Metrics

Comparer des périodes de métriques via l'API

Dans POST /metrics/get-data, vous envoyez la période principale et, si vous voulez, une période de comparaison. La réponse apporte déjà la valeur actuelle et la précédente : votre produit affiche l'évolution sans second appel. Sans OAuth, sans revue d'app, sans renouvellement de token.

L'appel

POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "customer_integration": "<connection uuid>",
  "start": "2026-08-01",
  "end": "2026-08-31",
  "comparison_start": "2026-07-01",
  "comparison_end": "2026-07-31",
  "metrics": [
    {
      "id": "f35a44ce-dac5-4188-aace-5c44a8952176",
      "reference_key": "fb_ads:spend",
      "component": "number_v1",
      "metrics": [
        "spend"
      ]
    }
  ]
}

Ce que vous pouvez faire

  • Comparer le mois en cours au précédent, ou n'importe quelle paire de périodes, en un seul appel.
  • Demander plusieurs métriques à la fois, chacune avec son component.
  • Régler le fuseau avec client_timezone pour que les journées se terminent comme l'attend votre client.
  • Utiliser la version asynchrone (get-data-async) avec les mêmes champs de comparaison pour les longues périodes.

Règles et limites

  • comparison_start n'est pris en compte que si comparison_end est aussi envoyé.
  • Dans l'exemple de la spec, un number_v1 revient avec value (période actuelle) et previous_value (période de comparaison).
  • Le résultat arrive dans l'objet data, avec l'id (UUID) de chaque métrique comme clé.
  • Si une métrique échoue seule, elle revient sous forme d'objet d'erreur (par exemple no_data_in_period) et les autres arrivent normalement, avec le statut 200.
  • Chaque appel lit une connexion (customer_integration) et exige le x-customer-token du client.

Champs principaux

ChampTypeObligatoireDescription
customer_integrationstringOuiUUID de la connexion du client dont les métriques sont lues. Une par appel.
startstringOuiDébut de la période (YYYY-MM-DD). Doit être inférieur ou égal à end.
endstringOuiFin de la période (YYYY-MM-DD).
comparison_startstringNonDébut de la période de comparaison (YYYY-MM-DD). Pris en compte seulement si comparison_end est aussi envoyé.
comparison_endstringNonFin de la période de comparaison (YYYY-MM-DD).
client_timezonestringNonFuseau horaire, comme America/Sao_Paulo (par défaut).
metricsarrayOuiListe des métriques demandées, au moins une. Chaque élément porte id, reference_key, component et metrics.

Pour qui

  • Cartes d'évolution dans les dashboards

    Votre panneau affiche dépense ou abonnés avec la flèche de hausse ou de baisse face à la période précédente, à partir d'une seule réponse.

  • Rapports mensuels d'agence

    Générez la comparaison mois sur mois de chaque client sans calculer la différence de votre côté.

  • Agents qui expliquent les variations

    Un agent lit l'actuel et le précédent et rédige l'analyse de ce qui a changé, avec les chiffres venant de l'API.

Questions fréquentes

Comment demander la comparaison ?

Envoyez comparison_start et comparison_end avec start et end dans POST /metrics/get-data. Si vous n'en envoyez qu'un, la comparaison n'est pas prise en compte.

La période de comparaison doit-elle avoir la même durée ?

La spec ne l'impose pas : vous choisissez les deux dates. Pour une comparaison juste, utilisez des périodes de même durée.

Cela marche-t-il avec toutes les métriques ?

Cela dépend de la métrique et du component. L'exemple de la spec montre number_v1 revenant avec value et previous_value. Testez la métrique voulue dans le catalogue GET /metrics/{integration_slug}.

Voir aussi

Voir tout ce que vous pouvez faire avec Metrics

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.