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

Elige tu 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.

Cómo realizar tu primera solicitud

Ejemplo de solicitud síncrona

Recuperar registros de SMS correspondientes a un intervalo de fechas concreto:

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

Genera un informe con 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 a la Reports API requieren autenticación básica HTTP mediante tu clave y tu secreto de API:

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Sustituir $VONAGE_API_KEY y $VONAGE_API_SECRET con tus credenciales de la 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 Account) abcd1234
product El producto de Vonage que se desea 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 el caso de las fechas, codifícalas mediante 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"

Consultas por ID frente a consultas por intervalo de fechas

  • Por identificación: Recuperar un registro concreto (solo de forma sincrónica)
  • Por intervalo de fechas: Recuperar todos los registros correspondientes a un periodo de tiempo determinado
  • No se pueden utilizar ambos: Elija id O date_start/date_end, no las dos cosas

Parámetros específicos del producto

Cada producto admite parámetros distintos. En esta sección se detallan los parámetros obligatorios y opcionales de cada producto. Para consultar las especificaciones completas de los parámetros y los formatos de respuesta, véase el Referencia API.

SMS

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • status - Filtrar por estado de entrega (p. ej., 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 - Tu número de 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 - Establecer en 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 - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • status - Filtrar por estado de entrega (p. ej., 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 DE VOZ

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • status - Estado de la llamada (p. ej., 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 específico de la llamada

In-App Voice

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • status - Estado de finalización de la llamada
  • conversation_id - ID de la conversación
  • leg_id - Tramo específico de una opción de compra

VOZ-TTS

Parámetros obligatorios:

  • product - Establecer en 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)

FALLO DE VOZ

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • country - Filtro por código de país
  • call_id - Identificador específico de la llamada

WEBSOCKET-CALL

Parámetros obligatorios:

  • product - Establecer en 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)
  • call_id - Identificador específico de la llamada

ASR

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)
  • call_id - Identificador específico de la llamada

AMD

Parámetros obligatorios:

  • product - Establecer en 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)
  • call_id - Identificador específico de la llamada

VERIFY-API

Parámetros obligatorios:

  • product - Establecer en VERIFY-API
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

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

VERIFY-V2

Parámetros obligatorios:

  • product - Establecer en 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/Configuración regional
  • network - Código de red móvil
  • to - Se está verificando el número de teléfono
  • id - Id. de registro específico (no puede utilizarse con intervalo de fechas)

NUMBER-INSIGHT

Parámetros obligatorios:

  • product - Establecer en NUMBER-INSIGHT
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

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

CONVERSACIÓN-ACONTECIMIENTO

Parámetros obligatorios:

  • product - Establecer en 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 específico de la conversación
  • status - Estado del evento
  • id - ID específico del registro (no se puede utilizar con un intervalo de fechas)

CONVERSACIÓN-MENSAJE

Parámetros obligatorios:

  • product - Establecer en 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 específico de la conversación
  • id - ID específico del registro (no se puede utilizar con un intervalo de fechas)

VIDEO-API

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)

EVENTO-API-RED

Parámetros obligatorios:

  • product - Establecer en 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 específico del registro (no se puede utilizar con un intervalo de fechas)

INFORMES-USO

Parámetros obligatorios:

  • product - Establecer en REPORTS-USAGE
  • account_id - Tu clave API de Vonage

Parámetros adicionales:

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

Nota: Todos los productos son compatibles include_subaccounts parámetro al crear informes asíncronos para incluir datos de Subaccounts. Para obtener información detallada sobre los formatos de respuesta y las opciones de filtrado adicionales, consulta el 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 tu 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.

Véase también