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,
    "frameName": "Trame A",
    "companyName": "Entreprise XYZ",
    "reportToken": "TOKEN123",
    "url": "https://certificall.example.com/download/SHARETOKEN123"
  }
]

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.

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).
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 et métadonnées du dossier.
- 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): Métadonnées personnalisées (paires clé-valeur de type string).
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 UTC).

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 et magicLinkToken sont mutuellement exclusifs : vous devez utiliser l'un ou l'autre, mais pas les deux.
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.

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://api.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 et métadonnées du dossier.
- 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 système (paires clé-valeur).
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 :

{
  "id": 12345,
  "cfRef": "CAS-12345_CMP-1",
  "title": "Inspection mise à jour",
  "frameId": 10,
  "reportToken": "RAPPORT-2024-001",
  "updatedAt": "2024-01-15T10:30:00Z"
}

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

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

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​

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​

Suppression d'un Dossier​

Endpoint : DELETE /cases/delete/:caseId​

Description​

Requête​

Réponses​

Permissions Requises​

Avertissement​

Cas d'Utilisation​

Sécurité et Bonnes Pratiques​

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

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

Suppression d'un Dossier

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

Description

Requête

Réponses

Permissions Requises

Avertissement

Cas d'Utilisation

Sécurité et Bonnes Pratiques