Aller au contenu principal

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)​

  • 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.
  • hours (Number, optionnel): Nombre d'heures dans le passé pendant lesquelles les dossiers ont été créés maximum 240 heures, par défaut 12 heures.
  • withReportToken (Boolean, optionnel): Indique si le token du rapport doit être inclus dans les résultats.
  • closed (Boolean, optionnel): Filtre les dossiers selon leur statut (ouvert/fermé).
  • format (Enum, requis): Spécifie le format de la réponse (ZIP ou metadata), utilisant RESPONSE_FORMAT.
  • caseId (Number, optionnel): Identifiant du dossier recherché.

Attention : précisez hours si vous souhaitez recevoir les dossiers antérieurs aux 12 dernières heures

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 :

[
  {
    "cfRef": "REF123",
    "closingDate": "2023-01-01T00:00:00Z",
    "createdAt": "2022-12-01T00:00:00Z",
    "closed": true,
    "frameName": "Trame A",
    "companyName": "Entreprise XYZ",
    "reportToken": "TOKEN123",
    "url": "https://certificall.example.com/download/SHARETOKEN123"
  }
]

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.

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).

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"
    }
  }
}

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​

Endpoint : GET /cases/close/:caseId​

Description​

Ce point d'API permet aux utilisateurs de fermer un dossier en cours. Une fois fermé, le dossier est considéré comme finalisé et ne peut plus être modifié. Cette action est essentielle pour indiquer la fin du processus de collecte de données.

Requête​

  • URL : /cases/close/:caseId

  • Méthode HTTP : GET

  • Paramètres de chemin :

    • caseId : number - L'identifiant unique du dossier à fermer.

  • Headers requis :

    Authorization: Bearer <Votre_Token_JWT>

Réponses​

Réponse en cas de succès :

  • Statut : 200 OK
  • Description : Le dossier a été fermé avec succès.
  • Exemple de réponse : 
    {
      "status": "Success",
      "message": "Case closed successfully"
    }

Réponse en cas d'erreur :

  • Statut : 400 Bad Request

  • Description : La requête est invalide ou le dossier n'existe pas.

    {
      "statusCode": 400,
      "message": "Invalid case ID",
      "error": "Bad Request"
    }

  • 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 fermé.

Cas d'Utilisation​

Utilisez cet endpoint lorsque vous avez terminé de collecter toutes les données nécessaires pour un dossier et que vous souhaitez le finaliser. Une fois fermé, le dossier ne peut plus recevoir de nouveaux items.

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).

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

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.