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

# Listar comercios

> Obtén una lista paginada de comercios con su estado de verificación KYC, sus límites de transacción diarios y mensuales y su uso actual.

Usa este endpoint para consultar los comercios registrados en tu cuenta. Puedes filtrar por nombre, correo electrónico o estado de verificación, y paginar los resultados. La respuesta incluye el estado KYC de cada comercio, sus límites de transacción diarios y mensuales y su uso actual, lo que resulta útil para monitorear el margen disponible de cumplimiento.

> [!NOTE]
>
> Todas las solicitudes deben incluir el header `X-BH-TOKEN` con un token de negocio obtenido de `GET /v2/token/generate`.

## Endpoint

`GET https://api.velafi.com/v2/merchants`

## Parámetros de consulta

**merchantName** `string`

Filtra los resultados por nombre del comercio (admite coincidencia parcial).

**email** `string`

Filtra los resultados por la dirección de correo electrónico del comercio.

**status** `integer`

Filtra por estado de verificación KYC/KYB:

* `-1` — todos los estados
* `1` — en autenticación
* `2` — normal (predeterminado)
* `3` — autenticación fallida
* `4` — incompleto

**currentPage** `integer`

Número de página a obtener (empieza en 1). El valor predeterminado es `1`.

**pageSize** `integer`

Número de registros por página. El valor predeterminado es `10` y el máximo es `1000`.

## Campos de la respuesta

**code** `number`

Código de respuesta de estilo HTTP. `200` indica éxito.

**msg** `string`

Mensaje de estado legible, por ejemplo `SUCCESS`.

**data** `object`

**campos de data**

**currentPage** `number`

El número de la página actual devuelta.

**size** `number`

Número de registros devueltos en esta página.

**total** `number`

Número total de comercios que coinciden con la consulta.

**record** `array`

**campos de cada elemento de record**

**merchantId** `number`

Identificador único del comercio.

**country** `string`

País del comercio.

**merchantName** `string`

Nombre visible del comercio.

**email** `string`

Dirección de correo electrónico del comercio.

**merchantType** `number`

Tipo de comercio: `1` = INDIVIDUAL, `2` = BUSINESS.

**status** `number`

Estado KYC/KYB: `1` = en autenticación, `2` = normal, `3` = fallido, `4` = incompleto.

**rejectReason** `string`

Motivo proporcionado si se rechazó la verificación KYC/KYB.

**upgradeMerchantLimitStatus** `number`

Estado de cualquier solicitud pendiente de aumento de límite: `1` = en autenticación, `2` = normal, `3` = fallido, `4` = incompleto.

**upgradeMerchantLimitRejectReason** `string`

Motivo de rechazo de una solicitud de aumento de límite, si aplica.

**dayFiatLimit** `number`

Monto fiat máximo que el comercio puede operar por día.

**dayFiatUsed** `number`

Monto fiat consumido del límite diario en lo que va del día.

**monthFiatLimit** `number`

Monto fiat máximo que el comercio puede operar por mes calendario.

**monthFiatUsed** `number`

Monto fiat consumido del límite mensual en el mes en curso.

**monthCryptoLimit** `number`

Equivalente cripto máximo (en USD) que el comercio puede operar por mes.

**monthCryptoUsed** `number`

Equivalente cripto consumido del límite cripto mensual.

**remark** `string`

Comentario de texto libre adjunto al registro del comercio.

**createTime** `string`

Marca de tiempo Unix (milisegundos) de cuando se creó el comercio.

**updateTime** `string`

Marca de tiempo Unix (milisegundos) de la última actualización del registro del comercio.

## Ejemplo

```bash cURL theme={null}
curl -G https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "status=-1" \
  --data-urlencode "currentPage=1" \
  --data-urlencode "pageSize=10"
```

```json Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "currentPage": 1,
    "size": 10,
    "total": 100,
    "record": [
      {
        "merchantId": 1,
        "country": "Mexico",
        "merchantName": "Example Merchant",
        "email": "merchant@example.com",
        "merchantType": 1,
        "status": 2,
        "rejectReason": "",
        "upgradeMerchantLimitStatus": 2,
        "upgradeMerchantLimitRejectReason": "",
        "dayFiatLimit": 25000.0,
        "dayFiatUsed": 0.0,
        "monthFiatLimit": 25000.0,
        "monthFiatUsed": 0.0,
        "monthCryptoLimit": 15000.0,
        "monthCryptoUsed": 0.0,
        "remark": "",
        "createTime": "1737452292000",
        "updateTime": "1737452344000"
      }
    ]
  }
}
```

> [!NOTE]
>
> Usa `status=-1` para obtener comercios en todas las etapas de KYC, incluidos los que fallaron o siguen en proceso.


## Related topics

- [Comercios](https://docs.velafi.com/es/docs/merchants.md)
- [Solicitar un aumento de límite](https://docs.velafi.com/es/api-reference/merchant/upgrade-merchant-limit.md)
- [Listar cuentas de comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md)
- [Listar beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md)
- [Listar cuentas virtuales](https://docs.velafi.com/es/api-reference/merchant/get-multiple-virtual-account.md)


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