Antes de empezar

Esta guía le ayudará a familiarizarse con la API de Reports. Para obtener información más detallada, consulte la página Visión general y Referencia API.

En este tema

Elija su enfoque

La Reports API ofrece dos métodos para recuperar sus registros de actividad, cada uno optimizado para diferentes patrones de consulta y volúmenes de datos.

Sincrónico (tiempo real)

El enfoque síncrono es el mejor para consultas frecuentes que recuperan hasta decenas de miles de registros. Cuando se realiza una solicitud sincrónica, los registros se devuelven inmediatamente en la respuesta de la API, lo que la hace ideal para cuadros de mando y sistemas de supervisión en tiempo real. Este método también permite realizar consultas por mensaje específico o ID de registro, lo que resulta útil cuando es necesario buscar transacciones individuales. Aunque es eficaz para conjuntos de datos pequeños, recomendamos limitar las consultas síncronas a miles de registros por solicitud para mantener un rendimiento óptimo.

Ejemplo de uso: Recuperar el estado de entrega de SMS de hoy para una campaña específica.

Asíncrono (procesamiento en segundo plano)

Para necesidades de datos mayores, el método asíncrono está diseñado para consultas poco frecuentes que necesitan recuperar millones de registros. En lugar de devolver los datos inmediatamente, este método genera un archivo ZIP descargable que contiene datos CSV mientras se procesan en segundo plano. El proceso de generación suele tardar entre 5 y 10 minutos por cada millón de registros. Puedes proporcionar una URL de devolución de llamada para recibir una notificación cuando finalice el procesamiento o consultar periódicamente el estado del informe. Para garantizar un rendimiento óptimo, Vonage recomienda limitar las consultas asincrónicas a un máximo de 7 millones de registros estableciendo fechas de inicio y finalización adecuadas.

Ejemplo de uso: Generar un informe mensual de todas las llamadas de voz.

Realizar la primera solicitud

Ejemplo de solicitud síncrona

Recuperar registros de SMS para un intervalo de fechas específico:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=YOUR_ACCOUNT_ID&product=SMS&direction=outbound&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

Ejemplo de solicitud asíncrona

Generar un informe de todos los mensajes enviados en diciembre:

curl -X POST "https://api.nexmo.com/v2/reports" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "product": "MESSAGES", "account_id": "YOUR_ACCOUNT_ID", "direction": "outbound", "date_start": "2025-12-01T00:00:00Z", "date_end": "2025-12-31T23:59:59Z", "callback_url": "https://your-domain.com/reports/callback" }'

Autenticación

Todas las solicitudes de Reports API requieren autenticación básica HTTP utilizando su clave y secreto de API:

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Sustituir $VONAGE_API_KEY y $VONAGE_API_SECRET con sus credenciales del Panel de Vonage.

Parámetros comunes

Estos parámetros se utilizan en la mayoría de las llamadas a la API de Reports:

Parámetro Requerido Descripción Ejemplo
account_id Tu clave API de Vonage (ID de cuenta) abcd1234
product El producto de Vonage a consultar SMS, MESSAGES, VOICE-CALL
date_start 🔸 Inicio del intervalo de fechas (formato ISO-8601) 2026-01-01T00:00:00Z
date_end 🔸 Fin del intervalo de fechas (formato ISO-8601) 2026-01-06T23:59:59Z
direction 🔸 Dirección del mensaje/llamada inbound o outbound
id 🔸 Mensaje específico o ID de registro (sólo sincronización) No puede utilizarse con intervalo de fechas

Leyenda: = Siempre obligatorio | 🔸 = Opcional o específico del producto

Requisitos de formato de fecha

Las fechas deben estar en formato ISO-8601:

  • Formato UTC: 2026-01-01T00:00:00Z
  • Con desfase horario: 2026-01-01T08:00:00+0800

Importante: Al utilizar GET solicitudes con + en fechas, codifica las fechas en URL:

curl -G --data-urlencode date_start="2026-01-01T08:00:00+0000" \ --data-urlencode date_end="2026-01-01T14:00:00+0000" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound"

Consulta por ID frente a intervalo de fechas

  • Por identificación: Recuperar un registro específico (sólo síncrono)
  • Por intervalo de fechas: Recuperar todos los registros dentro de un periodo de tiempo
  • No se pueden utilizar ambos: Elija id O date_start/date_endno ambos

Parámetros específicos del producto

Los distintos productos admiten parámetros diferentes. En esta sección se detallan los parámetros obligatorios y opcionales para cada producto. Para conocer las especificaciones completas de los parámetros y los formatos de respuesta, consulte la página Referencia API.

SMS

Parámetros obligatorios:

  • product - Ajustar a SMS
  • account_id - Tu clave API de Vonage
  • direction - Debe ser inbound o outbound

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • status - Filtrar por estado de entrega (por ejemplo, delivered, failed, expired)
  • from - Número del remitente
  • to - Número de beneficiario
  • country - Filtrar por código de país
  • network - Filtro por red MCC-MNC
  • client_ref - Su referencia de cliente
  • account_ref - Referencia de la Account
  • include_message - Incluir el cuerpo del mensaje en la respuesta (true/false)

Ejemplo:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound&status=delivered&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

SMS-CONTROL-DE-TRÁFICO

Parámetros obligatorios:

  • product - Ajustar a SMS-TRAFFIC-CONTROL
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

MENSAJES

Parámetros obligatorios:

  • product - Ajustar a MESSAGES
  • account_id - Tu clave API de Vonage
  • direction - Debe ser inbound o outbound

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • status - Filtrar por estado de entrega (por ejemplo, submitted, delivered, read, rejected)
  • from - Identificador del remitente
  • to - Identificador del destinatario
  • provider - Filtrar por canal (p. ej, whatsapp, sms, mms, viber_service_msg, messenger, instagram, rcs)
  • include_message - Incluir el cuerpo del mensaje en la respuesta (true/false)

LLAMADA POR VOZ

Parámetros obligatorios:

  • product - Ajustar a VOICE-CALL
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • direction - Dirección de llamada (inbound o outbound)
  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • status - Estado de la llamada (por ejemplo, ANSWERED, MACHINE, ERROR)
  • from - Número de llamada
  • to - Número llamado
  • country - Filtrar por código de país
  • network - Filtro por red MCC-MNC
  • call_id - Identificador de llamada específico

IN-APP-VOICE

Parámetros obligatorios:

  • product - Ajustar a IN-APP-VOICE
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • status - Estado de finalización de la llamada
  • conversation_id - Identificación de la conversación
  • leg_id - Tramo específico de una llamada

VOZ-TTS

Parámetros obligatorios:

  • product - Ajustar a VOICE-TTS
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

VOZ FALLIDA

Parámetros obligatorios:

  • product - Ajustar a VOICE-FAILED
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • direction - Dirección de llamada (inbound o outbound)
  • date_start / date_end - Intervalo de fechas para filtrar registros
  • from - Número de llamada
  • to - Número llamado
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • country - Filtro de código de país

WEBSOCKET-CALL

Parámetros obligatorios:

  • product - Ajustar a WEBSOCKET-CALL
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

ASR

Parámetros obligatorios:

  • product - Ajustar a ASR
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • direction - Dirección de llamada (inbound o outbound)
  • date_start / date_end - Intervalo de fechas para filtrar registros
  • from - Identificador de llamadas
  • to - Number called
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

AMD

Parámetros obligatorios:

  • product - Ajustar a AMD
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

VERIFY-API

Parámetros obligatorios:

  • product - Ajustar a VERIFY-API
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • to - Número de teléfono verificado
  • network - Filtro por red MCC-MNC

VERIFY-V2

Parámetros obligatorios:

  • product - Ajustar a VERIFY-V2
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • channel - Canal de verificación (v2, email, silent_auth)
  • status - Estado de la solicitud
  • parent_request_id - Filtro por ID de solicitud principal, que correlaciona las solicitudes de verificación v2 con sus eventos de correo electrónico o silent_auth asociados.
  • country - Código del país
  • locale - Idioma/Lugar
  • network - Código de red móvil
  • to - Número de teléfono verificado
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

VISIÓN DE LOS NÚMEROS

Parámetros obligatorios:

  • product - Ajustar a NUMBER-INSIGHT
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)
  • number - Número de teléfono consultado
  • network - Código de red móvil

NUMBER-INSIGHT-V2

Parámetros obligatorios:

  • product - Ajustar a NUMBER-INSIGHT-V2
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • request_type - Tipo de solicitud de insight (por ejemplo, fraud_score, sim_swap)
  • risk - Nivel de evaluación del riesgo
  • status- Numbers Estado de la solicitud Insight
  • swapped - Si el número ha sido portado/intercambiado
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

CONVERSACIÓN-ACONTECIMIENTO

Parámetros obligatorios:

  • product - Ajustar a CONVERSATION-EVENT
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • conversation_id - ID de conversación específica
  • status - Estado del evento
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

CONVERSACIÓN-MENSAJE

Parámetros obligatorios:

  • product - Ajustar a CONVERSATION-MESSAGE
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • conversation_id - ID de conversación específica
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

VIDEO-API

Parámetros obligatorios:

  • product - Ajustar a VIDEO-API
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • session_id - ID de la sesión de vídeo
  • meeting_id - Identificador de la reunión
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

EVENTO-API-RED

Parámetros obligatorios:

  • product - Ajustar a NETWORK-API-EVENT
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • product_name - Producto API de red específico
  • request_session_id - Identificador de sesión de la solicitud
  • product_path - Ruta del producto API
  • correlation_id - ID de correlación
  • request_type - Tipo de solicitud de API de red
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

INFORMES-USO

Parámetros obligatorios:

  • product - Ajustar a REPORTS-USAGE
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

  • date_start / date_end - Intervalo de fechas para filtrar registros
  • id - ID de registro específico (no puede utilizarse con intervalo de fechas)

Nota: Todos los productos son compatibles include_subaccounts al crear informes asíncronos para incluir datos de subcuentas. Para obtener información detallada sobre los formatos de respuesta y las opciones de filtrado adicionales, consulte la sección Referencia API.

Trabajar con informes asíncronos

Cuando cree un informe asíncrono, recibirá un mensaje request_id para seguir el estado del informe:

Ejemplo de respuesta:

{
  "request_id": "ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e",
  "request_status": "PENDING",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcd1234",
  "date_start": "2026-01-01T00:00:00+0000",
  "date_end": "2026-01-06T23:59:59+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"
    }
  }
}

Comprobar el estado del informe

Utiliza el request_id para comprobar si su informe está listo:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"

Descargar el informe completo

Cuando el estado del informe es SUCCESSextraiga el file_id de la respuesta y descarga:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v3/media/FILE_ID" \ -o report.zip

El archivo ZIP descargado contiene un CSV con sus registros. Los archivos están disponibles durante 72 horas.

Ver también