Skip to main content

Gestion des entreprises

Ce document détaille le fonctionnement et l'utilisation des endpoints pour gérer les entreprises l'application Certificall.

Listing des entreprises​

Endpoint : GET /companies​

Description​

Le endpoint récupère l'entreprise et toute la hiérarchie des entreprises liées

Authentification​

L'accès à ce endpoint nécessite une authentification valide. Incluez un token JWT (JSON Web Token) dans l'en-tête de votre requête HTTP comme suit :

Authorization: Bearer <Votre_Token_JWT>

Requête HTTP​

Méthode : GET URL : /companies

Exemple :

curl -X 'GET' \
'https://admin.certificall.app/certificall/api/companies' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'

Réponses​

200 OK : Retourne une liste des entreprises avec leur Id, leur nom, l'ID de l'entreprise parente et le niveau de profondeur.

Exemple de réponse :

{
  "descendants": [
    {
      "id": 1,
      "name": "Ent1",
      "parentId": null,
      "niveau": 0
    },
    {
      "id": 2,
      "name": "Ent2",
      "parentId": 1,
      "niveau": 1
    },
    {
      "id": 6,
      "name": "Ent6",
      "parentId": 1,
      "niveau": 1
    }
  ]
}

400 Bad Request : La requête est invalide, généralement en raison de paramètres manquants ou incorrects.

500 Internal Server Error : Erreur interne du serveur empêchant le traitement de la requête.

Consommation​

Endpoint : GET /companies/consumption​

Description​

Le endpoint restitue la consommation de votre entreprise et de toutes ses entreprises filles sur une période : nombre de photos, de vidéos et de signatures. Une ligne par entreprise de la hiérarchie, la vôtre comprise, plus un total consolidé.

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 ici ; sur la facture, elles sont comptées avec les photos.

Pour les intégrateurs API et SDK

Cet endpoint vous permet de maîtriser votre consommation réelle depuis votre propre SI, et de la ventiler par rapport ou par vos axes métier. Le parcours complet, de la capture au rapprochement, est décrit dans Suivre sa consommation réelle.

Authentification​

L'accès à ce endpoint nécessite une authentification valide. Incluez un token JWT (JSON Web Token) dans l'en-tête de votre requête HTTP comme suit :

Authorization: Bearer <Votre_Token_JWT>

Requête HTTP​

Méthode : GET URL : /companies/consumption

Exemple :

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 xxxx'

Paramètres de la requête​

  • startDate (String, requis) : début de période, inclus. ISO 8601 avec timezone, ou date seule (2026-08-01, interprétée minuit UTC).
  • endDate (String, requis) : fin de période, incluse. Une date seule est étendue à la fin de journée UTC. Amplitude maximale : 31 jours entre startDate et endDate ; au-delà, la requête est refusée (400) en rappelant la borne et la période demandée. Pour un trimestre, enchaînez trois appels.
  • reportToken (String, optionnel) : ne compte que les dossiers rattachés à ce rapport.
  • metadata (Object, optionnel) : ne compte que les dossiers portant toutes ces métadonnées, telles que fournies dans le champ metadata du dossier à sa création (POST /cases/create, Certilink ou SDK). Syntaxe : metadata[site]=Paris&metadata[zone]=A1. Mêmes limites que le champ : 20 clés, 40 caractères par clé, 500 par valeur. Les métadonnées envoyées dans caseContext ne sont pas prises en compte.

Permissions Requises​

  • L'utilisateur doit disposer du scope p_api et de la permission read sur la ressource consumption (p_api:consumption:read).

Réponses​

200 OK : la période retenue, le total sur toute la hiérarchie et une ligne par entreprise. Une entreprise sans consommation sur la période apparaît à zéro.

{
  "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 }
  ]
}

400 Bad Request : période absente, startDate postérieure à endDate, amplitude supérieure à 31 jours, ou métadonnées hors limites.

403 Forbidden : permission p_api:consumption:read absente.

429 Too Many Requests : quota dépassé — 30 appels par minute et par entreprise sur ce endpoint.