Saltar al contenido
Desarrolladores
6 min de lectura

Informes

Consulta el uso de mensajería y el costo de una sola cuenta o de todas las cuentas que posees, y descarga los mismos datos en CSV.

Compartir artículo

Los informes devuelven el uso de mensajería y el costo agregados. Hay dos endpoints de informes, más una descarga en CSV del informe por cuenta:

  • GET /report/accounts — uso agregado de todas las cuentas que posee el usuario autenticado.
  • GET /report/account/{account_id} — uso de una sola cuenta.
  • GET /report/account/{account_id}/download — los mismos datos por cuenta en un archivo CSV.

Ambos endpoints JSON aceptan los mismos parámetros de filtro y devuelven la misma estructura de respuesta.

Antes de empezar

  • El encabezado Authorization es obligatorio y debe llevar un token de acceso de Furcata.
  • GET /report/accounts no necesita un id de cuenta: informa sobre todas las cuentas que posees.
  • Los endpoints por cuenta reciben el id de la cuenta en la ruta.
  • Todas las marcas de tiempo son ISO-8601 con un desplazamiento UTC explícito. La API nunca infiere ni convierte zonas horarias: convierte el día local de quien llama a UTC antes de enviar.

Consultar el uso de todas las cuentas

GET /report/accounts devuelve el uso de todas las cuentas que posee el usuario autenticado. El ejemplo siguiente cubre un día UTC completo usando los límites de liquidación from y to.

curl --request GET \
  --url 'https://api.furcata.com/v0/report/accounts?from=2026-09-21T00%3A00%3A00.000Z&to=2026-09-21T23%3A59%3A59.999Z' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN'
{
  "timestamp": "2026-09-21T23:59:59.999Z",
  "eventsByType": {
    "sms": 42,
    "mms": 3
  },
  "total": 45,
  "inbound": 12,
  "outbound": 33,
  "rate": 0.0079,
  "credits": 45,
  "units": 45,
  "cost": 3.55
}

Campos de la respuesta

  • timestamp — fecha y hora en que se generó el informe.
  • eventsByType — objeto con clave por tipo de evento, donde cada valor es el conteo de ese tipo.
  • total — número total de eventos en la ventana.
  • inbound — eventos recibidos.
  • outbound — eventos enviados.
  • rate — tarifa aplicada al uso en la ventana.
  • credits — créditos consumidos.
  • units — unidades facturables.
  • cost — costo de la ventana.
  • raw — datos CSV del mismo conjunto de resultados.

Consultar el uso de una cuenta

GET /report/account/{account_id} recibe el id de la cuenta en la ruta y los mismos filtros, y devuelve la misma estructura de respuesta que GET /report/accounts.

curl --request GET \
  --url 'https://api.furcata.com/v0/report/account/acc_123?direction=outbound&type=sms' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN'

Parámetros de filtro

Todos los parámetros de filtro son parámetros de consulta opcionales. Los dos endpoints JSON de informes aceptan el mismo conjunto.

  • from — límite inferior de liquidación, inclusive. Marca de tiempo ISO-8601 con un desplazamiento UTC explícito (usa Z). Para cubrir un día UTC completo, define este valor como el primer instante de ese día, por ejemplo 2026-09-21T00:00:00.000Z.
  • to — límite superior de liquidación, inclusive. Para cubrir un día UTC completo, define este valor como el último instante de ese día, por ejemplo 2026-09-21T23:59:59.999Z, y no la medianoche del día siguiente, porque este límite es inclusivo.
  • created — ventana de creación. Puede ser una marca de tiempo ISO-8601, usada como límite inferior inclusivo, o dos marcas de tiempo separadas por comas para un rango semiabierto [from, to). Repetir el parámetro equivale a la forma con comas.
  • direction — inbound u outbound.
  • type — uno de message, sms, mms, voice, voicemail, call, whatsapp, action, unsubscribe, post.
  • country — código de país ISO 3166-1 alfa-2 de dos letras, normalizado a mayúsculas.
  • language — código de idioma ISO 639-1 de dos letras, por ejemplo en o es.
  • sentiment.text — uno de clearly_positive, positive, neutral, mixed, negative, clearly_negative, unknown.
  • contact — id del documento de contacto.
  • service — id del servicio.
  • filters — una carga opaca de filtros en base64 que lleva los mismos filtros que los parámetros planos. Se decodifica y se revalida contra el esquema idéntico, y cuando está presente reemplaza cualquier copia plana de un filtro que contenga. from y to no pueden aparecer dentro de ella y se mantienen en el nivel superior. Codifica el valor con porcentaje: un + sin codificar llega como un espacio y no se puede decodificar.

Los límites son inclusivos y se basan en UTC

from y to son límites de liquidación inclusivos. Define to como el último instante del día que quieres (23:59:59.999), no la medianoche del día siguiente, o la ventana incluirá un instante extra. Convierte el día local de quien llama a UTC antes de enviar, porque la API nunca infiere ni convierte zonas horarias.

Descargar un informe en CSV

GET /report/account/{account_id}/download genera un archivo text/csv para una cuenta. Acepta los mismos filtros que los endpoints JSON de informes.

  • 200 — el archivo CSV del informe.
  • 204 — no hay datos disponibles para los filtros que enviaste.
curl --request GET \
  --url 'https://api.furcata.com/v0/report/account/acc_123/download?from=2026-09-01T00%3A00%3A00.000Z&to=2026-09-30T23%3A59%3A59.999Z' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN' \
  --output report.csv

Errores

  • 400 — un valor de filtro no pasó la validación, o no se pudo decodificar una carga opaca de filtros.
  • 401 — falta el encabezado Authorization o el token no es válido.
  • 403 — quien llama no tiene permiso para leer la cuenta solicitada.
  • 429 — demasiadas peticiones. Consulta Límites de peticiones.

Todos los errores usan la envoltura descrita en Errores e idempotencia.