# Uso por merchant

> Quantos alertas cobráveis cada merchant da sua empresa teve no ciclo de cobrança atual ou num ciclo fechado. Só contagens.

Página: https://doc.rapidchargeback.com/canais/uso/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

```
GET https://api.rapidchargeback.com/api/v1/usage/merchants
```

## Autenticação

```
Authorization: Basic base64(client_id:client_secret)
```

---

## 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-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`.

---

## Exemplo de requisição

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

---

## Resposta

### Sucesso

```json
{
  "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

```
HTTP/1.1 404 Not Found
```

```json
{
  "error": {
    "code": "USAGE_CYCLE_NOT_FOUND",
    "message": "No closed billing cycle starts in this month"
  }
}
```

### Erros

| 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` |

---

## Notas

- **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](https://doc.rapidchargeback.com/referencia/autenticacao/) e [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/).
