Uso por merchant
Devuelve cuántas alertas facturables tuvo cada merchant de tu empresa en un ciclo de facturación: el actual, todavía abierto, o uno ya cerrado. Son solo conteos; los valores de la factura están en el panel, en Configuración › Facturación.
Endpoint
Sección titulada «Endpoint»GET
https://api.rapidchargeback.com/api/v1/usage/merchantsAutenticación
Sección titulada «Autenticación»Authorization: Basic base64(client_id:client_secret)Query params
Sección titulada «Query params»Todos opcionales. Un parámetro fuera de esta tabla se rechaza con 422 VALIDATION_ERROR (Unknown field: <nombre>).
| Param | Tipo | Default | Descripción |
|---|---|---|---|
cycle | string | current | current (ciclo en curso), previous (último ciclo cerrado) o YYYY-MM (el ciclo cerrado que empezó en ese mes) |
merchant_id | string (UUID) | - | Solo ese merchant |
merchant_ref | string (hasta 100) | - | Solo el merchant con esa referencia de tu sistema |
page | int (≥ 1) | 1 | Página |
per_page | int (1–100) | 20 | Ítems por página |
- El ciclo va del día de cierre de tu empresa hasta la víspera del cierre siguiente, contado en UTC.
YYYY-MMdel ciclo en curso vale comocurrent. Mes futuro:422 VALIDATION_ERROR“cycle cannot be in the future”. Mes sin ciclo cerrado:404 USAGE_CYCLE_NOT_FOUND.
Ejemplo de solicitud
Sección titulada «Ejemplo de solicitud»curl -G "https://api.rapidchargeback.com/api/v1/usage/merchants" \ --data-urlencode "cycle=previous" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Respuesta
Sección titulada «Respuesta»{ "data": [ { "merchant_id": "00000000-0000-0000-0000-000000000001", "merchant_ref": "PB-1001", "name": "Loja Exemplo", "billable_alerts": 42 }, { "merchant_id": null, "merchant_ref": null, "name": null, "billable_alerts": 3 } ], "meta": { "cycle_start": "2026-11-01", "cycle_end": "2026-11-30", "cycle_status": "closed", "totals": { "billable_alerts": 45 }, "generated_at": "2026-12-02T14:00:00.000Z", "page": 1, "per_page": 100, "total": 2, "total_pages": 1 }}| Campo | Descripción |
|---|---|
merchant_id, merchant_ref, name | El merchant. null en los tres en la línea de las alertas sin merchant identificado, que viene al final |
billable_alerts | Alertas facturables del merchant en el ciclo |
meta.cycle_start, meta.cycle_end | Primer y último día del ciclo (YYYY-MM-DD, el último incluido) |
meta.cycle_status | open (ciclo en curso: vista previa, cambia hasta el cierre) o closed |
meta.totals.billable_alerts | Total del ciclo, sumando todas las páginas |
meta.generated_at | Cuándo se hizo el conteo |
El orden va del merchant con más alertas al que tiene menos.
Ciclo no encontrado
Sección titulada «Ciclo no encontrado»HTTP/1.1 404 Not Found{ "error": { "code": "USAGE_CYCLE_NOT_FOUND", "message": "No closed billing cycle starts in this month" }}Errores
Sección titulada «Errores»| HTTP | Código | Cuándo |
|---|---|---|
| 422 | VALIDATION_ERROR | cycle en otro formato o en el futuro, parámetro desconocido (params.field) |
| 404 | USAGE_CYCLE_NOT_FOUND | Ningún ciclo cerrado empieza en el mes pedido (o todavía no hay ciclo cerrado, en previous) |
| 429 | RATE_LIMIT_EXCEEDED | Más de 10 consultas por minuto |
| 403 | COMPANY_BLOCKED | Empresa bloqueada |
| 503 | SERVICE_UNAVAILABLE | No disponible temporalmente: repite después del Retry-After |
- Números de hasta 5 minutos atrás. El conteo se rehace como máximo cada 5 minutos;
generated_atdice cuándo se hizo, y todas las páginas de la misma consulta salen del mismo conteo. - El ciclo abierto es vista previa: el conteo del ciclo en curso puede cambiar hasta el cierre.
- 10 consultas por minuto por empresa, contadas aparte de las escrituras.
- Auth, rate limit, códigos de error: ver Autenticación y Códigos de respuesta.