Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

GET https://api.rapidchargeback.com/api/v1/usage/merchants
Authorization: Basic base64(client_id:client_secret)

Todos opcionais. Parâmetro fora desta tabela é recusado com 422 VALIDATION_ERROR (Unknown field: <nome>).

ParamTipoDefaultDescrição
cyclestringcurrentcurrent (ciclo em andamento), previous (último ciclo fechado) ou YYYY-MM (o ciclo fechado que começou nesse mês)
merchant_idstring (UUID)-Só esse merchant
merchant_refstring (até 100)-Só o merchant com essa referência do seu sistema
pageint (≥ 1)1Página
per_pageint (1–100)20Itens por página
  • O ciclo vai do dia de fechamento da sua empresa até a véspera do fechamento seguinte, contado em UTC.
  • YYYY-MM do ciclo em andamento vale como current. Mês futuro: 422 VALIDATION_ERROR “cycle cannot be in the future”. Mês sem ciclo fechado: 404 USAGE_CYCLE_NOT_FOUND.

Janela do terminal
curl -G "https://api.rapidchargeback.com/api/v1/usage/merchants" \
--data-urlencode "cycle=previous" \
--data-urlencode "per_page=100" \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="

{
"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
}
}
CampoDescrição
merchant_id, merchant_ref, nameO merchant. null nos três na linha dos alertas sem merchant identificado, que vem por último
billable_alertsAlertas cobráveis do merchant no ciclo
meta.cycle_start, meta.cycle_endPrimeiro e último dia do ciclo (YYYY-MM-DD, o último incluído)
meta.cycle_statusopen (ciclo em andamento: prévia, muda até o fechamento) ou closed
meta.totals.billable_alertsTotal do ciclo, somando todas as páginas
meta.generated_atQuando a contagem foi feita

A ordem é do merchant com mais alertas para o com menos.

HTTP/1.1 404 Not Found
{
"error": {
"code": "USAGE_CYCLE_NOT_FOUND",
"message": "No closed billing cycle starts in this month"
}
}
HTTPCódigoQuando
422VALIDATION_ERRORcycle em outro formato ou no futuro, parâmetro desconhecido (params.field)
404USAGE_CYCLE_NOT_FOUNDNenhum ciclo fechado começa no mês pedido (ou ainda não há ciclo fechado, em previous)
429RATE_LIMIT_EXCEEDEDMais de 10 consultas por minuto
403COMPANY_BLOCKEDEmpresa bloqueada
503SERVICE_UNAVAILABLEIndisponibilidade 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_at diz 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.