POST
/api/v1/projects/{ref}/metricsDéfinir des indicateurs
Crée ou met à jour les indicateurs d'un projet : leur libellé et leur explication pour le client, leur unité, leur calcul.
Crée ou met à jour des indicateurs, par leur key. Une clé absente se
déduit du libellé (« Coût d'un contact » donne cout_d_un_contact).
Le libellé et l'explication sont lus par le client, dans son portail et dans le rapport par mail : écrivez « Contacts obtenus » plutôt que « Leads », et dites en une phrase ce que le chiffre veut dire.
Paramètres de chemin
| Paramètre | Description |
|---|---|
ref | L'id ou le slug du projet |
Corps de la requête
| Champ | Type | Requis | Contraintes |
|---|---|---|---|
metrics | array | oui | 1 à 50 indicateurs |
metrics[].key | string | a-z, 0-9, _, 48 caractères max | |
metrics[].label | string | oui | 1 à 80 caractères |
metrics[].description | string | L'explication pour le client, 400 caractères max | |
metrics[].unit | enum | number (défaut), currency, percent, duration (secondes) | |
metrics[].currency | string | Code ISO à 3 lettres, EUR par défaut | |
metrics[].aggregation | enum | Sur une période : sum (défaut), avg, last | |
metrics[].kind | enum | value (défaut), ou ratio : calculé | |
metrics[].numerator_key | string | Pour un ratio : l'indicateur divisé | |
metrics[].denominator_key | string | Pour un ratio : l'indicateur diviseur | |
metrics[].good_direction | enum | up (défaut), down (un coût), neutral (un budget) | |
metrics[].target | number | L'objectif sur la période | |
metrics[].visible_to_client | boolean | true par défaut ; masqué, il sert aux calculs |
Un ratio se calcule sur les totaux de la période — Σ numérateur ÷ Σ dénominateur —, multiplié par 100 en pourcentage.
Cette route accepte un en-tête Idempotency-Key.
Exemple
curl -X POST "https://www.tetikasa.app/api/v1/projects/campagne-meta-raphael/metrics" \
-H "Authorization: Bearer $TETIKASA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metrics":[
{"key":"spend","label":"Budget dépensé","unit":"currency","good_direction":"neutral"},
{"key":"leads","label":"Contacts obtenus","description":"Les personnes qui ont laissé leurs coordonnées."},
{"key":"cost_per_lead","label":"Coût par contact","kind":"ratio","unit":"currency",
"numerator_key":"spend","denominator_key":"leads","good_direction":"down"}
]}'La réponse liste tous les indicateurs envoyés ; un seul est montré ici.
Erreurs
code | Statut | Quand |
|---|---|---|
invalid_request | 422 | Corps invalide, ou ratio qui cite un indicateur absent du projet |
forbidden | 403 | Le reporting est inclus dans les plans payants |
not_found | 404 | Projet inexistant ou d'une autre organisation |
unauthorized | 401 | Clé absente, invalide, révoquée ou expirée |
