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.
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
startDateetendDate; 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
metadatadu 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 danscaseContextne 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
}
| Champ | Type | Description |
|---|---|---|
companyId | Number | Identifiant de l'entreprise. |
apiSettings | Array | Intégrations configurées, dont le webhook (caseHook). |
apiSettings[].apiName | String | Nom de l'intégration. |
apiSettings[].endpoints | Object | URL appelées par Certificall. |
apiSettings[].authorizationHeader | String | Méthode d'authentification : authorization ou security-token. |
apiSettings[].hasCredentials | Boolean | true si un jeton est enregistré. Le jeton lui-même n'est jamais renvoyé. |
pdfOptions | Object | Réglages du certificat PDF de l'entreprise. |
lang | String | Langue de l'entreprise. |
casesSharable | Boolean | true 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.
- Créez l'entreprise enfant (
POST /companies) et conservez sonid. - Créez ses utilisateurs (
POST /users) avec cecompanyId. - Créez ses dossiers avec
POST /cases/create:userMaild'un utilisateur de l'entreprise enfant, ouchildCompanyIdpour 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é.