Aller au contenu principal

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érationEndpoint
Lister les tramesGET /certificall/api/frames
Créer une tramePOST /certificall/api/frames
Modifier une tramePATCH /certificall/api/frames/{frameId}
Supprimer une trameDELETE /certificall/api/frames/{frameId}
Droits nécessaires

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​

ChampTypeDescription
idnumberIdentifiant de la trame.
namestringNom de la trame.
stepstableauToutes 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.
groupstableauL'arborescence des groupes, sans leurs étapes (elles sont dans steps).
Lecture et écriture ne sont pas symétriques

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​

ChampTypeDescription
idnumberIdentifiant de l'étape.
titlestringTitre affiché.
descriptionstring ou nullConsigne affichée.
stepActionstringType d'étape (voir Types d'étape).
isMandatorybooleanL'étape est-elle obligatoire.
groupIdnumber ou nullGroupe qui contient l'étape, null si hors groupe.
posnumberPlace 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 / maxnumber ou nullNombre minimum / maximum de répétitions de l'étape.
parametersobjet ou nullParamètres propres à l'étape (JSON libre).
visibleIfobjet ou nullConditions d'affichage (voir Conditions d'affichage).
scoringtableau ou nullBarème de l'étape, en lecture seule.

Forme d'un groupe​

ChampTypeDescription
idnumberIdentifiant du groupe.
namestringNom du groupe.
descriptionstring ou nullDescription du groupe.
posnumberPlace du groupe parmi les étapes de son conteneur.
isMandatorybooleanLe groupe est-il obligatoire.
min / maxnumberNombre minimum / maximum de répétitions du groupe.
visibleIfobjet ou nullConditions d'affichage du groupe.
groupstableauSous-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

NomTypeRequisDescription
namestringouiNom de la trame.
attachmentTypestringnonType de pièce jointe de la trame : DOCX, LINK, PDF ou PUBLIC_LINK.
confirmBeforeClosebooleannonDemande une confirmation avant de clôturer le dossier.
endSessionOnCompletebooleannonTermine la session une fois le dossier complété.
stepstableau d'étapesnonLes étapes hors groupe, dans l'ordre d'affichage.
groupstableau de groupesnonLes groupes d'étapes, dans l'ordre d'affichage. Ils s'affichent après les étapes hors groupe.
Au moins une étape

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)

NomTypeRequisDescription
idnumbernonÀ omettre à la création. À fournir pour modifier une étape existante (voir Modifier une trame).
titlestringouiTitre de l'étape.
stepActionstringouiType d'étape (voir Types d'étape).
descriptionstringnonConsigne affichée.
isMandatorybooleannonÉtape obligatoire. Défaut : false.
min / maxnumbernonNombre minimum / maximum de répétitions de l'étape (entiers, min ≥ 0 et max ≥ 1).
parametersobjetnonParamètres propres à l'étape (JSON libre).
visibleIfobjetnonConditions d'affichage (voir Conditions d'affichage).

Groupe (éléments de groups)

NomTypeRequisDescription
idnumbernonÀ omettre à la création, à fournir pour modifier un groupe existant.
namestringouiNom du groupe.
descriptionstringnonDescription du groupe.
isMandatorybooleannonGroupe obligatoire. Défaut : false.
min / maxnumbernonNombre minimum / maximum de répétitions du groupe. Défaut : 1.
visibleIfobjetnonConditions d'affichage du groupe.
stepstableau d'étapesnonLes étapes du groupe, dans l'ordre d'affichage.
groupstableau de groupesnonSous-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

NomTypeRequisDescription
frameIdnumberouiIdentifiant 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éeEffet
élément avec idmodifié
élément sans idcréé
élément de la trame absent de la listesupprimé
  • L'ordre des tableaux définit l'ordre d'affichage (pos est recalculé).
  • Un groupe absent de groups est supprimé avec ses étapes.
  • Les étapes d'un groupe conservé ne sont remplacées que si son steps est fourni : l'omettre les laisse en place, le fournir vide les supprime.
  • Si steps ou groups est omis, ce niveau n'est pas touché.
Envoyez la liste complète

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

NomTypeRequisDescription
frameIdnumberouiIdentifiant 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
PHOTOGRAPHYPhoto
VIDEOVidéo
SIGNATURESignature
DOCUMENT_UPLOADDépôt de document
TEXT_FIELDChamp texte
NUMBER_FIELDChamp numérique
DATE_FIELDChamp date
TIMEChamp heure
EMAILAdresse e-mail
SELECTChoix 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.