Uso y cuotas

GET /platform/dashboard/usage devuelve el uso por canal + los totales por cuenta + las cuotas del plan para el período de facturación vigente. Es la fuente que el dashboard usa para pintar las barras de cuota y la tabla por canal.

Autenticación

Cookie-JWT del dashboard ÚNICAMENTE. El endpoint usa el mismo session cookie (access_token_dev) que setea POST /platform/dashboard/login, igual que GET /platform/dashboard/me.

No expuesto a API keys programáticas. Si más adelante necesitás leer el uso desde un servicio tuyo via X-API-Key, hace falta un scope read:usage dedicado, está fuera de alcance en la primera versión. Para el dashboard alcanza con la sesión cookie.

Período

El campo period es el período al que pertenecen los counters:

YYYY-MM (calendario UTC) para cuentas free / sin anclaje de Polar.
YYYY-MM-DD (aniversario Polar) una vez que tu suscripción tiene su ciclo anclado.

El resolver es services.platform_metering._account_period, el mismo que usa el volcado a platform_usage y el chequeo de cuota entrante. Los counters se itemizan por canal vía Redis (con fallback durable a platform_usage si Redis está caído).

Response 200

{
  "period": "2026-06",
  "plan_code": "free",
  "inbound_limit": 200,
  "template_limit": 0,
  "max_channels": 1,
  "total_msgs_in": 12,
  "total_msgs_out": 7,
  "total_templates_sent": 0,
  "active_channels": 1,
  "channels": [
    {
      "channel_id": 42,
      "meta_identifier": "1234567890",
      "channel_type": "whatsapp",
      "msgs_in": 12,
      "msgs_out": 7,
      "templates_sent": 0
    }
  ]
}

Campos

Campo	Tipo	Descripción
`period`	`string`	Período de los counters (ver arriba).
`plan_code`	`string`	Tu plan actual (`free` / `lite` / `pro` / `business`).
`inbound_limit`	`integer \| null`	Cupo mensual de mensajes entrantes. `null` = ilimitado.
`template_limit`	`integer \| null`	Cupo mensual de templates enviados. `null` = ilimitado.
`max_channels`	`integer \| null`	Cupo de canales conectados. `null` = ilimitado.
`total_msgs_in`	`integer`	Suma de inbound entre todos tus canales para `period`.
`total_msgs_out`	`integer`	Suma de outbound.
`total_templates_sent`	`integer`	Suma de templates enviados.
`active_channels`	`integer`	Cantidad de canales con `status="active"` (el dashboard lo compara contra `max_channels`).
`channels[]`	`ChannelUsage[]`	Detalle por canal (más nuevo primero). Aparecen TODOS los canales, no solo los activos.
`channels[].msgs_in` / `msgs_out` / `templates_sent`	`integer`	Counters per canal (Redis-first con fallback durable).

Cuotas del plan

Plan	Inbound/mes	Templates/mes	Canales
Free	200	0	1
Lite	∞	1.000	2
Pro	∞	10.000	5
Business	∞	∞	∞

null en inbound_limit / template_limit / max_channels significa ilimitado: el dashboard lo renderiza como “Ilimitado”.

Consistencia

El endpoint es read-only y eventualmente consistente. Los counters en vivo son los de Redis; platform_usage (la fuente durable) se reconcilia cada 60s por el job platform_usage_flush. Si Redis está caído, el endpoint cae automáticamente sobre platform_usage y devuelve la última foto durable, y nunca crashea por una caída transitoria de Redis.

No uses este endpoint para controlar la facturación en tiempo real. Para eso está el 429 con template quota exceeded del endpoint de envío. Esto es una vista de uso, no un control.

Status codes

Code	Trigger
`200 OK`	Sesión válida, cuenta encontrada.
`401 Unauthorized`	No hay cookie de sesión o es inválida.
`404 Not Found`	La cuenta resuelta por la cookie no existe (race entre logout/borrado).