Avant de commencer

Ce guide vous aide à démarrer avec l'API Reports. Pour des informations plus détaillées, consultez le Vue d'ensemble et Référence API.

Dans ce thème

Choisissez votre approche

L'API Reports propose deux méthodes pour récupérer vos enregistrements d'activité, chacune étant optimisée pour des modèles de requête et des volumes de données différents.

Synchrone (temps réel)

L'approche synchrone est la meilleure pour les requêtes fréquentes qui récupèrent jusqu'à des dizaines de milliers d'enregistrements. Lorsque vous effectuez une requête synchrone, les enregistrements sont renvoyés immédiatement dans la réponse de l'API, ce qui est idéal pour les tableaux de bord et les systèmes de surveillance en temps réel. Cette méthode prend également en charge les requêtes par message spécifique ou par ID d'enregistrement, ce qui est utile lorsque vous devez rechercher des transactions individuelles. Bien que cette méthode soit efficace pour les petits ensembles de données, nous recommandons de limiter les requêtes synchrones à des milliers d'enregistrements par demande afin de maintenir des performances optimales.

Exemple de cas d'utilisation : Récupérer l'état de livraison des SMS du jour pour une campagne spécifique.

Asynchrone (traitement en arrière-plan)

Pour les besoins en données plus importants, l'approche asynchrone est conçue pour les requêtes peu fréquentes qui nécessitent l'extraction de millions d'enregistrements. Au lieu de renvoyer les données immédiatement, cette méthode génère un fichier ZIP téléchargeable contenant des données CSV pendant que le traitement se déroule en arrière-plan. Le processus de génération prend généralement 5 à 10 minutes pour 1 million d'enregistrements. Vous pouvez soit fournir une URL de rappel pour recevoir une notification lorsque le traitement est terminé, soit demander périodiquement l'état du rapport. Pour garantir une performance optimale, Vonage recommande de limiter les requêtes asynchrones à un maximum de 7 millions d'enregistrements en définissant des dates de début et de fin appropriées.

Exemple de cas d'utilisation : Produire un rapport mensuel de tous les appels vocaux.

Faire une première demande

Exemple de demande synchrone

Récupérer les enregistrements SMS pour une plage de dates spécifique :

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"

Exemple de demande asynchrone

Générer un rapport pour tous les messages envoyés en décembre :

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

Authentification

Toutes les demandes de Reports API nécessitent une authentification de base HTTP à l'aide de votre clé et de votre secret API :

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Remplacer $VONAGE_API_KEY et $VONAGE_API_SECRET à l'aide de vos données d'identification provenant de la Tableau de bord Vonage.

Paramètres communs

Ces paramètres sont utilisés dans la plupart des appels à l'API Reports :

Paramètres Exigée Description Exemple
account_id Votre clé API Vonage (Account ID) abcd1234
product Le produit Vonage à interroger SMS, MESSAGES, VOICE-CALL
date_start 🔸 Début de la plage de dates (format ISO-8601) 2026-01-01T00:00:00Z
date_end 🔸 Fin de la plage de dates (format ISO-8601) 2026-01-06T23:59:59Z
direction 🔸 Direction du message/de l'appel inbound ou outbound
id 🔸 ID de message ou d'enregistrement spécifique (synchronisation uniquement) Ne peut être utilisé avec une plage de dates

Légende : = Toujours requis 🔸 = Facultatif ou spécifique à un produit

Exigences en matière de format de date

Les dates doivent être au format ISO-8601 :

  • Format UTC : 2026-01-01T00:00:00Z
  • Avec décalage du fuseau horaire : 2026-01-01T08:00:00+0800

Important : Lors de l'utilisation de GET demandes avec + dans les dates, encoder les dates dans l'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"

Interrogation par ID ou par plage de dates

  • Par ID : Récupérer un enregistrement spécifique (synchrone uniquement)
  • Par tranche de dates : Récupérer tous les enregistrements au cours d'une période donnée
  • Il n'est pas possible d'utiliser les deux : Choisissez l'une ou l'autre des options suivantes id OU date_start/date_endet non les deux

Paramètres spécifiques au produit

Les différents produits prennent en charge des paramètres différents. Cette section détaille les paramètres obligatoires et facultatifs pour chaque produit. Pour connaître les spécifications complètes des paramètres et les formats de réponse, voir la section Référence API.

SMS

Paramètres requis :

  • product - Régler sur SMS
  • account_id - Votre clé API Vonage
  • direction - Doit être soit inbound ou outbound

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • status - Filtrer par statut de livraison (par exemple, delivered, failed, expired)
  • from - Numéro de l'expéditeur
  • to - Numéro de destinataire
  • country - Filtrer par code pays
  • network - Filtrer par réseau MCC-MNC
  • client_ref - Votre référence client
  • account_ref - Référence du compte
  • include_message - Inclure le corps du message dans la réponse (true/false)

Exemple :

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-CONTRÔLE DU TRAFIC

Paramètres requis :

  • product - Régler sur SMS-TRAFFIC-CONTROL
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

MESSAGES

Paramètres requis :

  • product - Régler sur MESSAGES
  • account_id - Votre clé API Vonage
  • direction - Doit être soit inbound ou outbound

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • status - Filtrer par statut de livraison (par exemple, submitted, delivered, read, rejected)
  • from - Identifiant de l'expéditeur
  • to - Identifiant du destinataire
  • provider - Filtrer par canal (par ex, whatsapp, sms, mms, viber_service_msg, messenger, instagram, rcs)
  • include_message - Inclure le corps du message dans la réponse (true/false)

VOIX-APPEL

Paramètres requis :

  • product - Régler sur VOICE-CALL
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • direction - Direction de l'appel (inbound ou outbound)
  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • status - Statut de l'appel (par exemple, ANSWERED, MACHINE, ERROR)
  • from - Numéro de l'appelant
  • to - Numéro appelé
  • country - Filtrer par code pays
  • network - Filtrer par réseau MCC-MNC
  • call_id - Identifiant d'appel spécifique

IN-APP VOICE

Paramètres requis :

  • product - Régler sur IN-APP-VOICE
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • status - État de la terminaison d'appel
  • conversation_id - ID de conversation
  • leg_id - Branche spécifique d'un appel

VOICE-TTS

Paramètres requis :

  • product - Régler sur VOICE-TTS
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

VOICE-FAILED

Paramètres requis :

  • product - Régler sur VOICE-FAILED
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • direction - Direction de l'appel (inbound ou outbound)
  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • from - Numéro de l'appelant
  • to - Numéro appelé
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • country - Filtre de code pays

WEBSOCKET-CALL

Paramètres requis :

  • product - Régler sur WEBSOCKET-CALL
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

ASR

Paramètres requis :

  • product - Régler sur ASR
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • direction - Direction de l'appel (inbound ou outbound)
  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • from - Identification de l'appelant
  • to - Numbers appelés
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

AMD

Paramètres requis :

  • product - Régler sur AMD
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

VERIFY-API

Paramètres requis :

  • product - Régler sur VERIFY-API
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • to - Numéro de téléphone vérifié
  • network - Filtrer par réseau MCC-MNC

VERIFY-V2

Paramètres requis :

  • product - Régler sur VERIFY-V2
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • channel - Canal de vérification (v2, email, silent_auth)
  • status - Statut de la demande
  • parent_request_id - Filtre sur l'identifiant de la demande parentale, qui permet d'établir une corrélation entre les demandes de vérification v2 et les événements e-mail ou silent_auth qui leur sont associés.
  • country - Code pays
  • locale - Langue/Locale
  • network - Code du réseau mobile
  • to - Numéro de téléphone en cours de vérification
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

NUMBER-INSIGHT

Paramètres requis :

  • product - Régler sur NUMBER-INSIGHT
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)
  • number - Numéro de téléphone interrogé
  • network - Code du réseau mobile

NOMBRE-VUE-V2

Paramètres requis :

  • product - Régler sur NUMBER-INSIGHT-V2
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • request_type - Type de demande d'aperçu (par ex, fraud_score, sim_swap)
  • risk - Niveau d'évaluation des risques
  • status- Numéro Statut de la demande de contrôle
  • swapped - Si le numéro a été porté/échangé
  • id - Identifiant d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

CONVERSATION-ÉVÉNEMENT

Paramètres requis :

  • product - Régler sur CONVERSATION-EVENT
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • conversation_id - ID de conversation spécifique
  • status - Statut de l'événement
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

MESSAGE DE CONVERSATION

Paramètres requis :

  • product - Régler sur CONVERSATION-MESSAGE
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • conversation_id - ID de conversation spécifique
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

VIDEO API

Paramètres requis :

  • product - Régler sur VIDEO-API
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • session_id - ID de la session vidéo
  • meeting_id - Identifiant de la réunion
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

RÉSEAU-API-ÉVÉNEMENT

Paramètres requis :

  • product - Régler sur NETWORK-API-EVENT
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • product_name - Produit spécifique Network API
  • request_session_id - Identifiant de session de la demande
  • product_path - Chemin d'accès au produit API
  • correlation_id - ID de corrélation
  • request_type - Type de demande d'API réseau
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

RAPPORTS-USAGE

Paramètres requis :

  • product - Régler sur REPORTS-USAGE
  • account_id - Votre clé API Vonage

Paramètres supplémentaires :

  • date_start / date_end - Plage de dates pour le filtrage des enregistrements
  • id - ID d'enregistrement spécifique (ne peut être utilisé avec une plage de dates)

Remarque : Tous les produits prennent en charge include_subaccounts lors de la création de rapports asynchrones pour inclure des données provenant de Subaccounts. Pour plus de détails sur les formats de réponse et les options de filtrage supplémentaires, voir la section Référence API.

Travailler avec des rapports asynchrones

Lorsque vous créez un rapport asynchrone, vous recevez un request_id pour suivre l'état de la déclaration :

Exemple de réponse :

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

Vérifier l'état du rapport

Utiliser le request_id pour vérifier si votre rapport est prêt :

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

Télécharger le rapport complet

Lorsque le statut du rapport est SUCCESS, extraire le file_id de la réponse et du téléchargement :

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

Le fichier ZIP téléchargé contient un fichier CSV avec vos enregistrements. Les fichiers sont disponibles pendant 72 heures.

Voir aussi