Gestion des Items

Ce document détaille les différentes méthodes pour ajouter des items (éléments de données) à un dossier dans l'application Certificall.

Contrat v2 — nommer l'application qui dépose

Les endpoints POST /items/... sans préfixe /v2 sont dépréciés

Ils continuent de fonctionner à l'identique et leur URL ne change pas : aucune intégration existante n'est cassée. Ils ne figurent plus dans le Swagger et disparaîtront à terme. Migrez vers /v2 dès que possible.

Pourquoi

Quand un fichier est capturé par votre application puis déposé via notre API, Certificall ne voit ni l'appareil, ni le moment réel de la prise de vue. Le certificat produit porte donc un encart « Origine de la capture » qui nomme l'application déposante et précise la répartition des rôles :

Certificall atteste la réception et l'horodatage de ce fichier. La capture est le fait de l'application déposante.

Sur un dépôt sans fichier (texte, date, heure, email, nombre, liste), rien n'est horodaté : la clause devient « Certificall atteste la réception de cette donnée. Sa saisie est le fait de l'application déposante. » L'horodatage qualifié concerne les items porteurs d'un fichier — photo, vidéo, signature, document.

Sans le nom de votre application, cet encart ne nomme personne — et un certificat qui n'identifie pas l'auteur de la capture ne protège ni vous, ni votre client.

Trois champs obligatoires

Champ	Format	Ce qu'il devient sur le certificat
`clientAppName`	texte	Nom de l'application, sous « Application déposante »
`clientAppVersion`	texte	Version affichée à la suite du nom — permet de dater un incident et de rappeler un parc
`frontCreatedAt`	ISO 8601	Heure de prise de vue déclarée. Absente, la ligne ne s'affiche pas

Les champs userDevice* restent obligatoires comme en v1 et alimentent « Environnement déclaré ». L'adresse IP inscrite sur le certificat est celle constatée par nos serveurs, jamais une valeur transmise dans le corps de la requête.

Endpoints

Méthode	URL	Usage
`POST`	`/v2/items/create`	Item non-media (texte, sélection, date, email, nombre, heure)
`POST`	`/v2/items/:caseId`	Photo, vidéo, signature ou document
`POST`	`/v2/items/:caseId/document`	Document seul, avec le droit `p_api:case:create`

Les corps de requête, droits et codes de réponse sont identiques à leurs équivalents v1, aux trois champs ci-dessus près.

Exemple

curl -X POST 'https://admin.certificall.app/v2/certificall/api/items/798' \
  -H 'Authorization: Bearer <Votre_Token_JWT>' \
  -F 'file=@compteur.jpg' \
  -F 'createItemDto={
    "stepId": 1,
    "data": "compteur.jpg",
    "clientAppName": "AquaReleve Web",
    "clientAppVersion": "3.8.2",
    "frontCreatedAt": "2026-08-21T14:29:41+02:00",
    "userDeviceManufacturer": "Samsung",
    "userDeviceModel": "SM-S928B",
    "userDeviceName": "releve-terrain",
    "userDevicePlatform": "Chrome 141",
    "userDeviceOs": "Android",
    "userDeviceOsVersion": "15",
    "geolocLatitude": "47.393210",
    "geolocLongitude": "0.689410",
    "companyId": 25,
    "caseId": 798
  }'

Erreurs de contrat

Un champ manquant renvoie un 400 qui nomme le champ et indique quoi envoyer :

{
  "message": "Missing required field(s) in createItemDto: clientAppName, clientAppVersion. The certificate must name the application that performed the capture. Send clientAppName (your application name), clientAppVersion (its version) and frontCreatedAt (capture date, ISO 8601)."
}

Une date de capture mal formée renvoie également un 400, en rappelant le format attendu.

Migrer depuis la v1

Préfixez l'URL par /v2
Ajoutez clientAppName, clientAppVersion et frontCreatedAt à createItemDto

Rien d'autre ne change. En attendant votre migration, les dépôts effectués sur les anciens endpoints affichent l'identifiant de votre compte API à la place du nom de l'application.

Création d'un Item

Endpoint : `POST /items/create`

Description

Ce point d'API permet aux utilisateurs de créer des items dans un dossier. Les types d'items autorisés sont : texte, sélection, date, email, nombre et heure. Les types média (photo, vidéo, signature) et les documents (upload de fichier) ne sont pas autorisés via cet endpoint.

Requête

URL : /items/create
Méthode HTTP : POST

Headers requis :

Authorization: Bearer <Votre_Token_JWT>
Content-Type: application/json

Corps de la Requête (Payload)

caseId (Number, requis): Identifiant du dossier auquel ajouter l'item.
stepId (Number, requis): Identifiant de l'étape (obtenu via l'endpoint /frames).
data (String, requis): Données de l'item (le format dépend du type d'étape).
pos (Number, optionnel): Position de l'item dans un multi-step (par défaut : 0).

Exemple de corps de requête pour un champ texte :

{
  "caseId": 12345,
  "stepId": 101,
  "data": "Commentaire: Installation conforme",
  "pos": 0
}

Exemple de corps de requête pour une date :

{
  "caseId": 12345,
  "stepId": 102,
  "data": "2024-01-15",
  "pos": 0
}

Exemple de corps de requête pour un nombre :

{
  "caseId": 12345,
  "stepId": 103,
  "data": "42.5",
  "pos": 0
}

Types d'Items Autorisés

Les types d'items suivants sont autorisés :

TEXT_FIELD : Champ texte libre
SELECT : Liste de sélection
DATE : Date
EMAIL : Adresse email
NUMBER : Nombre
TIME : Heure

Les types suivants sont interdits et doivent utiliser l'endpoint /items/:caseId :

PHOTOGRAPHY : Photo
VIDEO : Vidéo
SIGNATURE : Signature
DOCUMENT_UPLOAD : Document — utilisez /items/:caseId/document (droit case:create, voir ci-dessous) ou /items/:caseId

Réponses

Réponse en cas de succès :

Code Statut: 200 OK
Description: L'item a été créé avec succès.

Exemple de réponse réussie :

{
  "id": 98765,
  "cfRef": "ITM-98765"
}

Réponse en cas d'échec :

Code Statut: 400 Bad Request
Description: La requête est invalide (Step ID manquant ou limite maximum atteinte).
Code Statut: 403 Forbidden
Description: Type non autorisé via cet endpoint (photo/video/signature/document).
Code Statut: 404 Not Found
Description: Le dossier ou l'étape spécifiée n'existe pas.

Cas d'Utilisation

Utilisez cet endpoint pour ajouter des données non-média à un dossier :

Commentaires textuels
Sélections dans des listes déroulantes
Dates d'intervention
Coordonnées email
Mesures numériques
Heures d'intervention

Ajout d'un Item avec Fichier

Endpoint : `POST /items/:caseId`

Description

Ce point d'API permet aux utilisateurs d'ajouter un item à un dossier avec upload de fichier. Cet endpoint est particulièrement adapté pour les photos, vidéos, signatures et autres types d'items nécessitant un fichier.

Requête

URL : /items/:caseId
Méthode HTTP : POST
Paramètres de chemin :
- caseId : number - L'identifiant unique du dossier.

Headers requis :

Authorization: Bearer <Votre_Token_JWT>
Content-Type: multipart/form-data

Corps de la Requête (Multipart Form-Data)

La requête doit être envoyée en multipart/form-data et contenir les champs suivants :

Champ file (optionnel) :

Type : Fichier binaire (image, vidéo, etc.)
Description : Le fichier à uploader (obligatoire pour les items de type photo, vidéo, signature)

Champ createItemDto (requis) :

Type : JSON stringifié
Description : Objet JSON contenant les informations de l'item

Structure du createItemDto :

companyId (Number, requis): Identifiant de l'entreprise.
stepId (Number, requis): Identifiant de l'étape (obtenu via /frames).
data (String, requis): Données de l'item ou nom du fichier pour les photos.
caseId (Number, optionnel): Identifiant du dossier (peut être omis car déjà dans l'URL).
userDeviceManufacturer (String, requis): Fabricant de l'appareil.
userDeviceModel (String, requis): Modèle de l'appareil.
userDeviceName (String, requis): Nom de l'appareil.
userDevicePlatform (String, requis): Plateforme de l'appareil (iOS, Android, etc.).
userDeviceOs (String, requis): Système d'exploitation.
userDeviceOsVersion (String, requis): Version du système d'exploitation.
userDeviceCarrierIpAddress (String, optionnel): Adresse IP du réseau mobile.
userDeviceWifiIpAddress (String, optionnel): Adresse IP du réseau WiFi.
geolocLatitude (String, optionnel): Latitude (obligatoire pour les photos).
geolocLongitude (String, optionnel): Longitude (obligatoire pour les photos).
geolocAccuracy (String, optionnel): Précision de la géolocalisation.
frontCreatedAt (String ISO 8601, optionnel): Date de création côté client. Permet de transmettre l'horodatage réel de la prise (ex. capture hors-ligne).

Exemple de Requête avec cURL

curl -X POST "https://admin.certificall.app/certificall/api/items/12345" \
  -H "Authorization: Bearer votre_token_jwt" \
  -F "file=@/chemin/vers/photo.jpg" \
  -F 'createItemDto={
    "companyId": 1,
    "stepId": 101,
    "data": "photo_facade.jpg",
    "userDeviceManufacturer": "Apple",
    "userDeviceModel": "iPhone 13",
    "userDeviceName": "iPhone de Jean",
    "userDevicePlatform": "iOS",
    "userDeviceOs": "iOS",
    "userDeviceOsVersion": "16.0",
    "geolocLatitude": "48.8566",
    "geolocLongitude": "2.3522",
    "geolocAccuracy": "5.0",
    "frontCreatedAt": "2026-05-28T10:30:00+02:00"
  }'

Réponses

Réponse en cas de succès :

Code Statut: 200 OK
Description: L'item a été créé et le fichier uploadé avec succès.

Exemple de réponse réussie :

{
  "id": 98765,
  "cfRef": "ITM-98765",
  "fileUrl": "https://certificall.app/files/photo_facade.jpg"
}

Réponse en cas d'échec :

Code Statut: 400 Bad Request
Description: La requête est invalide (paramètres manquants ou incorrects).
Code Statut: 403 Forbidden
Description: Vous n'avez pas les permissions nécessaires ou le dossier n'appartient pas à votre entreprise.
Code Statut: 413 Payload Too Large
Description: Le fichier uploadé est trop volumineux.

Permissions Requises

Le dossier doit appartenir à votre entreprise.
Votre entreprise doit être autorisée à utiliser cette API, contactez Certificall pour savoir si c'est le cas

Types d'Items Supportés

Cet endpoint supporte tous les types d'items, notamment :

PHOTOGRAPHY : Photos avec géolocalisation
VIDEO : Vidéos
SIGNATURE : Signatures
TEXT_FIELD, SELECT, DATE, EMAIL, NUMBER, TIME : Items non-média

Cas d'Utilisation

Utilisez cet endpoint pour :

Ajouter des photos avec métadonnées de localisation
Uploader des vidéos d'inspection
Capturer des signatures numériques
Ajouter tout type d'item avec traçabilité complète de l'appareil

Upload d'un Document (droit case:create)

Endpoint : `POST /items/:caseId/document`

Description

Uploade un document (PDF, JPEG, PNG) sur une étape de type DOCUMENT_UPLOAD, avec le seul droit p_api:case:create — sans nécessiter le droit média p_api:item:create (réservé aux photos, vidéos et signatures).

Cet endpoint n'accepte que les étapes DOCUMENT_UPLOAD (403 sinon, 404 si l'étape n'existe pas). Mêmes contraintes fichier que l'endpoint général : taille max ~10 Mo, type réel vérifié. Si l'étape a une analyse documentaire configurée, elle est déclenchée automatiquement en asynchrone.

Le format de la requête (multipart file + createItemDto) est identique à POST /items/:caseId ci-dessus.

Documentation détaillée (exemples, codes d'erreur, récupération du résultat d'analyse) : voir API — Analyse documentaire.

Sécurité et Bonnes Pratiques

Récupérez d'abord la liste des étapes disponibles via l'endpoint /frames pour obtenir les stepId valides.
Assurez-vous que le format de data correspond au type d'étape attendu.
Pour les photos, la géolocalisation (geolocLatitude, geolocLongitude) est obligatoire.
Incluez toujours les informations complètes de l'appareil pour assurer la traçabilité.
Limitez la taille des fichiers uploadés pour éviter les erreurs de timeout.
Vérifiez que le dossier n'est pas encore fermé avant d'ajouter des items.
Les interactions avec l'API Certificall doivent toujours être effectuées via une connexion sécurisée (HTTPS).

En suivant ces instructions, vous pourrez ajouter en toute sécurité des items à vos dossiers via l'API Certificall.

Contrat v2 — nommer l'application qui dépose​

Pourquoi​

Trois champs obligatoires​

Endpoints​

Exemple​

Erreurs de contrat​

Migrer depuis la v1​

Création d'un Item​

Endpoint : POST /items/create​

Description​

Requête​

Corps de la Requête (Payload)​

Types d'Items Autorisés​

Réponses​

Cas d'Utilisation​

Ajout d'un Item avec Fichier​

Endpoint : POST /items/:caseId​

Description​

Requête​

Corps de la Requête (Multipart Form-Data)​

Exemple de Requête avec cURL​

Réponses​

Permissions Requises​

Types d'Items Supportés​

Cas d'Utilisation​

Upload d'un Document (droit case:create)​

Endpoint : POST /items/:caseId/document​

Description​

Sécurité et Bonnes Pratiques​

Contrat v2 — nommer l'application qui dépose

Pourquoi

Trois champs obligatoires

Endpoints

Exemple

Erreurs de contrat

Migrer depuis la v1

Création d'un Item

Endpoint : `POST /items/create`

Description

Requête

Corps de la Requête (Payload)

Types d'Items Autorisés

Réponses

Cas d'Utilisation

Ajout d'un Item avec Fichier

Endpoint : `POST /items/:caseId`

Description

Requête

Corps de la Requête (Multipart Form-Data)

Exemple de Requête avec cURL

Réponses

Permissions Requises

Types d'Items Supportés

Cas d'Utilisation

Upload d'un Document (droit case:create)

Endpoint : `POST /items/:caseId/document`

Description

Sécurité et Bonnes Pratiques