Gestion des Dossiers (Cases)

Ce document détaille le fonctionnement et l'utilisation des endpoints pour gérer les dossiers dans l'application Certificall.

Recherche de Dossiers

Endpoint : `GET /cases`

Description

Le endpoint de recherche de dossiers permet aux utilisateurs authentifiés d'interroger et de récupérer des dossiers enregistrés dans le système Certificall, en appliquant des filtres variés pour affiner les résultats selon les besoins spécifiques.

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 : /cases

Paramètres de la requête (Query Parameters)

Filtres généraux

reportToken (String, optionnel): Token du rapport associé aux dossiers recherchés.
companyId (Number, optionnel): Identifiant de l'entreprise associée aux dossiers.
frameId (Number, optionnel): Identifiant de la trame utilisée pour les dossiers.
caseId (Number, optionnel): Identifiant du dossier recherché.
withReportToken (Boolean, optionnel): Indique si le token du rapport doit être inclus dans les résultats.
closed (Boolean, optionnel): Filtre par statut. Valeurs acceptées : true (dossiers clôturés uniquement) ou false (dossiers ouverts uniquement). Si le paramètre est absent ou ne correspond pas à un booléen valide, l'endpoint retourne dossiers ouverts ET clôturés.
format (Enum, requis): Spécifie le format de la réponse (zip ou metadata).

Fenêtre temporelle (filtre sur `createdAt`)

Trois modes au choix, mutuellement exclusifs :

hours (Number, optionnel): Fenêtre relative — nombre d'heures dans le passé depuis maintenant. Max 168 (1 semaine), défaut 12 heures.
startDate (String, optionnel): Borne inférieure absolue (incluse). Accepté : ISO 8601 avec timezone ("2026-04-23T08:00:00+02:00") ou date seule ("2026-04-23", interprétée comme minuit UTC).
endDate (String, optionnel): Borne supérieure absolue (incluse). Mêmes formats. Une date seule est étendue à la fin de journée UTC (23:59:59.999). Un datetime ISO strictement égal à minuit UTC est traité comme une date seule.

⚠️ hours et startDate/endDate sont mutuellement exclusifs (400 si les deux sont fournis).

Amplitude max entre startDate et endDate : 7 jours (400 si dépassée).

Pagination

Pagination opt-in : sans limit ni offset, l'endpoint retourne tous les dossiers matched (comportement legacy). La pagination s'active dès que l'un des deux est fourni.

limit (Number, optionnel): Nombre max de dossiers retournés. Défaut: 50, max: 100.
offset (Number, optionnel): Nombre de dossiers à ignorer. Défaut: 0.

Le total de dossiers matchés est exposé via le header HTTP X-Total-Count dans la réponse (toujours présent, même sans pagination explicite). Itérer en incrémentant offset de limit jusqu'à recevoir 0 dossiers.

Note : limit et offset s'appliquent aussi au format zip. Pour exporter au-delà de limit en ZIP, itérer sur plusieurs requêtes paginées.

Exemple :

curl -X 'GET' \
'https://admin.certificall.app/certificall/api/cases?format=metadata&hours=48' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'

Réponses

200 OK : Retourne une liste de dossiers correspondant aux critères spécifiés.

Exemple de réponse pour une demande avec format=metadata :

[
  {
    "id": 12345,
    "cfRef": "REF123",
    "closingDate": "2023-01-01T00:00:00Z",
    "createdAt": "2022-12-01T00:00:00Z",
    "scheduledAt": "2026-06-15T00:00:00.000Z",
    "closed": true,
    "frame": "Trame A",
    "companyName": "Entreprise XYZ",
    "reportId": "TOKEN123",
    "caseUrl": "https://certificall.example.com/download/SHARETOKEN123",
    "metadata": { "site": "Paris", "zone": "A1" }
  }
]

id (number) : identifiant numérique interne du dossier, utile pour les opérations subséquentes (/cases/close/:caseId, /cases/delete/:caseId). cfRef (string) : identifiant public au format CAS-XXXX_CMP-Y.

metadata (object) : métadonnées libres du dossier, telles que vous les avez fournies à sa création — par le champ metadata de POST /cases/create, par un Certilink ou par le SDK mobile. La clé est absente du dossier qui n'en porte aucune. Elle ne sert pas à retrouver un dossier (utilisez reportToken), mais elle filtre la consommation.

scheduledAt (string ISO 8601 | null) : date à laquelle le dossier devient visible sur l'app mobile. null si le dossier n'est pas planifié.

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.

Cas pratique

Récupérer les `id` des dossiers créés entre 6h et 11h aujourd'hui qui ne sont pas clôturés

Combinaison startDate + endDate (fenêtre absolue avec timezone) + closed=false + extraction de l'id via jq :

TODAY=$(date +%Y-%m-%d)

curl -s -X 'GET' \
  "https://admin.certificall.app/certificall/api/cases?format=metadata&startDate=${TODAY}T06:00:00%2B02:00&endDate=${TODAY}T11:00:00%2B02:00&closed=false" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq -r '.[].id'

Sortie attendue (un id par ligne) :

4582
4581
4576

Pour un format plus riche (id + cfRef + heure de création) :

... | jq -r '.[] | "\(.id)\t\(.cfRef)\t\(.createdAt)"'

Notes :

%2B02:00 est l'encodage URL de +02:00 (timezone Europe/Paris). Adapter selon la TZ.

Pour vérifier le total disponible avant d'itérer, lire le header X-Total-Count :

curl -sI -H "Authorization: Bearer ${TOKEN}" "<même URL>" | grep -i x-total-count

Si plus de 50 dossiers attendus, ajouter &limit=100&offset=0 puis itérer en incrémentant offset.

Création d'un Dossier

Endpoint : `POST /cases/create`

Description

Ce point d'API permet aux utilisateurs authentifiés de créer un nouveau dossier dans le système Certificall. Le dossier peut être associé à un utilisateur spécifique ou à un certilink (Magic Link) pour une utilisation sans authentification.

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 : POST URL : /cases/create

Corps de la Requête (Payload)

Paramètre requis :

frameId (Number): Identifiant de la trame (frame) à utiliser pour le dossier.

Paramètres optionnels :

title (String): Titre du dossier.
userId (String): Identifiant Keycloak de l'utilisateur à associer au dossier (exclusif avec magicLinkToken).
userMail (String): Email de l'utilisateur à associer au dossier (alternatif à userId, exclusif avec magicLinkToken). Le système résout automatiquement l'identifiant Keycloak à partir de l'email. L'utilisateur doit exister dans Certificall (s'être connecté au moins une fois).
childCompanyId (Number): ID de la company enfant cible (utilisé uniquement avec certilink).
magicLinkToken (String): Token d'un certilink existant à utiliser (exclusif avec userId).
certilinkOptions (Object): Options pour créer un nouveau certilink automatiquement.
- reportToken (String, requis): Token du rapport unique pour le certilink.
- maxUses (Number, optionnel): Nombre maximal d'utilisations autorisées.
- expirationDate (String, optionnel): Date d'expiration (format : aaaa-mm-jjThh:mm:ss.sss+hhmm).
reportToken (String): Token du rapport pour associer ou créer un rapport.
caseContext (Object): Contexte du dossier (données visibles).
- visibleData (Object): Données visibles dans le dossier.
  - beneficiary (Object): Informations du bénéficiaire.
    - lastName (String): Nom de famille.
    - firstName (String): Prénom.
    - address (String): Adresse.
    - city (String): Ville.
    - postCode (String): Code postal.
    - email (String): Adresse email.
  - issuer (String): Émetteur du dossier.
  - photoRef (String): Référence photo.
  - reportRef (String): Référence du rapport.
  - instructions (String): Instructions spécifiques pour l'utilisateur.
  - user (String): Nom de l'utilisateur à afficher dans le PDF.
metadata (Object, optionnel) : métadonnées libres du dossier, paires clé-valeur de texte (20 clés max, 40 caractères par clé, 500 par valeur). Restituées avec le dossier dans GET /cases et dans le webhook de dossier.
scheduledAt (String ISO 8601, optionnel): Date planifiée du dossier. Doit être dans le mois courant ou un mois futur. Le dossier est masqué sur l'app mobile tant que le mois cible n'est pas atteint. Formats acceptés : ISO 8601 avec timezone (recommandé, ex. "2026-05-15T14:00:00+02:00"), date seule ("2026-05-15", interprétée minuit Europe/Paris (UTC+2)).

Exemples de Requêtes

Exemple 1 : Créer un dossier pour un utilisateur spécifique

{
  "frameId": 10,
  "title": "Inspection technique",
  "userId": "user-keycloak-id-123",
  "reportToken": "RAPPORT-2024-001",
  "caseContext": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Dupont",
        "firstName": "Jean",
        "email": "jean.dupont@example.com"
      },
      "issuer": "ACME Company",
      "instructions": "Vérifier l'état général du matériel"
    }
  },
  "metadata": {
    "source": "api",
    "version": "1.0"
  }
}

Exemple 2 : Créer un dossier avec un certilink automatique

{
  "frameId": 10,
  "title": "Inspection externe",
  "certilinkOptions": {
    "reportToken": "RAPPORT-2024-002",
    "maxUses": 5,
    "expirationDate": "2025-12-31T23:59:59.000+0100"
  },
  "caseContext": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Martin",
        "firstName": "Sophie",
        "address": "123 Rue de la Paix",
        "city": "Paris",
        "postCode": "75001",
        "email": "sophie.martin@example.com"
      },
      "instructions": "Veuillez noter le numéro d'appartement"
    }
  }
}

Exemple 3 : Créer un dossier avec un certilink existant

{
  "frameId": 10,
  "magicLinkToken": "09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
  "title": "Inspection programmée",
  "caseContext": {
    "visibleData": {
      "issuer": "Société ABC",
      "instructions": "Suivre le protocole standard"
    }
  }
}

Exemple 4 : Créer un dossier planifié pour un mois futur

{
  "frameId": 10,
  "title": "Inspection programmée juin",
  "userId": "user-id-123",
  "scheduledAt": "2026-06-15T00:00:00+02:00"
}

Planification (scheduledAt)

Un dossier planifié est masqué sur l'app mobile tant que le mois indiqué n'est pas le mois courant. Utile pour préparer à l'avance des dossiers récurrents (inspections mensuelles, certifications planifiées). Le champ est lisible via GET /cases et modifiable via PATCH /cases/update (passer null pour retirer la planification).

Réponses

Réponse en cas de succès :

Statut : 201 Created
Description : Le dossier a été créé avec succès.

Exemple de réponse :

{
  "id": 12345,
  "cfRef": "CAS-12345_CMP-1",
  "frameId": 10,
  "title": "Inspection technique",
  "createdAt": "2024-01-15T10:30:00Z",
  "closed": false,
  "magicLinkUrl": "https://app.certificall.app/?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
}

Réponse en cas d'erreur :

Statut : 400 Bad Request

Description : La requête est invalide (paramètres manquants ou incorrects).

{
  "statusCode": 400,
  "message": "frameId is required",
  "error": "Bad Request"
}

Statut : 403 Forbidden
Description : Vous n'avez pas les permissions nécessaires pour créer un dossier.
Statut : 404 Not Found
Description : La trame (frame) spécifiée n'existe pas ou n'appartient pas à votre entreprise.

Permissions Requises

L'utilisateur doit disposer du scope p_api et de la permission create sur la ressource case.
La trame (frame) doit appartenir à votre entreprise ou être accessible.

Cas d'Utilisation

Utilisez cet endpoint pour :

Créer un dossier destiné à un utilisateur spécifique de votre équipe
Générer un dossier accessible via un certilink (Magic Link) pour des utilisateurs externes
Initialiser un dossier avec des informations préremplies (bénéficiaire, instructions, etc.)
Créer un dossier et un certilink en une seule opération

Notes Importantes

userId, userMail et magicLinkToken sont mutuellement exclusifs : vous devez utiliser l'un ou l'autre, mais pas plusieurs à la fois.
Si vous utilisez certilinkOptions, un nouveau certilink sera créé automatiquement pour ce dossier.
Le champ reportToken dans certilinkOptions est requis si vous utilisez cette option.
Les métadonnées doivent être des paires clé-valeur avec des valeurs de type chaîne de caractères.

Plusieurs dossiers à créer ?

N'appelez pas cet endpoint en boucle : vous atteindriez vite la limite d'appels et recevriez un 429. Utilisez la création en masse ci-dessous, qui ne compte que pour une seule requête.

Création en Masse

Endpoint : `POST /cases/bulk-create`

Crée plusieurs dossiers en une seule requête. Conçu pour les intégrations qui doivent ouvrir un ensemble de dossiers d'un coup — par exemple un dossier par intervention d'un même chantier.

Un seul appel est compté, quelle que soit la taille du tableau. Cet endpoint a sa propre limite d'appels de 10 requêtes par minute — soit jusqu'à 500 dossiers créés par minute, contre 60 en bouclant sur la création unitaire.

Requête

POST /certificall/api/cases/bulk-create
Authorization: Bearer <Votre_Token_JWT>
Content-Type: application/json

Le corps est un tableau d'objets, chacun au même format que la création unitaire (POST /cases/create) :

[
  { "frameId": 10, "title": "Intervention lot A", "userMail": "technicien@example.com" },
  { "frameId": 10, "title": "Intervention lot B", "userMail": "technicien@example.com" },
  { "frameId": 12, "title": "Contrôle final" }
]

Limite : 50 dossiers maximum par requête. Au-delà, l'API répond 400 — découpez votre traitement en plusieurs appels.

Pas de dédoublonnage

Deux lignes identiques dans le tableau créent deux dossiers distincts. Avant de renvoyer une requête interrompue (coupure réseau, timeout), vérifiez via GET /cases quels dossiers ont déjà été créés.

Permissions Requises

Deux droits sont nécessaires :

Droit	Rôle
`p_api:case:create`	Création d'un dossier
`p_api:case:bulk_create`	Accès à la création en masse

S'il en manque un, l'API répond 403 et aucun dossier n'est créé.

Réponse

Code statut : 200 OK, même si certains dossiers échouent. Chaque dossier est créé indépendamment : l'échec de l'un n'annule pas les autres, et les dossiers déjà créés sont conservés.

{
  "state": "Cases bulk create ended",
  "date": "2026-09-15T09:12:34.567Z",
  "company": 42,
  "success": [
    { "index": 0, "caseId": 12345 },
    { "index": 2, "caseId": 12346 }
  ],
  "error": [
    { "index": 1, "error": "Error while creating case" }
  ]
}

Champ	Description
`success`	Dossiers effectivement créés
`error`	Lignes non créées, avec le motif de chacune
`index`	Position dans le tableau que vous avez envoyé
`caseId`	Identifiant attribué au dossier créé. Absent des entrées de `error`, puisque le dossier n'existe pas

Contrôlez toujours le tableau error

Un 200 ne signifie pas que tous les dossiers ont été créés. Parcourez error pour identifier les lignes à corriger puis à renvoyer.

L'ordre de traitement n'est pas garanti : appuyez-vous sur index pour rattacher chaque caseId à la ligne correspondante de votre requête. Seul l'identifiant est renvoyé ; pour obtenir le détail d'un dossier créé, utilisez GET /cases avec le paramètre caseId.

Le motif d'échec est celui renvoyé par le service métier (trame introuvable, utilisateur inconnu…) ou, à défaut, Error while creating case. Ces libellés ne sont pas stables dans le temps : routez vos erreurs sur la présence de la ligne dans error[] plutôt que sur le texte exact.

Erreurs de requête

Dans ces cas, aucun dossier n'est créé :

Statut	Contexte
`400`	Tableau vide, plus de 50 dossiers, ou élément invalide. Les erreurs de tous les éléments sont renvoyées, préfixées par leur position : `[1] frameId must be a number conforming to the specified constraints`
`403`	L'un des deux droits requis est manquant
`429`	Limite de 10 requêtes par minute dépassée sur cet endpoint

Fermeture d'un Dossier

Deux endpoints sont disponibles selon la méthode d'identification du dossier à clôturer : par caseId ou par certilink token.

Endpoint : `GET /cases/close/:caseId`

Description

Ferme un dossier en cours en utilisant son identifiant. Une fois fermé, le dossier est finalisé et ne peut plus être modifié.

Requête

URL : /cases/close/:caseId
Méthode HTTP : GET
Paramètres de chemin :
- caseId : number — Identifiant unique du dossier à fermer.
Headers requis :
```
Authorization: Bearer <Votre_Token_JWT>
```

Permissions

Le dossier doit appartenir à votre entreprise.

Endpoint : `GET /cases/close/certilink/:magicLinkToken`

Description

Ferme automatiquement le dossier ouvert rattaché à un Certilink. Utile pour les intégrations externes qui disposent uniquement du token Certilink et non du caseId.

Ce endpoint fonctionne uniquement si le Certilink est rattaché à un seul dossier non clos. Si plusieurs dossiers sont ouverts sur le Certilink, utilisez /cases/close/:caseId avec l'identifiant explicite.

Requête

URL : /cases/close/certilink/:magicLinkToken
Méthode HTTP : GET
Paramètres de chemin :
- magicLinkToken : UUID — Token du Certilink (UUID v4).
Headers requis :
```
Authorization: Bearer <Votre_Token_JWT>
```

À venir

Support du paramètre shortlink en alternative au magicLinkToken (voir ticket CER-1195).

Permissions

Le Certilink doit appartenir à votre entreprise (ou à une sous-entreprise).

Exemple cURL

curl -X GET \
  "https://admin.certificall.app/certificall/api/cases/close/certilink/00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer <JWT>"

Réponses (communes aux deux endpoints)

Succès — 200 OK :

{
  "status": "Success",
  "message": "Case closed successfully"
}

Erreurs :

Statut	Contexte
`400`	Requête invalide, dossier déjà clôturé, ou plusieurs dossiers rattachés au Certilink (préciser `caseId`)
`403`	Le dossier ou le Certilink n'appartient pas à votre entreprise
`404`	Aucun dossier ouvert à clôturer pour ce Certilink
`405`	UUID invalide

Cas d'usage

Finalisation classique d'un dossier : GET /cases/close/:caseId
Intégration externe avec un Certilink unique par dossier : GET /cases/close/certilink/:magicLinkToken

Mise à Jour d'un Dossier

Endpoint : `PATCH /cases/update`

Description

Ce point d'API permet aux utilisateurs de mettre à jour les informations d'un dossier existant. Vous pouvez modifier le titre, la trame associée, l'utilisateur, le token de rapport ou le contexte du dossier.

Requête

URL : /cases/update
Méthode HTTP : PATCH

Headers requis :

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

Corps de la Requête (Payload)

caseId (Number, requis): Identifiant du dossier à mettre à jour.
title (String, optionnel): Nouveau titre du dossier (maximum 255 caractères).
frameId (Number, optionnel): Identifiant de la nouvelle trame à associer.
userId (String, optionnel): Identifiant Keycloak de l'utilisateur à associer.
reportToken (String, optionnel): Token du rapport à associer au dossier.
caseContext (Object, optionnel): Contexte du dossier (données visibles).
- visibleData (Object, optionnel): Données visibles dans le dossier.
  - beneficiary (Object, optionnel): Informations du bénéficiaire.
    - lastName (String): Nom de famille.
    - firstName (String): Prénom.
    - address (String): Adresse.
    - city (String): Ville.
    - postCode (String): Code postal.
    - email (String): Adresse email.
  - issuer (String): Émetteur du dossier.
  - photoRef (String): Référence photo.
  - reportRef (String): Référence du rapport.
  - instructions (String): Instructions spécifiques.
  - user (String): Nom de l'utilisateur à afficher.
metadata (Object, optionnel) : métadonnées libres du dossier, paires clé-valeur de texte (20 clés max, 40 caractères par clé, 500 par valeur). Remplacent celles du dossier ; null les efface. Restituées dans GET /cases et dans le webhook de dossier.
scheduledAt (String ISO 8601 | null, optionnel): Met à jour la date planifiée du dossier. Passer null pour retirer la planification (le dossier redevient visible immédiatement sur mobile). Doit être dans le mois courant ou futur.

Exemple de corps de requête :

{
  "caseId": 12345,
  "title": "Inspection mise à jour",
  "reportToken": "RAPPORT-2024-001",
  "caseContext": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Dupont",
        "firstName": "Jean",
        "email": "jean.dupont@example.com"
      },
      "issuer": "ACME Company",
      "instructions": "Vérifier l'état général du matériel"
    }
  },
  "metadata": {
    "source": "api",
    "version": "2.0"
  }
}

Réponses

Réponse en cas de succès :

Code Statut: 200 OK
Description: Le dossier a été mis à jour avec succès.

Exemple de réponse réussie :

{
  "success": true
}

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: 404 Not Found
Description: Le dossier spécifié n'existe pas.

Permissions Requises

Le dossier doit appartenir à votre entreprise pour pouvoir être mis à jour.

Cas d'Utilisation

Utilisez cet endpoint pour :

Corriger le titre d'un dossier
Modifier les informations du bénéficiaire
Associer un nouveau token de rapport
Ajouter ou modifier des métadonnées
Changer la trame associée au dossier
Planifier un dossier pour un mois futur via scheduledAt
Retirer la planification en passant scheduledAt: null

Plusieurs dossiers à mettre à jour ?

N'appelez pas cet endpoint en boucle : vous atteindriez vite la limite d'appels et recevriez un 429. Utilisez la mise à jour en masse ci-dessous, qui ne compte que pour une seule requête.

Mise à Jour en Masse

Endpoint : `PATCH /cases/bulk-update`

Met à jour plusieurs dossiers en une seule requête. Conçu pour les intégrations qui doivent propager une même information sur un ensemble de dossiers liés — par exemple répercuter un changement de date sur tous les dossiers rattachés à une même affaire.

Un seul appel est compté, quelle que soit la taille du tableau. Cet endpoint a sa propre limite d'appels de 10 requêtes par minute — soit jusqu'à 1000 dossiers mis à jour par minute, contre 60 en bouclant sur la mise à jour unitaire.

Requête

PATCH /certificall/api/cases/bulk-update
Authorization: Bearer <Votre_Token_JWT>
Content-Type: application/json

Le corps est un tableau d'objets, chacun au même format que la mise à jour unitaire :

[
  { "caseId": 12345, "scheduledAt": "2026-09-10T09:00:00+02:00" },
  { "caseId": 12346, "scheduledAt": "2026-09-10T09:00:00+02:00" },
  { "caseId": 12347, "scheduledAt": "2026-09-10T09:00:00+02:00" }
]

Limite : 100 dossiers maximum par requête. Au-delà, l'API répond 400 — découpez votre traitement en plusieurs appels.

Permissions Requises

Deux droits sont nécessaires :

Droit	Rôle
`p_api:case:update`	Mise à jour d'un dossier
`p_api:case:bulk_update`	Accès à la mise à jour en masse

S'il en manque un, l'API répond 403 et aucun dossier n'est traité.

Réponse

Code statut : 200 OK, même si certains dossiers échouent. Chaque dossier est traité indépendamment : l'échec de l'un n'annule pas les autres.

{
  "state": "Cases bulk update ended",
  "date": "2026-08-13T09:12:34.567Z",
  "company": 42,
  "success": [
    { "index": 0, "caseId": 12345 },
    { "index": 2, "caseId": 12347 }
  ],
  "error": [
    { "index": 1, "caseId": 12346, "error": "case.notBelongCompany" }
  ]
}

Champ	Description
`success`	Dossiers effectivement mis à jour
`error`	Dossiers en échec, avec le motif de chacun
`index`	Position dans le tableau que vous avez envoyé
`caseId`	Identifiant du dossier concerné

Contrôlez toujours le tableau error

Un 200 ne signifie pas que tous les dossiers ont été mis à jour. Parcourez error pour identifier ceux qui ont échoué et pourquoi.

L'ordre de traitement n'est pas garanti : ne vous fiez pas à la position dans success ou error, mais au champ index, qui pointe la position d'origine dans votre requête.

Motifs d'échec fréquents

Message	Cause
`case.notBelongCompany`	Le dossier appartient à une autre entreprise
`case.scheduledAt.mustBeCurrentOrFutureMonth`	La date planifiée est antérieure au mois courant
`case.scheduledAt.invalid`	Format de date non reconnu
`Error while updating case`	Le dossier n'existe pas, ou le service métier est momentanément indisponible

remarque

Ces libellés proviennent du service métier et ne sont pas stables dans le temps. Pour router vos erreurs, appuyez-vous sur la présence du dossier dans error[] plutôt que sur le texte exact.

Suppression d'un Dossier

Endpoint : `DELETE /cases/delete/:caseId`

Description

Ce point d'API permet aux utilisateurs de supprimer définitivement un dossier du système. Cette action est irréversible et supprime toutes les données associées au dossier.

Requête

URL : /cases/delete/:caseId
Méthode HTTP : DELETE
Paramètres de chemin :
- caseId : number - L'identifiant unique du dossier à supprimer.
Headers requis :
```
Authorization: Bearer <Votre_Token_JWT>
```

Réponses

Réponse en cas de succès :

Statut : 200 OK
Description : Le dossier a été supprimé avec succès.

Exemple de réponse :

{
  "status": "Success",
  "message": "Case deleted successfully"
}

Réponse en cas d'erreur :

Statut : 400 Bad Request
Description : La requête est invalide ou le dossier n'existe pas.
Statut : 403 Forbidden
Description : Vous n'avez pas les permissions nécessaires ou le dossier n'appartient pas à votre entreprise.

Permissions Requises

Le dossier doit appartenir à votre entreprise pour pouvoir être supprimé.

Avertissement

⚠️ ATTENTION : Cette opération est irréversible. Une fois le dossier supprimé, toutes les données associées (items, photos, vidéos, métadonnées) seront définitivement perdues.

Cas d'Utilisation

Utilisez cet endpoint uniquement lorsque vous avez besoin de supprimer définitivement un dossier, par exemple :

Dossier créé par erreur
Données erronées qui nécessitent une suppression complète
Respect des politiques de conservation des données

Plusieurs dossiers à supprimer ?

N'appelez pas cet endpoint en boucle : vous atteindriez vite la limite d'appels et recevriez un 429. Utilisez la suppression en masse ci-dessous, qui ne compte que pour une seule requête.

Suppression en Masse

Endpoint : `POST /cases/bulk-delete`

Supprime plusieurs dossiers en une seule requête. Chaque dossier est supprimé exactement comme avec la suppression unitaire.

Un seul appel est compté, quelle que soit la taille du tableau. Cet endpoint a sa propre limite d'appels de 10 requêtes par minute — soit jusqu'à 500 dossiers supprimés par minute, contre 60 en bouclant sur la suppression unitaire.

Requête

POST /certificall/api/cases/bulk-delete
Authorization: Bearer <Votre_Token_JWT>
Content-Type: application/json

Le corps est un objet contenant la liste des identifiants à supprimer :

{
  "caseIds": [12345, 12346, 12347]
}

Pourquoi POST et non DELETE ?

De nombreux clients HTTP et proxys gèrent mal un corps de requête sur DELETE. POST garantit que la liste des dossiers arrive intacte jusqu'à l'API.

Limite : 50 dossiers maximum par requête, sans doublon. Au-delà, l'API répond 400 — découpez votre traitement en plusieurs appels.

Opération irréversible

Comme pour la suppression unitaire, toutes les données associées aux dossiers supprimés (items, photos, vidéos, métadonnées) sont définitivement perdues. Vérifiez la liste des identifiants avant l'envoi.

Permissions Requises

Deux droits sont nécessaires :

Droit	Rôle
`p_api:case:delete`	Suppression d'un dossier
`p_api:case:bulk_delete`	Accès à la suppression en masse

S'il en manque un, l'API répond 403 et aucun dossier n'est supprimé.

Réponse

Code statut : 200 OK, même si certains dossiers échouent. Chaque dossier est traité indépendamment : l'échec de l'un n'annule pas les autres.

{
  "state": "Cases bulk delete ended",
  "date": "2026-09-15T09:12:34.567Z",
  "company": 42,
  "success": [
    { "index": 0, "caseId": 12345 },
    { "index": 2, "caseId": 12347 }
  ],
  "error": [
    { "index": 1, "caseId": 12346, "error": "Error while deleting case" }
  ]
}

Champ	Description
`success`	Dossiers effectivement supprimés
`error`	Dossiers en échec, avec le motif de chacun
`index`	Position dans le tableau `caseIds` que vous avez envoyé
`caseId`	Identifiant du dossier concerné

Contrôlez toujours le tableau error

Un 200 ne signifie pas que tous les dossiers ont été supprimés. Parcourez error pour identifier ceux qui ont échoué et pourquoi.

L'ordre de traitement n'est pas garanti : ne vous fiez pas à la position dans success ou error, mais au champ index.

Le motif d'échec est celui renvoyé par le service métier (dossier d'une autre entreprise, dossier inexistant…) ou, à défaut, Error while deleting case. Ces libellés ne sont pas stables dans le temps : routez vos erreurs sur la présence du dossier dans error[] plutôt que sur le texte exact.

Erreurs de requête

Dans ces cas, aucun dossier n'est supprimé :

Statut	Contexte
`400`	`caseIds` vide, plus de 50 identifiants, identifiant non numérique, ou même identifiant présent plusieurs fois
`403`	L'un des deux droits requis est manquant
`429`	Limite de 10 requêtes par minute dépassée sur cet endpoint

Analyse d'un Dossier

Endpoint : `GET /cases/:caseId/analysis`

Description

Retourne l'analyse de confiance complète d'un dossier : score global, signaux par dimension métier (géolocalisation, device, photo, document…) et, si une analyse documentaire a été déclenchée, le détail par document.

Analyse documentaire asynchrone

L'analyse documentaire (OCR + scoring Itesoft) s'exécute en arrière-plan après l'upload. Si elle n'est pas encore terminée, le bloc documentAnalyses peut être partiel — vérifiez progressStatusLevel === "ANALYSIS_COMPLETED" avant d'exploiter les scores documentaires.

Pour aller plus loin

La page Analyse documentaire décrit le flux complet : upload du document (POST /items/:caseId/document) puis récupération du résultat avec cet endpoint.

Requête

URL : /cases/:caseId/analysis
Méthode HTTP : GET
Paramètres de chemin :
- caseId : number — Identifiant unique du dossier.
Headers requis :
```
Authorization: Bearer <Votre_Token_JWT>
```

Permissions Requises

Scope p_api, ressource case, action read.
Le dossier doit appartenir à votre entreprise.

Exemple

curl -X GET \
  "https://admin.certificall.app/certificall/api/cases/12345/analysis" \
  -H "Authorization: Bearer votre_token_jwt"

Réponse en cas de succès

Statut : 200 OK

{
  "caseId": 12345,
  "trustScore": 86,
  "trustLevel": "GOOD",
  "itemsAnalyzed": 5,
  "signals": [
    { "key": "gps",       "score": 95, "trustLevel": "GOOD" },
    { "key": "motion",    "score": 80, "trustLevel": "GOOD" },
    { "key": "device",    "score": 90, "trustLevel": "GOOD" },
    { "key": "image",     "score": 85, "trustLevel": "GOOD" },
    { "key": "duplicate", "score": 100,"trustLevel": "GOOD" },
    { "key": "document",  "score": 88, "trustLevel": "GOOD" }
  ],
  "documentAnalyses": [
    {
      "itemId": 67890,
      "expectedDocumentTypes": ["INVOICE"],
      "detectedDocumentType": "INVOICE",
      "typeMatchScore": 100,
      "crossCheckResults": [
        { "fieldCode": "totalAmount", "fieldLabel": "Montant total", "match": "MATCH" },
        { "fieldCode": "customerName", "fieldLabel": "Nom du client", "match": "MATCH" }
      ],
      "crossCheckScore": 100,
      "suspicionLevel": "NONE",
      "evaluation": 96,
      "suspicionScore": 96,
      "progressStatusLevel": "ANALYSIS_COMPLETED",
      "trustScore": 97,
      "analysisDetails": [
        {
          "code": "FONT_CONSISTENCY",
          "label": "Cohérence des polices",
          "status": "VALID",
          "evaluation": 95,
          "suspicionLevel": "NONE",
          "weight": 2
        }
      ]
    }
  ]
}

Modèle de données

`ApiCaseAnalysisDto` — analyse du dossier

Champ	Type	Description
`caseId`	Number	Identifiant du dossier.
`trustScore`	Number	Score de confiance global (0–100, 100 = confiance maximale).
`trustLevel`	String	`GOOD` (70–100) \| `SUSPICIOUS` (30–69) \| `CRITICAL` (0–29).
`itemsAnalyzed`	Number	Nombre d'items analysés.
`signals`	Array	Score par dimension (voir tableau ci-dessous).
`documentAnalyses`	Array	Détail par document analysé (voir ci-dessous). Vide si aucune étape document dans le dossier.

`signals` — clés possibles

Clé	Dimension analysée
`gps`	Géolocalisation (cohérence, précision)
`battery`	Batterie (état de l'appareil au moment de la prise)
`motion`	Mouvement (stabilité de prise de vue)
`device`	Intégrité de l'appareil (Play Integrity / attestation)
`image`	Photo (détection de photo d'une photo)
`duplicate`	Doublon (similarité avec des photos déjà connues)
`document`	Analyse documentaire (présent uniquement si au moins une analyse documentaire existe sur le dossier)

`ApiDocumentAnalysisDto` — analyse d'un document

Champ	Type	Description
`itemId`	Number	Item (document) concerné.
`expectedDocumentTypes`	String[]	Types de documents acceptés configurés sur l'étape.
`detectedDocumentType`	String \| null	Type de document détecté par l'IA.
`typeMatchScore`	Number \| null	Conformité du type (0–100).
`crossCheckResults`	Array \| null	Verdict par champ recoupé : `MATCH` \| `MISMATCH` \| `MISSING`. Les valeurs comparées ne sont jamais renvoyées.
`crossCheckScore`	Number \| null	Cohérence croisée (0–100) : recoupement document ↔ données saisies.
`suspicionScore`	Number \| null	Détection d'anomalies (0–100) : analyse forensique de falsification.
`suspicionLevel`	String \| null	Niveau de suspicion (`NONE`, `LOW`, `MEDIUM`, `HIGH`).
`evaluation`	Number \| null	Note brute de l'analyse.
`progressStatusLevel`	String \| null	`ANALYSIS_COMPLETED` quand l'analyse est terminée.
`trustScore`	Number \| null	Score documentaire agrégé (0–100), intégré au Trust Score global via le signal `document`.
`analysisDetails`	Array \| null	Détail des critères de contrôle : `code`, `label`, `status`, `evaluation`, `suspicionLevel`, `weight`. Un critère peut porter un tableau `subControls` (mêmes champs, plus `message` et `resultDetails`) détaillant ses sous-contrôles.

Réponses en cas d'erreur

Statut	Description
`403 Forbidden`	Le dossier n'appartient pas à votre entreprise, ou l'option d'analyse n'est pas active pour votre entreprise.
`404 Not Found`	Dossier introuvable.

Sécurité et Bonnes Pratiques

Assurez-vous que toutes les données nécessaires ont été collectées avant de fermer un dossier.
Seuls les champs fournis dans la requête de mise à jour seront modifiés. Les autres champs conserveront leurs valeurs actuelles.
Envisagez de sauvegarder les données importantes avant suppression.
Vérifiez toujours que le caseId correspond bien au dossier que vous souhaitez manipuler.
Les métadonnées doivent être des paires clé-valeur avec des valeurs de type chaîne de caractères.
Les interactions avec l'API Certificall doivent toujours être effectuées via une connexion sécurisée (HTTPS).
Stockez et gérez le token d'authentification de manière sécurisée.

En suivant ces instructions, vous pourrez gérer en toute sécurité vos dossiers via l'API Certificall.

Recherche de Dossiers​

Endpoint : GET /cases​

Description​

Authentification​

Requête HTTP​

Paramètres de la requête (Query Parameters)​

Filtres généraux​

Fenêtre temporelle (filtre sur createdAt)​

Pagination​

Réponses​

Cas pratique​

Récupérer les id des dossiers créés entre 6h et 11h aujourd'hui qui ne sont pas clôturés​

Création d'un Dossier​

Endpoint : POST /cases/create​

Description​

Authentification​

Requête HTTP​

Corps de la Requête (Payload)​

Exemples de Requêtes​

Réponses​

Permissions Requises​

Cas d'Utilisation​

Notes Importantes​

Création en Masse​

Endpoint : POST /cases/bulk-create​

Requête​

Permissions Requises​

Réponse​

Erreurs de requête​

Fermeture d'un Dossier​

Endpoint : GET /cases/close/:caseId​

Description​

Requête​

Permissions​

Endpoint : GET /cases/close/certilink/:magicLinkToken​

Description​

Requête​

Permissions​

Exemple cURL​

Réponses (communes aux deux endpoints)​

Cas d'usage​

Mise à Jour d'un Dossier​

Endpoint : PATCH /cases/update​

Description​

Requête​

Corps de la Requête (Payload)​

Réponses​

Permissions Requises​

Cas d'Utilisation​

Mise à Jour en Masse​

Endpoint : PATCH /cases/bulk-update​

Requête​

Permissions Requises​

Réponse​

Motifs d'échec fréquents​

Suppression d'un Dossier​

Endpoint : DELETE /cases/delete/:caseId​

Description​

Requête​

Réponses​

Permissions Requises​

Avertissement​

Cas d'Utilisation​

Suppression en Masse​

Endpoint : POST /cases/bulk-delete​

Requête​

Permissions Requises​

Réponse​

Erreurs de requête​

Analyse d'un Dossier​

Endpoint : GET /cases/:caseId/analysis​

Description​

Requête​

Permissions Requises​

Exemple​

Réponse en cas de succès​

Modèle de données​

ApiCaseAnalysisDto — analyse du dossier​

signals — clés possibles​

ApiDocumentAnalysisDto — analyse d'un document​

Recherche de Dossiers

Endpoint : `GET /cases`

Description

Authentification

Requête HTTP

Paramètres de la requête (Query Parameters)

Filtres généraux

Fenêtre temporelle (filtre sur `createdAt`)

Pagination

Réponses

Cas pratique

Récupérer les `id` des dossiers créés entre 6h et 11h aujourd'hui qui ne sont pas clôturés

Création d'un Dossier

Endpoint : `POST /cases/create`

Description

Authentification

Requête HTTP

Corps de la Requête (Payload)

Exemples de Requêtes

Réponses

Permissions Requises

Cas d'Utilisation

Notes Importantes

Création en Masse

Endpoint : `POST /cases/bulk-create`

Requête

Permissions Requises

Réponse

Erreurs de requête

Fermeture d'un Dossier

Endpoint : `GET /cases/close/:caseId`

Description

Requête

Permissions

Endpoint : `GET /cases/close/certilink/:magicLinkToken`

Description

Requête

Permissions

Exemple cURL

Réponses (communes aux deux endpoints)

Cas d'usage

Mise à Jour d'un Dossier

Endpoint : `PATCH /cases/update`

Description

Requête

Corps de la Requête (Payload)

Réponses

Permissions Requises

Cas d'Utilisation

Mise à Jour en Masse

Endpoint : `PATCH /cases/bulk-update`

Requête

Permissions Requises

Réponse

Motifs d'échec fréquents

Suppression d'un Dossier

Endpoint : `DELETE /cases/delete/:caseId`

Description

Requête

Réponses

Permissions Requises

Avertissement

Cas d'Utilisation

Suppression en Masse

Endpoint : `POST /cases/bulk-delete`

Requête

Permissions Requises

Réponse

Erreurs de requête

Analyse d'un Dossier

Endpoint : `GET /cases/:caseId/analysis`

Description

Requête

Permissions Requises

Exemple

Réponse en cas de succès

Modèle de données

`ApiCaseAnalysisDto` — analyse du dossier

`signals` — clés possibles

`ApiDocumentAnalysisDto` — analyse d'un document