Métadonnées de dossier

Les métadonnées sont des paires clé-valeur libres que vous attachez à un dossier. Certificall ne les interprète jamais : elles vous sont restituées telles quelles, sur tous les canaux, et vous servent à ventiler votre consommation.

Cette page rassemble le sujet de bout en bout. Le détail de chaque endpoint reste sur sa page dédiée.

Une métadonnée n'est pas une référence

Pour retrouver un dossier, utilisez reportToken : c'est le seul champ sur lequel l'API filtre, et celui que le webhook vous renvoie dans reportId. Les métadonnées sont un complément descriptif — site, agence, type d'intervention, campagne. Mettez votre identifiant dans reportToken, le contexte dans metadata.

Poser des métadonnées

Trois canaux, un même champ metadata :

Canal	Où le renseigner	Référence
API	Champ metadata de POST /cases/create	Gestion des dossiers
Certilink	Champ context.metadata à la création du lien	Certilink
SDK mobile	Option metadata de l'appel de capture	Référence SDK

Quel que soit le canal, les métadonnées sont portées par le dossier, pas par la photo ou le certificat.

Limites

Contrainte	Valeur
Nombre de clés	20 au maximum
Longueur d'une clé	40 caractères
Longueur d'une valeur	500 caractères
Type des valeurs	texte uniquement
Caractères interdits dans une clé	[ et ]

Un dépassement fait échouer la requête en 400, en nommant la clé fautive.

Les crochets sont refusés dans les clés parce qu'ils portent déjà un sens dans la syntaxe de filtre metadata[clé]=valeur : une clé qui en contiendrait rendrait le filtre ambigu.

Les valeurs sont du texte

Un nombre ou un booléen doit être transmis en chaîne de caractères ("42", "true"). Les objets et les tableaux imbriqués sont refusés : le champ est plat, une clé vaut une valeur.

Les récupérer

Les métadonnées vous reviennent partout où le dossier vous est restitué :

Où	Comment
Liste des dossiers	GET /cases?format=metadata — champ metadata de chaque dossier (détail)
Webhook de dossier	Champ metadata du corps envoyé à la clôture (détail)

{
  "id": 12345,
  "cfRef": "CAS-1234_CMP-7",
  "reportId": "CHANTIER-2026-018",
  "metadata": { "site": "Paris", "zone": "A1" }
}

Clé absente plutôt que vide

Un dossier sans métadonnée n'a pas la clé metadata dans la réponse. Prévoyez un défaut à la lecture (const { metadata = {} } = dossier) plutôt qu'un test sur un objet vide.

Les modifier

Les métadonnées d'un dossier existant se mettent à jour avec PATCH /cases/update. Vous n'envoyez que les clés qui changent :

{
  "caseId": 12345,
  "metadata": { "zone": "B2" }
}

Les clés envoyées complètent celles déjà posées : une clé déjà présente voit sa valeur écrasée, les autres sont conservées. Sur un dossier portant {"site": "Paris", "zone": "A1"}, l'appel ci-dessus laisse {"site": "Paris", "zone": "B2"}.

Pour effacer toutes les métadonnées d'un dossier, passez null :

{ "caseId": 12345, "metadata": null }

Le plafond s'applique au résultat

Les limites sont vérifiées sur le bloc après fusion. Dix clés ajoutées à quinze existantes dépassent le plafond de vingt et la requête est refusée en 400, alors qu'aucun des deux envois n'est fautif pris isolément.

Retirer une clé précise

Il n'existe pas aujourd'hui de moyen de supprimer une clé seule : null efface le bloc entier. Pour retirer une clé, effacez puis reposez les clés à conserver.

Pour mettre à jour plusieurs dossiers, utilisez PATCH /cases/bulk-update : une seule requête au regard des limites d'appels.

Filtrer votre consommation

C'est le seul endroit où les métadonnées servent de filtre : GET /companies/consumption ne compte que les dossiers qui portent toutes les paires demandées.

curl -X GET \
  'https://admin.certificall.app/certificall/api/companies/consumption?startDate=2026-08-01&endDate=2026-08-31&metadata[site]=Paris&metadata[zone]=A1' \
  -H 'Authorization: Bearer $TOKEN'

La syntaxe est metadata[clé]=valeur, répétée autant de fois que nécessaire. Plusieurs paires se cumulent en ET : l'exemple ci-dessus ne compte que les dossiers du site de Paris et de la zone A1.

Voir Consommation pour les paramètres de période et le format de réponse, et Suivre sa consommation pour le parcours complet.

Un filtre mal orthographié est refusé, pas ignoré

metadata.site=Paris (point au lieu de crochets) renvoie une erreur 400. C'est volontaire : sans cela vous recevriez le total non filtré en le croyant filtré.

Deux confusions à éviter

format=metadata n'a aucun rapport

Le paramètre format de GET /cases et de POST /reports/report/:reportToken accepte la valeur metadata. Il décrit le format de la réponse — des données JSON plutôt qu'une archive ZIP — et n'a rien à voir avec les métadonnées de dossier.

# Format de réponse JSON, sans aucun filtre sur les métadonnées
GET /cases?format=metadata&hours=48

# Filtre sur les métadonnées du dossier
GET /companies/consumption?startDate=…&endDate=…&metadata[site]=Paris

caseContext.metadata n'est pas filtrable

Certaines intégrations anciennes transmettent leurs métadonnées dans l'objet context du dossier (caseContext.metadata). Ces valeurs vous sont toujours restituées, pour ne pas casser les intégrations en place, mais elles ne sont pas prises en compte par le filtre de consommation.

Seul le champ metadata du dossier est filtrable. Si vous filtrez votre consommation et n'obtenez aucun résultat alors que vos dossiers portent bien vos clés, vérifiez que vous les envoyez dans metadata et non dans caseContext.

À retenir

Question	Réponse
Retrouver un dossier par une métadonnée ?	Non — utilisez reportToken
Modifier les métadonnées après création ?	Oui, PATCH /cases/update — les clés se complètent
Retirer une clé seule ?	Non — null efface le bloc entier
Filtrer une liste de dossiers dessus ?	Non — uniquement la consommation
Les retrouver dans le webhook ?	Oui, champ metadata
Valeurs numériques ?	En texte ("42")