Reports API

Cuando utiliza nuestras API de comunicación, se crean dos tipos de registros: registros del servidor y registros detallados de llamadas (CDR), es decir, registros transaccionales de la actividad. La Reports API le permite descargar sus CDR. Puede filtrar sus CDR en función de atributos como números de teléfono de origen y destino, estado, periodo de tiempo, etc. Consulte la lista de parámetros admitidos. Puede incluir el cuerpo del mensaje/texto y descargar informes para cualquiera de sus subcuentas.

Puede utilizar la API de Reports en una amplia variedad de casos de uso, entre los que se incluyen:

Facturación a clientes: descargue las transacciones relacionadas con todas sus subcuentas y utilice los datos de precios incluidos para determinar lo que debe facturar a sus clientes.
Conciliación de facturas: compare sus datos de uso con la factura que ha recibido.
Supervisión y análisis: añada datos CDR en tiempo real a su sistema de inteligencia o análisis empresarial para correlacionarlos con otros eventos.
Gestión de campañas: controle el rendimiento de su campaña mediante herramientas de autoservicio.
Depuración: solucione problemas explorando hasta 13 meses de datos de uso detallados.
Prevención del fraude - Identifique el fraude y controle los patrones para bloquear a los usuarios que utilicen el Defensor del Fraude producto.

Puede consultar sus CDR utilizando una amplia gama de filtros. Los registros de datos se conservan durante trece meses (periodo máximo de conservación) o 90 días para Video API. Los registros de más de trece meses (o 90 días para Video API) no se pueden obtener porque se borran automáticamente del sistema.

Funcionamiento síncrono y asíncrono

Dependiendo de su patrón de consulta, puede elegir uno de los dos enfoques para la Reports API:

Sincrónico
Asíncrono

En síncrono está optimizada para consultas frecuentes y periódicas de pequeños lotes de registros de datos. Los tamaños típicos de los lotes oscilan entre un registro y decenas de miles por consulta.

En asíncrono está optimizada para consultas de datos poco frecuentes y de gran tamaño. Los tamaños de lote habituales oscilan entre varios miles y millones de registros.

Resumen de características

En la siguiente tabla se comparan las características de los métodos síncrono y asíncrono de utilización de la API de Reports:

Característica	Informes sincrónicos (punto final GET)	Informes Asíncronos (POST endpoint)
Recuperación de datos	Devuelve resultados inmediatamente en lotes de hasta 1000 registros. La respuesta contiene un lote de registros de datos y un enlace al siguiente lote (si lo hay)	No devuelve los datos inmediatamente. En su lugar, registra una solicitud de datos, la procesa de forma asíncrona y crea un archivo que contiene todos los registros. Cuando el fichero de resultados está listo, devuelve un enlace al fichero
Formato de salida	JSON	CSV
Compresión	No aplicable	El archivo CSV está comprimido para una descarga más rápida
Informe TTL	No aplicable	Los archivos de los informes se borran automáticamente al cabo de 72 horas
Filtro de tiempo	Puede recuperar hasta 13 meses (periodo máximo de conservación) de datos en una consulta (90 días para Video API)	Puede recuperar hasta 13 meses (periodo máximo de conservación) de datos en una consulta (90 días para Video API)
Filtro ID	Puede buscar un registro de datos por su ID	No admite filtrado de ID
Cuerpo del mensaje	Puede recuperar el cuerpo del mensaje	Puede recuperar el cuerpo del mensaje
Subaccounts	Requiere una solicitud distinta para cada subaccounts	Requiere una solicitud de informe. Agrupa automáticamente en un informe los registros de datos pertenecientes a subcuentas.
Devoluciones de llamada	No aplicable	Se puede generar una llamada de retorno HTTP(S) POST para notificar la finalización del informe.

Nota sobre el rendimiento: Aunque la API de Reports es rápida y puede tratar enormes cantidades de datos, puede volverse más lenta al intentar descargar datos para análisis en tiempo real. El uso de filtros sensibles puede acelerar considerablemente el procesamiento.

Productos compatibles

SMS API
Messages API:
- SMS/MMS
- RCS
- WhatsApp
- Viber
- Instagram
- Mensajero
Voice API:
- SIP
- RTPC
- WebRTC
- ASR
- TTS
- AMD
Video API
Conversation API
Verificar API
Entender los Numbers
Reports API
API de red (con el nombre de producto NETWORK_API-EVENT):
- API de intercambio de SIM
- API de Identity Insights

Precios

Para consultar los precios, visite esta página. Los valores de los precios incluidos en los ejemplos que figuran a continuación son meramente ilustrativos.

Ejemplo de fijación de precios (`GET` solicitudes)

Supongamos que desea recuperar los registros de SMS del último minuto, y resulta que hay 300 registros en este periodo de tiempo. El coste total de este informe será el siguiente:

Charge = 300 * 0.0004€ = 0.12€

GET Las solicitudes (crear y obtener informe JSON) pueden devolver registros por ID o por un periodo de tiempo al que pertenezcan. La búsqueda por ID no está limitada en el tiempo. La búsqueda por periodo de tiempo admite rangos de hasta 24 horas.

Ejemplo de fijación de precios (`POST` solicitudes)

Supongamos que crea un informe SMS para recuperar un día de datos y este informe contiene 10.000 CDR, entonces el cargo total por este informe será el siguiente:

Charge = 10,000 * 0.0004€ = 4€

¿Cómo puede comprobar el uso de su Reports API?

Puede comprobar el uso de su Reports API cargando registros de forma sincrónica o creando un informe de forma asincrónica para el producto "REPORTS-USAGE".

Nota: Esta función puede utilizarse sin coste adicional.

Recuperar registros de forma sincrónica

Utilice una solicitud HTTP GET para recuperar esta información:

curl --location --request GET 'https://api.nexmo.com/v2/reports/records?account_id=<API-KEY>&product=REPORTS-USAGE&date_start=YYYY-MM-DDTHH:MM:SSZ&date_end=YYYY-MM-DDTHH:MM:SSZ' --header 'Authorization: Basic <basic auth hash>='

Recibirá una respuesta similar a la que figura a continuación. En "items_count": 3 indica que se extrajeron 3 informes durante el periodo de búsqueda.

{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?account_id=<API-KEY>&product=REPORTS-USAGE&date_start=YYYY-MM-DDTHH%3AMM%3ASSZ&date_end=YYYY-MM-DDTHH%3AMM%3ASSZ"
    }
  },
  "request_id": "555042c5-368a-4fd2-b983-f24197692bac",
  "request_status": "SUCCESS",
  "received_at": "2021-10-07T09:08:58+00:00",
  "price": 0.0,
  "currency": "",
  "limit": 1000,
  "items_count": 3,
  "include_subaccounts": false,
  "records": [
    ...
  ],
  "product": "REPORTS-USAGE",
  "account_id": "<API-KEY>",
  "date_start": "2021-10-06T00:00:00+00:00",
  "date_end": "2021-10-07T23:59:00+00:00",
  "endpoint_type": "PUBLIC"
}

Recuperar registros de forma asíncrona

Los registros se pueden recuperar de forma asíncrona creando un informe asíncrono y estableciendo la opción product a "REPORTS-USAGE". El siguiente ejemplo muestra cómo crear un informe asíncrono:

curl -X POST https://api.nexmo.com/v2/reports/ \ -u $API_KEY:$API_SECRET \ -H "Content-Type: application/json" \ -d '{"account_id": "API_KEY","product": "REPORTS-USAGE","direction": "outbound","date_start": "2024-06-01T00:00:00+0000","date_end": "2024-07-01T00:00:00+0000"}'

Para más información crear un informe CSV utilizando la línea de comandos página.

Fragmentos de código

Tutoriales

Referencia API

Referencia de la API Reports