Gestion des trames
Une trame décrit ce que l'on demande de collecter dans un dossier : la liste de ses étapes (photo, signature, champ texte, document…), leur ordre, leur caractère obligatoire et leurs conditions d'affichage. Un dossier ou un Certilink est toujours créé à partir d'une trame (voir Création d'un certificat et Certilink).
Ces endpoints permettent de lister, créer, modifier et supprimer les trames de votre entreprise.
Authentification : Authorization: Bearer <votre_token> (voir Authentification).
| Opération | Endpoint |
|---|---|
| Lister les trames | GET /certificall/api/frames |
| Créer une trame | POST /certificall/api/frames |
| Modifier une trame | PATCH /certificall/api/frames/{frameId} |
| Supprimer une trame | DELETE /certificall/api/frames/{frameId} |
Chaque opération demande le droit correspondant sur les trames (lecture, création, modification, suppression). Sans ce droit, l'API répond 403.
Lister les trames
GET /certificall/api/frames
Retourne les trames à utiliser pour créer un dossier : celles de votre entreprise, ainsi que celles qui lui sont rattachées dans sa hiérarchie d'entreprises.
Paramètres : aucun.
Exemple
curl -X GET 'https://admin.certificall.app/certificall/api/frames' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
Réponse 200 : un tableau de trames.
[
{
"id": 12,
"name": "État des lieux",
"steps": [
{
"id": 101,
"title": "Photo de la façade",
"description": "Prendre la photo depuis la rue",
"stepAction": "PHOTOGRAPHY",
"isMandatory": true,
"groupId": null,
"pos": 0,
"min": null,
"max": null,
"parameters": null,
"visibleIf": null,
"scoring": null
},
{
"id": 102,
"title": "Pièce d'identité",
"description": null,
"stepAction": "DOCUMENT_UPLOAD",
"isMandatory": false,
"groupId": 7,
"pos": 0,
"min": null,
"max": null,
"parameters": null,
"visibleIf": null,
"scoring": null
}
],
"groups": [
{
"id": 7,
"name": "Pièces justificatives",
"description": null,
"pos": 1,
"isMandatory": false,
"min": 1,
"max": 1,
"visibleIf": null,
"groups": []
}
]
}
]
Forme d'une trame
| Champ | Type | Description |
|---|---|---|
id | number | Identifiant de la trame. |
name | string | Nom de la trame. |
steps | tableau | Toutes les étapes de la trame, y compris celles des groupes. Le champ groupId indique le groupe qui porte l'étape, null pour une étape hors groupe. |
groups | tableau | L'arborescence des groupes, sans leurs étapes (elles sont dans steps). |
En lecture, steps contient toutes les étapes, groupes compris. En écriture (création, modification), steps ne contient que les étapes hors groupe : les étapes d'un groupe se déclarent dans le steps de ce groupe.
Forme d'une étape
| Champ | Type | Description |
|---|---|---|
id | number | Identifiant de l'étape. |
title | string | Titre affiché. |
description | string ou null | Consigne affichée. |
stepAction | string | Type d'étape (voir Types d'étape). |
isMandatory | boolean | L'étape est-elle obligatoire. |
groupId | number ou null | Groupe qui contient l'étape, null si hors groupe. |
pos | number | Place de l'élément dans son conteneur (la trame ou son groupe). Étapes et groupes d'un même conteneur partagent la même numérotation. |
min / max | number ou null | Nombre minimum / maximum de répétitions de l'étape. |
parameters | objet ou null | Paramètres propres à l'étape (JSON libre). |
visibleIf | objet ou null | Conditions d'affichage (voir Conditions d'affichage). |
scoring | tableau ou null | Barème de l'étape, en lecture seule. |
Forme d'un groupe
| Champ | Type | Description |
|---|---|---|
id | number | Identifiant du groupe. |
name | string | Nom du groupe. |
description | string ou null | Description du groupe. |
pos | number | Place du groupe parmi les étapes de son conteneur. |
isMandatory | boolean | Le groupe est-il obligatoire. |
min / max | number | Nombre minimum / maximum de répétitions du groupe. |
visibleIf | objet ou null | Conditions d'affichage du groupe. |
groups | tableau | Sous-groupes. |
Autres réponses
401— jeton absent ou invalide.403— votre compte n'a pas le droit de lire les trames.429— quota de requêtes dépassé (voir Limites de requêtes).
Créer une trame
POST /certificall/api/frames
Crée une trame pour votre entreprise, avec ses étapes et, si besoin, ses groupes d'étapes.
Corps de la requête
| Nom | Type | Requis | Description |
|---|---|---|---|
name | string | oui | Nom de la trame. |
attachmentType | string | non | Type de pièce jointe de la trame : DOCX, LINK, PDF ou PUBLIC_LINK. |
confirmBeforeClose | boolean | non | Demande une confirmation avant de clôturer le dossier. |
endSessionOnComplete | boolean | non | Termine la session une fois le dossier complété. |
steps | tableau d'étapes | non | Les étapes hors groupe, dans l'ordre d'affichage. |
groups | tableau de groupes | non | Les groupes d'étapes, dans l'ordre d'affichage. Ils s'affichent après les étapes hors groupe. |
Une trame doit contenir au moins une étape, hors groupe ou dans un groupe. Sinon l'API répond 400.
Étape (éléments de steps)
| Nom | Type | Requis | Description |
|---|---|---|---|
id | number | non | À omettre à la création. À fournir pour modifier une étape existante (voir Modifier une trame). |
title | string | oui | Titre de l'étape. |
stepAction | string | oui | Type d'étape (voir Types d'étape). |
description | string | non | Consigne affichée. |
isMandatory | boolean | non | Étape obligatoire. Défaut : false. |
min / max | number | non | Nombre minimum / maximum de répétitions de l'étape (entiers, min ≥ 0 et max ≥ 1). |
parameters | objet | non | Paramètres propres à l'étape (JSON libre). |
visibleIf | objet | non | Conditions d'affichage (voir Conditions d'affichage). |
Groupe (éléments de groups)
| Nom | Type | Requis | Description |
|---|---|---|---|
id | number | non | À omettre à la création, à fournir pour modifier un groupe existant. |
name | string | oui | Nom du groupe. |
description | string | non | Description du groupe. |
isMandatory | boolean | non | Groupe obligatoire. Défaut : false. |
min / max | number | non | Nombre minimum / maximum de répétitions du groupe. Défaut : 1. |
visibleIf | objet | non | Conditions d'affichage du groupe. |
steps | tableau d'étapes | non | Les étapes du groupe, dans l'ordre d'affichage. |
groups | tableau de groupes | non | Sous-groupes, de même forme (sans groups). Profondeur maximum : 2. |
Exemple
curl -X POST 'https://admin.certificall.app/certificall/api/frames' \
-H 'Authorization: Bearer xxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "État des lieux",
"confirmBeforeClose": true,
"steps": [
{
"title": "Photo de la façade",
"description": "Prendre la photo depuis la rue",
"stepAction": "PHOTOGRAPHY",
"isMandatory": true
}
],
"groups": [
{
"name": "Pièces justificatives",
"steps": [
{ "title": "Pièce d'\''identité", "stepAction": "DOCUMENT_UPLOAD" }
]
}
]
}'
Réponses
201— la trame créée, dans la même forme que celle de la liste.400— corps invalide (champ manquant, valeur hors liste, aucune étape, groupes imbriqués au-delà de 2 niveaux) ou erreur à la création.401— jeton absent ou invalide.403— droit de création de trame manquant.429— quota de requêtes dépassé.
Modifier une trame
PATCH /certificall/api/frames/{frameId}
Modifie les réglages d'une trame et/ou ses étapes.
Paramètre de chemin
| Nom | Type | Requis | Description |
|---|---|---|---|
frameId | number | oui | Identifiant de la trame. Seules les trames créées par votre entreprise (ou ses entreprises enfants) sont modifiables. |
Corps de la requête : mêmes champs que pour la création, tous optionnels. Un champ absent n'est pas modifié.
Pour steps et groups, la liste envoyée remplace l'existante :
| Dans la liste envoyée | Effet |
|---|---|
élément avec id | modifié |
élément sans id | créé |
| élément de la trame absent de la liste | supprimé |
- L'ordre des tableaux définit l'ordre d'affichage (
posest recalculé). - Un groupe absent de
groupsest supprimé avec ses étapes. - Les étapes d'un groupe conservé ne sont remplacées que si son
stepsest fourni : l'omettre les laisse en place, le fournir vide les supprime. - Si
stepsougroupsest omis, ce niveau n'est pas touché.
Pour modifier une seule étape, renvoyez toutes les autres avec leur id (récupérées par GET /frames). Une étape oubliée dans la liste est supprimée.
Exemple : renommer la trame et changer le titre d'une étape, sans rien supprimer
curl -X PATCH 'https://admin.certificall.app/certificall/api/frames/12' \
-H 'Authorization: Bearer xxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "État des lieux d'\''entrée",
"steps": [
{ "id": 101, "title": "Façade (vue de la rue)", "stepAction": "PHOTOGRAPHY", "isMandatory": true }
],
"groups": [
{ "id": 7, "name": "Pièces justificatives" }
]
}'
Réponses
200— la trame mise à jour (même forme que la liste).400— corps invalide, trame laissée sans étape, ou erreur à la modification.401— jeton absent ou invalide, ou trame non créée par votre entreprise.403— droit de modification de trame manquant.404— trame introuvable.429— quota de requêtes dépassé.
Supprimer une trame
DELETE /certificall/api/frames/{frameId}
Supprime une trame. La suppression est logique : la trame n'est plus proposée.
Paramètre de chemin
| Nom | Type | Requis | Description |
|---|---|---|---|
frameId | number | oui | Identifiant de la trame. Seules les trames créées par votre entreprise (ou ses entreprises enfants) sont supprimables. |
Exemple
curl -X DELETE 'https://admin.certificall.app/certificall/api/frames/12' \
-H 'Authorization: Bearer xxxx'
Réponse 200
{ "id": 12 }
Autres réponses
400— erreur à la suppression.401— jeton absent ou invalide, ou trame non créée par votre entreprise.403— droit de suppression de trame manquant.404— trame introuvable.429— quota de requêtes dépassé.
Types d'étape
Valeurs possibles de stepAction :
| Valeur | Étape |
|---|---|
PHOTOGRAPHY | Photo |
VIDEO | Vidéo |
SIGNATURE | Signature |
DOCUMENT_UPLOAD | Dépôt de document |
TEXT_FIELD | Champ texte |
NUMBER_FIELD | Champ numérique |
DATE_FIELD | Champ date |
TIME | Champ heure |
EMAIL | Adresse e-mail |
SELECT | Choix dans une liste |
Conditions d'affichage
visibleIf permet d'afficher une étape ou un groupe seulement si une réponse précédente a une valeur donnée. Exemple : l'étape n'apparaît que si l'étape 3 a la valeur CNI.
{ "allOf": [{ "stepId": 3, "operator": "equals", "value": "CNI" }] }
allOf exige que toutes les conditions soient vraies ; anyOf qu'au moins une le soit.
Barème (scoring)
Le champ scoring d'une étape est renvoyé en lecture seule : le barème se règle dans l'éditeur de trame de l'interface d'administration. Il est ignoré à la création et à la modification par l'API.
Limites de requêtes
Ces endpoints suivent la limite par défaut (60 requêtes par minute et par endpoint). Voir Limites de requêtes.