# Uso por merchant

> Cuántas alertas facturables tuvo cada merchant de tu empresa en el ciclo de facturación actual o en un ciclo cerrado. Solo conteos.

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

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

## Autenticación

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

---

## 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-MM` del ciclo en curso vale como `current`. Mes futuro: `422 VALIDATION_ERROR` "cycle cannot be in the future". Mes sin ciclo cerrado: `404 USAGE_CYCLE_NOT_FOUND`.

---

## Ejemplo de solicitud

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

---

## Respuesta

### Éxito

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

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

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

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

---

## Notas

- **Números de hasta 5 minutos atrás.** El conteo se rehace como máximo cada 5 minutos; `generated_at` dice 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](https://doc.rapidchargeback.com/es/referencia/autenticacao/) y [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/).
