Aller au contenu principal

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 droit API > Consommation > Consulter.

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 API > Consommation > Consulter absente.

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


Options de l'entreprise​

Endpoint : GET /company-options​

Description​

Le endpoint renvoie les options de l'entreprise de votre token, dont la configuration du webhook. Les secrets ne sont jamais renvoyés : seule leur présence est indiquée.

Requête HTTP​

Méthode : GET URL : /company-options

Exemple :

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

Permissions Requises​

  • L'utilisateur doit disposer de la permission API > Mon entreprise > Consulter.

Réponses​

200 OK :

{
"companyId": 42,
"apiSettings": [
{
"apiName": "caseHook",
"endpoints": { "sendCase": "https://votre-domaine.fr/webhooks/certificall/dossier" },
"authorizationHeader": "authorization",
"hasCredentials": true
}
],
"pdfOptions": {},
"lang": "fr",
"casesSharable": true
}
ChampTypeDescription
companyIdNumberIdentifiant de l'entreprise.
apiSettingsArrayIntégrations configurées, dont le webhook (caseHook).
apiSettings[].apiNameStringNom de l'intégration.
apiSettings[].endpointsObjectURL appelées par Certificall.
apiSettings[].authorizationHeaderStringMéthode d'authentification : authorization ou security-token.
apiSettings[].hasCredentialsBooleantrue si un jeton est enregistré. Le jeton lui-même n'est jamais renvoyé.
pdfOptionsObjectRéglages du certificat PDF de l'entreprise.
langStringLangue de l'entreprise.
casesSharableBooleantrue si les dossiers de l'entreprise peuvent être partagés par lien.

Pour modifier la configuration du webhook, utilisez POST /company-options/api-settings.

403 Forbidden : permission API > Mon entreprise > Consulter absente.

404 Not Found : aucune option enregistrée pour cette entreprise.


Créer une entreprise enfant​

Endpoint : POST /companies​

Description​

Le endpoint crée une entreprise rattachée directement à la vôtre : l'entreprise parente est toujours celle de votre token, jamais un paramètre. Il sert aux revendeurs et intégrateurs qui ouvrent un compte Certificall à chacun de leurs clients sans passer par l'interface d'administration.

L'entreprise créée consomme les crédits de votre entreprise. Elle apparaît ensuite dans la hiérarchie renvoyée par GET /companies.

Parcours complet
  1. Créez l'entreprise enfant (POST /companies) et conservez son id.
  2. Créez ses utilisateurs (POST /users) avec ce companyId.
  3. Créez ses dossiers avec POST /cases/create : userMail d'un utilisateur de l'entreprise enfant, ou childCompanyId pour un dossier par certilink.

Requête HTTP​

Méthode : POST URL : /companies

Exemple :

curl -X 'POST' \
'https://admin.certificall.app/certificall/api/companies' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer xxxx' \
-d '{ "name": "Artisan Dupont" }'

Corps de la requête​

  • name (String, requis) : nom de l'entreprise enfant, 255 caractères au plus.

Un champ inconnu est refusé (400), jamais ignoré. Rejouer la requête crée une seconde entreprise : appelez-la une seule fois par client.

Permissions Requises​

  • L'utilisateur doit disposer de la permission API > Entreprises enfants > Créer.

Réponses​

201 Created :

{ "id": 1234, "name": "Artisan Dupont" }

400 Bad Request : nom absent ou vide, ou champ inconnu.

403 Forbidden : permission API > Entreprises enfants > Créer absente.


Créer un utilisateur​

Endpoint : POST /users​

Description​

Le endpoint crée un utilisateur dans votre entreprise ou l'une de vos entreprises enfants. Le compte est actif tout de suite, avec le mot de passe fourni : l'utilisateur se connecte à l'application et à l'interface d'administration avec son email et ce mot de passe. Aucun droit d'administration n'est demandé à votre compte d'intégration.

Requête HTTP​

Méthode : POST URL : /users

Exemple :

curl -X 'POST' \
'https://admin.certificall.app/certificall/api/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer xxxx' \
-d '{
"email": "paul.dupont@exemple.fr",
"firstname": "Paul",
"lastname": "Dupont",
"password": "Mot-de-passe-choisi-123",
"companyId": 1234
}'

Corps de la requête​

  • email (String, requis) : email de connexion, unique sur toute la plateforme.
  • firstname, lastname (String, requis).
  • password (String, requis) : mot de passe du compte.
  • companyId (Number, requis) : votre entreprise ou l'une de vos entreprises enfants.

Les droits ne se choisissent pas : un corps qui contient roleToAdd est refusé (400).

L'utilisateur créé accède à l'application mobile et à l'interface d'administration. Il peut consulter, créer et modifier les trames, les dossiers, son entreprise et ses utilisateurs, et ajouter des vidéos aux trames. Il ne peut ni supprimer, ni valider de dossier, ni utiliser l'API.

Votre compte d'intégration n'a pas besoin de posséder ces droits : la permission API > Utilisateur > Créer suffit.

Permissions Requises​

  • L'utilisateur doit disposer de la permission API > Utilisateur > Créer.

Réponses​

201 Created :

{
"id": 5678,
"email": "paul.dupont@exemple.fr",
"firstname": "Paul",
"lastname": "Dupont",
"roles": ["r_app:user", "r_bo:user", "p_bo:frame:read", "…", "p_bo:option:video"],
"companyId": 1234
}

Le champ roles liste, à titre informatif, les droits donnés d'office à l'utilisateur.

400 Bad Request : champ manquant ou invalide, champ inconnu, ou présence de roleToAdd.

403 Forbidden : permission API > Utilisateur > Créer absente, ou companyId qui n'est ni votre entreprise ni l'une de vos entreprises enfants.

409 Conflict : email déjà utilisé.