Skip to main content

Suivre sa consommation réelle — API et SDK

Ce guide s'adresse aux intégrateurs API et SDK mobile qui veulent piloter leur consommation Certificall depuis leur propre système d'information, sans passer par l'interface d'administration.

L'endpoint GET /companies/consumption vous rend, pour votre entreprise et toutes ses entreprises filles, le nombre de photos, de vidéos et de signatures consommées sur une période — les mêmes chiffres que notre suivi interne, comptés avec les mêmes règles. Vous pouvez les ventiler par rapport (reportToken) ou par vos propres axes analytiques (metadata), et ainsi rapprocher ce que vous consommez de ce que vous facturez à vos propres clients.

Vue d'ensemble​

┌─────────────────────┐   (1) capture      ┌──────────────────────┐
│  App mobile / SDK   │  reportToken +     │  Backend Certificall │
│  ou POST /cases     │  metadata ────────►│                      │
│  (création)         │                    │  dossier + items     │
└─────────────────────┘                    │  fermés, datés       │
                                           └──────────┬───────────┘
┌─────────────────────┐                               │
│  Backend partenaire │  (2) GET /companies/           │
│                     │      consumption ─────────────►│
│  - période ≤ 31 j   │      ?startDate&endDate        │
│  - filtre rapport   │      [&reportToken]            │
│    ou metadata      │      [&metadata[site]=Paris]   │
│                     │◄───────────────────────────────┤
│  (3) rapprochement  │  total + une ligne par         │
│      avec votre SI  │  entreprise de la hiérarchie   │
└─────────────────────┘                    └──────────────────────┘

Pré-requis​

Pré-requisComment l'obtenir
Compte API actifDemandez à votre administrateur Certificall l'activation d'un utilisateur de type API.
Droit p_api:consumption:readCe droit dédié est attribué par Certificall à votre compte API. Sans lui, l'endpoint répond 403. Le droit de lecture de la hiérarchie (p_api:company:read) ne suffit pas.
Vos axes analytiques posés à la créationPour ventiler la consommation, renseignez le reportToken (votre référence métier) et le champ metadata (site, zone, référence interne…) au moment où le dossier est créé — via le SDK mobile ou POST /cases/create. Voir la note ci-dessous.
Les métadonnées se filtrent uniquement depuis le champ metadata

Le filtre de consommation ne lit que les métadonnées transmises dans le champ metadata du dossier (SDK, Certilink ou POST /cases/create). Des métadonnées envoyées dans caseContext restent restituées avec le dossier mais ne sont pas prises en compte par ce filtre.

Étape 1 — Authentification​

Tout appel à l'API est authentifié par un token JWT obtenu avec les identifiants de votre compte API.

Étape 2 — Interroger sa consommation sur une période​

Requête :

curl -X 'GET' \
'https://admin.certificall.app/certificall/api/companies/consumption?startDate=2026-08-01&endDate=2026-08-31' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
ParamètreRequisRôle
startDateouiDébut de période, inclus. ISO 8601 avec timezone, ou date seule (2026-08-01, minuit UTC).
endDateouiFin de période, incluse. Une date seule couvre la journée entière (UTC) ; une date-heure explicite est prise telle quelle.
reportTokennonNe compte que les dossiers rattachés à ce rapport.
metadata[clé]=valeurnonNe compte que les dossiers portant toutes les paires indiquées.

Réponse 200 :

{
  "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-31T23:59:59.999Z" },
  "total": { "photos": 128, "videos": 9, "signatures": 41 },
  "companies": [
    { "id": 1, "name": "Ent1", "parentId": null, "photos": 100, "videos": 9, "signatures": 30 },
    { "id": 2, "name": "Ent2", "parentId": 1, "photos": 28, "videos": 0, "signatures": 11 },
    { "id": 6, "name": "Ent6", "parentId": 1, "photos": 0, "videos": 0, "signatures": 0 }
  ]
}
  • total est la somme sur toute la hiérarchie.
  • companies contient une ligne par entreprise de la hiérarchie, la vôtre comprise ; une entreprise sans consommation sur la période apparaît à zéro.
Les règles de comptage sont celles de notre suivi interne

Un élément est compté lorsqu'il est clôturé et créé dans la période. Les signatures sont comptées à part dans cette réponse ; sur la facture, elles sont comptées avec les photos. Vous lisez donc exactement ce que nous lisons.

Étape 3 — Ventiler par rapport ou par axe analytique​

Par rapport — la consommation d'un seul rapport, identifié par votre référence métier :

curl -X 'GET' \
'https://admin.certificall.app/certificall/api/companies/consumption?startDate=2026-08-01&endDate=2026-08-31&reportToken=RAPPORT-2024-001' \
-H 'Authorization: Bearer <token>'

Par métadonnées — la consommation des dossiers portant toutes les paires demandées :

curl -g -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>'
Posez vos axes dès la capture

Côté SDK mobile, le champ metadata de la capture (voir la référence SDK) est enregistré avec le dossier : c'est lui qui rend possible cette ventilation. Choisissez des clés stables (site, agence, contrat…) et réutilisez-les à l'identique d'une capture à l'autre.

Étape 4 — Couvrir un trimestre ou une année​

La période est bornée à 31 jours par appel. Pour un trimestre, enchaînez trois appels mensuels et additionnez les totaux de votre côté. Au-delà, l'API répond 400 en rappelant la borne et la période demandée.

01/07 → 31/07   puis   01/08 → 31/08   puis   01/09 → 30/09

Le quota est de 30 appels par minute et par entreprise sur cet endpoint : largement suffisant pour un suivi quotidien ou une clôture mensuelle, pas conçu pour être scruté en continu.

Réponses d'erreur​

CodeSituation
400Période absente, startDate postérieure à endDate, amplitude supérieure à 31 jours, métadonnées hors limites, ou paramètre inconnu (par exemple metadata.site au lieu de metadata[site] — refusé plutôt qu'ignoré, pour ne jamais vous rendre un total non filtré en le croyant filtré).
401Token absent ou invalide.
403Droit p_api:consumption:read absent.
429Quota de 30 appels par minute dépassé.