Uso por merchant
Devolve quantos alertas cobráveis cada merchant da sua empresa teve num ciclo de cobrança: o atual, ainda aberto, ou um já fechado. São só contagens; os valores da fatura ficam no painel, em Configurações › Cobrança.
Endpoint
Seção intitulada “Endpoint”GET
https://api.rapidchargeback.com/api/v1/usage/merchantsAutenticação
Seção intitulada “Autenticação”Authorization: Basic base64(client_id:client_secret)Query params
Seção intitulada “Query params”Todos opcionais. Parâmetro fora desta tabela é recusado com 422 VALIDATION_ERROR (Unknown field: <nome>).
| Param | Tipo | Default | Descrição |
|---|---|---|---|
cycle | string | current | current (ciclo em andamento), previous (último ciclo fechado) ou YYYY-MM (o ciclo fechado que começou nesse mês) |
merchant_id | string (UUID) | - | Só esse merchant |
merchant_ref | string (até 100) | - | Só o merchant com essa referência do seu sistema |
page | int (≥ 1) | 1 | Página |
per_page | int (1–100) | 20 | Itens por página |
- O ciclo vai do dia de fechamento da sua empresa até a véspera do fechamento seguinte, contado em UTC.
YYYY-MMdo ciclo em andamento vale comocurrent. Mês futuro:422 VALIDATION_ERROR“cycle cannot be in the future”. Mês sem ciclo fechado:404 USAGE_CYCLE_NOT_FOUND.
Exemplo de requisição
Seção intitulada “Exemplo de requisição”curl -G "https://api.rapidchargeback.com/api/v1/usage/merchants" \ --data-urlencode "cycle=previous" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Resposta
Seção intitulada “Resposta”Sucesso
Seção intitulada “Sucesso”{ "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 | Descrição |
|---|---|
merchant_id, merchant_ref, name | O merchant. null nos três na linha dos alertas sem merchant identificado, que vem por último |
billable_alerts | Alertas cobráveis do merchant no ciclo |
meta.cycle_start, meta.cycle_end | Primeiro e último dia do ciclo (YYYY-MM-DD, o último incluído) |
meta.cycle_status | open (ciclo em andamento: prévia, muda até o fechamento) ou closed |
meta.totals.billable_alerts | Total do ciclo, somando todas as páginas |
meta.generated_at | Quando a contagem foi feita |
A ordem é do merchant com mais alertas para o com menos.
Ciclo não encontrado
Seção intitulada “Ciclo não encontrado”HTTP/1.1 404 Not Found{ "error": { "code": "USAGE_CYCLE_NOT_FOUND", "message": "No closed billing cycle starts in this month" }}| HTTP | Código | Quando |
|---|---|---|
| 422 | VALIDATION_ERROR | cycle em outro formato ou no futuro, parâmetro desconhecido (params.field) |
| 404 | USAGE_CYCLE_NOT_FOUND | Nenhum ciclo fechado começa no mês pedido (ou ainda não há ciclo fechado, em previous) |
| 429 | RATE_LIMIT_EXCEEDED | Mais de 10 consultas por minuto |
| 403 | COMPANY_BLOCKED | Empresa bloqueada |
| 503 | SERVICE_UNAVAILABLE | Indisponibilidade temporária: repita depois do Retry-After |
- Números de até 5 minutos atrás. A contagem é refeita no máximo a cada 5 minutos;
generated_atdiz quando foi feita, e todas as páginas da mesma consulta saem da mesma contagem. - Ciclo aberto é prévia: a contagem do ciclo em andamento pode mudar até o fechamento.
- 10 consultas por minuto por empresa, contadas à parte das escritas.
- Auth, rate limit, códigos de erro: ver Autenticação e Códigos de resposta.