Antes de começar

Este guia ajuda você a dar os primeiros passos com a Reports API. Para obter informações detalhadas, consulte o Visão geral e Referência da API.

Neste tópico

Escolha sua abordagem

A Reports API oferece dois métodos para recuperar seus registros de atividade, cada um otimizado para diferentes padrões de consulta e volumes de dados.

Síncrono (em tempo real)

A abordagem síncrona é mais adequada para consultas frequentes que recuperam até dezenas de milhares de registros. Ao fazer uma solicitação síncrona, os registros são retornados imediatamente na resposta da API, tornando-a ideal para painéis em tempo real e sistemas de monitoramento. Esse método também permite consultas por ID específico de mensagem ou registro, o que é útil quando é necessário localizar transações individuais. Embora seja eficiente para conjuntos de dados menores, recomendamos limitar as consultas síncronas a milhares de registros por solicitação para manter o desempenho ideal.

Exemplo de caso de uso: Verifique o status de entrega das mensagens SMS de hoje para uma campanha específica.

Assíncrono (processamento em segundo plano)

Para necessidades de dados em grande volume, a abordagem assíncrona foi projetada para consultas pouco frequentes que exigem a recuperação de milhões de registros. Em vez de retornar os dados imediatamente, esse método gera um arquivo ZIP para download contendo dados em formato CSV, enquanto o processamento ocorre em segundo plano. O processo de geração geralmente leva de 5 a 10 minutos por 1 milhão de registros. Você pode fornecer uma URL de retorno de chamada para receber uma notificação quando o processamento for concluído ou verificar periodicamente o status do relatório. Para garantir o desempenho ideal, a Vonage recomenda limitar as consultas assíncronas a um máximo de 7 milhões de registros, definindo datas de início e término adequadas.

Exemplo de caso de uso: Gerar um relatório mensal de todas as chamadas de voz.

Como fazer sua primeira solicitação

Exemplo de solicitação síncrona

Recuperar registros de SMS para um intervalo de datas 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"

Exemplo de solicitação assíncrona

Gerar um relatório com todas as mensagens enviadas em dezembro:

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" }'

Autenticação

Todas as solicitações à Reports API exigem autenticação HTTP básica usando sua chave e seu segredo da API:

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Substituir $VONAGE_API_KEY e $VONAGE_API_SECRET com suas credenciais do Painel do Vonage.

Parâmetros comuns

Esses parâmetros são utilizados na maioria das chamadas da Reports API:

Parâmetro Obrigatório Descrição Exemplo
account_id Sua chave da API da Vonage (ID do Account) abcd1234
product O produto da Vonage a ser consultado SMS, MESSAGES, VOICE-CALL
date_start 🔸 Data inicial do intervalo (formato ISO-8601) 2026-01-01T00:00:00Z
date_end 🔸 Fim do intervalo de datas (formato ISO-8601) 2026-01-06T23:59:59Z
direction 🔸 Direção da mensagem/chamada inbound ou outbound
id 🔸 ID específico da mensagem ou do registro (somente sincronização) Não pode ser usado com intervalo de datas

Legenda: = Sempre obrigatório | 🔸 = Opcional ou específico do produto

Requisitos de formato de data

As datas devem estar no formato ISO-8601:

  • Formato UTC: 2026-01-01T00:00:00Z
  • Com diferença de fuso horário: 2026-01-01T08:00:00+0800

Importante: Ao usar GET solicitações com + no caso de datas, codifique-as usando o formato 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 x intervalo de datas

  • Por ID: Recuperar um registro específico (somente de forma síncrona)
  • Por intervalo de datas: Recuperar todos os registros dentro de um determinado período
  • Não é possível usar os dois: Escolha uma das opções id OU date_start/date_end, não os dois

Parâmetros específicos do produto

Produtos diferentes suportam parâmetros diferentes. Esta seção detalha os parâmetros obrigatórios e opcionais para cada produto. Para obter as especificações completas dos parâmetros e os formatos de resposta, consulte o Referência da API.

SMS

Parâmetros obrigatórios:

  • product - Definir como SMS
  • account_id - Sua chave de API da Vonage
  • direction - Deve ser uma das seguintes opções: inbound ou outbound

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • status - Filtrar por status de entrega (por exemplo, delivered, failed, expired)
  • from - Número do remetente
  • to - Número do destinatário
  • country - Filtrar por código de país
  • network - Filtrar por rede MCC-MNC
  • client_ref - Sua referência de cliente
  • account_ref - Referência da conta
  • include_message - Incluir o corpo da mensagem na resposta (true/false)

Exemplo:

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"

CONTROLE DE TRÁFEGO POR SMS

Parâmetros obrigatórios:

  • product - Definir como SMS-TRAFFIC-CONTROL
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

MENSAGENS

Parâmetros obrigatórios:

  • product - Definir como MESSAGES
  • account_id - Sua chave de API da Vonage
  • direction - Deve ser uma das seguintes opções: inbound ou outbound

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • status - Filtrar por status de entrega (por exemplo, submitted, delivered, read, rejected)
  • from - Identificador do remetente
  • to - Identificador do destinatário
  • provider - Filtrar por canal (por exemplo, whatsapp, sms, mms, viber_service_msg, messenger, instagram, rcs)
  • include_message - Incluir o corpo da mensagem na resposta (true/false)

CHAMADA DE VOZ

Parâmetros obrigatórios:

  • product - Definir como VOICE-CALL
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • direction - Direção da chamada (inbound ou outbound)
  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • status - Status da chamada (por exemplo, ANSWERED, MACHINE, ERROR)
  • from - Número do chamador
  • to - Número chamado
  • country - Filtrar por código de país
  • network - Filtrar por rede MCC-MNC
  • call_id - Identificador específico da chamada

In-App Voice

Parâmetros obrigatórios:

  • product - Definir como IN-APP-VOICE
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • status - Status de término da chamada
  • conversation_id - ID da conversa
  • leg_id - Etapa específica de uma chamada

VOZ-TTS

Parâmetros obrigatórios:

  • product - Definir como VOICE-TTS
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

FALHA NA VOZ

Parâmetros obrigatórios:

  • product - Definir como VOICE-FAILED
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • direction - Direção da chamada (inbound ou outbound)
  • date_start / date_end - Intervalo de datas para filtrar registros
  • from - Número do chamador
  • to - Número chamado
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • country - Filtro por código de país
  • call_id - Identificador específico da chamada

WEBSOCKET-CALL

Parâmetros obrigatórios:

  • product - Definir como WEBSOCKET-CALL
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • call_id - Identificador específico da chamada

ASR

Parâmetros obrigatórios:

  • product - Definir como ASR
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • direction - Direção da chamada (inbound ou outbound)
  • date_start / date_end - Intervalo de datas para filtrar registros
  • from - Identificação de chamadas
  • to - Número chamado
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • call_id - Identificador específico da chamada

AMD

Parâmetros obrigatórios:

  • product - Definir como AMD
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • call_id - Identificador específico da chamada

Verify-API

Parâmetros obrigatórios:

  • product - Definir como VERIFY-API
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • to - Número de telefone que foi verificado
  • network - Filtrar por rede MCC-MNC

Verify-V2

Parâmetros obrigatórios:

  • product - Definir como VERIFY-V2
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • channel - Canal de verificação (v2, email, silent_auth)
  • status - Status da solicitação
  • parent_request_id - Filtrar por ID da solicitação principal, que correlaciona as solicitações de verificação da v2 com os eventos de e-mail ou silent_auth associados a elas
  • country - Código do país
  • locale - Idioma/Configuração regional
  • network - Código da rede móvel
  • to - Número de telefone em verificação
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

NUMBER-INSIGHT

Parâmetros obrigatórios:

  • product - Definir como NUMBER-INSIGHT
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)
  • number - Número de telefone que foi consultado
  • network - Código da rede móvel

EVENTO DE CONVERSA

Parâmetros obrigatórios:

  • product - Definir como CONVERSATION-EVENT
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • conversation_id - ID específico da conversa
  • status - Status do evento
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

CONVERSA-MENSAGEM

Parâmetros obrigatórios:

  • product - Definir como CONVERSATION-MESSAGE
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • conversation_id - ID específico da conversa
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

Video API

Parâmetros obrigatórios:

  • product - Definir como VIDEO-API
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • session_id - ID da sessão de vídeo
  • meeting_id - Identificador da reunião
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

NETWORK-API-EVENT

Parâmetros obrigatórios:

  • product - Definir como NETWORK-API-EVENT
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • product_name - Produto específico da API de rede
  • request_session_id - Identificador da sessão de solicitação
  • product_path - Caminho do produto na API
  • correlation_id - ID de correlação
  • request_type - Tipo de solicitação da API de rede
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

RELATÓRIOS - UTILIZAÇÃO

Parâmetros obrigatórios:

  • product - Definir como REPORTS-USAGE
  • account_id - Sua chave de API da Vonage

Parâmetros adicionais:

  • date_start / date_end - Intervalo de datas para filtrar registros
  • id - ID específico do registro (não pode ser usado com intervalo de datas)

Observação: Suporte para todos os produtos include_subaccounts parâmetro ao criar relatórios assíncronos para incluir dados de Subaccounts. Para obter detalhes completos sobre os formatos de resposta e opções adicionais de filtragem, consulte o Referência da API.

Trabalhando com relatórios assíncronos

Ao criar um relatório assíncrono, você receberá um request_id para acompanhar o status do relatório:

Exemplo de resposta:

{
  "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"
    }
  }
}

Verificar o status do relatório

Use o request_id Para verificar se o seu relatório está pronto:

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

Baixar o relatório completo

Quando o status do relatório for SUCCESS, extraia o file_id a partir da resposta e do download:

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

O arquivo ZIP baixado contém um arquivo CSV com seus registros. Os arquivos ficam disponíveis por 72 horas.

Veja também