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
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| customer_integration | string | Oui | UUID de la connexion du client dont les métriques sont lues. Une par appel. |
| start | string | Oui | Début de la période (YYYY-MM-DD). Doit être inférieur ou égal à end. |
| end | string | Oui | Fin de la période (YYYY-MM-DD). |
| comparison_start | string | Non | Début de la période de comparaison (YYYY-MM-DD). Pris en compte seulement si comparison_end est aussi envoyé. |
| comparison_end | string | Non | Fin de la période de comparaison (YYYY-MM-DD). |
| client_timezone | string | Non | Fuseau horaire, comme America/Sao_Paulo (par défaut). |
| metrics | array | Oui | Liste 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}.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
