> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Buscar grupos de cuentas por ID de comercio

> Busca grupos de cuentas usando un identificador del lado del comercio en lugar de un ID de grupo de Yuno

Devuelve todos los grupos de cuentas de la organización autenticada que tengan el `merchant_id` indicado. Usa este endpoint para ubicar los registros de grupo de Yuno con el identificador que ya existe de tu lado, sin tener que almacenar ni consultar los IDs de grupo generados por Yuno.

> [!NOTE]
>
> **Coincidencias múltiples y resultados vacíos**
>
> No se garantiza que un `merchant_id` sea único: más de un grupo puede compartir el mismo valor. Se devuelven todos los grupos que coinciden. Cuando ningún grupo tiene el `merchant_id` solicitado, la respuesta contiene un arreglo `data` vacío en lugar de un error. Los grupos eliminados nunca se incluyen.


## OpenAPI

````yaml openapi/es/organizations/find-account-groups-by-merchant-id.json GET /organizations/account-groups
openapi: 3.1.0
info:
  title: Account Groups API - Find by Merchant ID
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /organizations/account-groups:
    get:
      summary: Buscar grupos de cuentas por ID de comercio
      description: >-
        Devuelve todos los grupos de cuentas que coinciden con el `merchant_id`
        indicado. Como no se garantiza que un ID de comercio sea único, se
        devuelven todos los grupos que coinciden. Cuando ningún grupo tiene ese
        ID de comercio, la respuesta contiene un arreglo `data` vacío: no es un
        error. Solo se devuelven los grupos que pertenecen a la organización
        autenticada; los grupos eliminados se excluyen.
      operationId: find-account-groups-by-merchant-id
      parameters:
        - name: merchant_id
          in: query
          required: true
          schema:
            type: string
          description: >-
            El identificador del lado del comercio que se desea buscar. Debe ser
            una coincidencia exacta.
      responses:
        '200':
          description: 'OK: cero o más grupos de cuentas coincidentes.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: >-
                      Lista de grupos de cuentas que tienen el merchant_id
                      solicitado. Está vacía cuando no hay coincidencias.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: >-
                            Identificador único del grupo de cuentas generado
                            por Yuno.
                        name:
                          type: string
                          description: Nombre visible del grupo de cuentas.
                        merchant_id:
                          type: string
                          description: >-
                            Identificador del lado del comercio almacenado en
                            este grupo.
                        parent_code:
                          type:
                            - string
                            - 'null'
                          format: uuid
                          description: >-
                            El `id` del grupo bajo el cual se anida este grupo.
                            `null` para un grupo raíz (de nivel superior).
                        created_at:
                          type: string
                          format: date-time
                          description: Marca de tiempo ISO 8601 de la creación del grupo.
                        updated_at:
                          type: string
                          format: date-time
                          description: Marca de tiempo ISO 8601 de la última actualización.
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_items:
                        type: integer
                      total_pages:
                        type: integer
                      has_next:
                        type: boolean
                      has_previous:
                        type: boolean
              examples:
                match_found:
                  summary: One group matched
                  value:
                    data:
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        name: Acme Corp - LATAM
                        merchant_id: MCH-00123
                        parent_code: null
                        created_at: '2024-03-15T10:00:00Z'
                        updated_at: '2024-06-01T08:30:00Z'
                    pagination:
                      page: 1
                      page_size: 20
                      total_items: 1
                      total_pages: 1
                      has_next: false
                      has_previous: false
                no_match:
                  summary: No group matched — empty result
                  value:
                    data: []
                    pagination:
                      page: 1
                      page_size: 20
                      total_items: 0
                      total_pages: 0
                      has_next: false
                      has_previous: false
        '400':
          description: >-
            Solicitud incorrecta: el parámetro de consulta `merchant_id` falta o
            está en blanco.
        '401':
          description: 'No autorizado: las credenciales de la API no son válidas o faltan.'
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      x-default: <Your PUBLIC-API-KEY>
    sec1:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      x-default: <Your PRIVATE-SECRET-KEY>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.