Gestion des Rapports

Ce document détaille les endpoints permettant de récupérer des rapports et leurs métadonnées via l'API Certificall.

Le reportToken est un identifiant utilisé pour corréler plusieurs certificats à un contexte tiers (comme un système CRM ou une autre application) lorsqu'il est renseigné dans un deeplink avec le paramètre reportId.

Récupération des Métadonnées d'un Rapport

Endpoint : `GET /reports/:reportToken`

Description

Ce point d'API permet aux utilisateurs de récupérer les métadonnées détaillées d'un rapport spécifique en utilisant un jeton de rapport. Cet endpoint est public et ne nécessite pas d'authentification.

Le reportToken est transmis directement dans l'URL en tant que paramètre et sert de clé pour accéder à toutes les informations des certificats associés à un rapport.

Requête

URL : /reports/:reportToken
Méthode HTTP : GET
Paramètres de chemin :
- reportToken : string - Le jeton unique qui identifie le rapport.
Headers requis : Aucune authentification n'est nécessaire pour ce endpoint public.

Réponses

Réponse en cas de succès :

Statut : 200 OK
Description : Retourne un tableau d'objets JSON contenant les métadonnées détaillées du rapport.
Type : Array<CaseForApiResponseDto>

Exemple de réponse :

[
  {
    "cfRef": "CAS-7264_CMP-1",
    "companyName": "Entreprise XYZ",
    "createdAt": "2023-11-09T13:24:40+01:00",
    "closingDate": "2023-11-10T15:30:00+01:00",
    "reportId": "12345",
    "frame": "Inspection Visuelle",
    "closed": true,
    "caseUrl": "https://certificall.app/certificall/share/case/shareToken123",
    "items": [
      {
        "createdAt": "2023-11-09T13:25:00+01:00",
        "cfRef": "ITEM-001",
        "description": "Photo du matériel",
        "geolocLatitude": "48.8566",
        "geolocLongitude": "2.3522",
        "data": "État général satisfaisant",
        "imageUrl": "https://certificall.app/images/photo1.jpg",
        "stepAction": "Photography",
        "stepTitle": "Photo du matériel",
        "stepDescription": "Prendre une photo du matériel à inspecter",
        "imageHash": "abc123def456",
        "tspTokenHash": "xyz789uvw012"
      }
    ]
  }
]

Réponse en cas d'erreur :

Statut : 400 Bad Request
Description : La requête est invalide, par exemple si le reportToken est incorrect ou manquant.

{
  "statusCode": 400,
  "message": "Invalid report token",
  "error": "Bad Request"
}

Statut : 404 Not Found
Description : Aucun rapport trouvé pour ce reportToken.

{
  "statusCode": 404,
  "message": "Report not found",
  "error": "Not Found"
}

Modèle de Données

CaseForApiResponseDto :

cfRef : string - Référence unique du cas (exemple: "CAS-7264_CMP-1")
companyName : string - Nom de l'entreprise associée au certificat
createdAt : Date (ISO 8601) - Date de création du certificat
closingDate : Date (ISO 8601) - Date de fermeture du certificat
reportId : string - Identifiant unique du rapport (reportToken)
frame : string - Nom de la trame utilisée
closed : boolean - Statut indiquant si le certificat est fermé
caseUrl : string - URL publique de téléchargement du certificat PDF
items : Array<ItemDto> - Liste détaillée des éléments (items) du certificat

ItemDto :

createdAt : Date (ISO 8601) - Date de création de l'item
cfRef : string - Référence unique de l'item
description : string - Description de l'item
geolocLatitude : string - Latitude de géolocalisation
geolocLongitude : string - Longitude de géolocalisation
data : string - Données associées à l'item
imageUrl : string (optionnel) - URL de l'image si l'item est une photo
stepAction : string - Type d'action de l'étape (Photography, Text, etc.)
stepTitle : string - Titre de l'étape
stepDescription : string - Description de l'étape
imageHash : string (optionnel) - Hash de l'image pour vérification d'intégrité
tspTokenHash : string (optionnel) - Hash du token d'horodatage

Cas d'Utilisation

Utilisez cet endpoint pour :

Récupérer toutes les métadonnées détaillées des certificats d'un rapport
Consulter les informations sans authentification (endpoint public)
Obtenir les URLs de téléchargement des certificats individuels via le champ caseUrl
Accéder aux détails de chaque item (photos, textes, géolocalisation, etc.)
Vérifier l'intégrité des fichiers via les hash fournis

Récupération d'un Rapport Complet (ZIP ou URLs)

Endpoint : `POST /reports/report/:reportToken`

Description

Ce point d'API permet aux utilisateurs authentifiés de récupérer un rapport complet (ensemble de certificats) associé à un token de rapport spécifique. Selon le format demandé, vous pouvez obtenir soit un fichier ZIP contenant tous les PDFs des certificats, soit les URLs de téléchargement des certificats.

Requête

URL : /reports/report/:reportToken
Méthode HTTP : POST
Paramètres de chemin :
- reportToken : string - Le jeton unique qui identifie le rapport.

Headers requis :

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

Corps de la Requête (Payload)

format (Enum, optionnel): Format de la réponse (zip ou metadata).
- zip : Retourne un fichier ZIP contenant tous les PDFs des certificats
- metadata : Retourne les URLs de téléchargement des certificats
hours (Number, optionnel): Filtrer les certificats créés dans les X dernières heures.

Exemple de requête pour obtenir un ZIP :

{
  "format": "zip",
  "hours": 48
}

Exemple de requête pour obtenir les métadonnées :

{
  "format": "metadata"
}

Réponses

Réponse en cas de succès (format: zip) :

Code Statut: 200 OK
Type de Contenu: application/zip
Description: Retourne un fichier ZIP contenant tous les PDFs des certificats du rapport.

En-têtes de réponse :

Content-Type: application/zip
Content-Disposition: attachment; filename="reportToken.zip"

Le corps de la réponse contient le fichier ZIP binaire.

Réponse en cas de succès (format: metadata) :

Code Statut: 200 OK
Type de Contenu: application/json
Description: Retourne un objet contenant les URLs de téléchargement.

Exemple de réponse :

{
  "reportToken": "RAPPORT-2024-001",
  "caseUrls": [
    "https://certificall.app/certificall/share/case/shareToken1",
    "https://certificall.app/certificall/share/case/shareToken2",
    "https://certificall.app/certificall/share/case/shareToken3"
  ]
}

Réponse en cas d'erreur :

Code Statut: 400 Bad Request
Description: La requête est invalide (reportToken manquant ou format invalide).

{
  "statusCode": 400,
  "message": "Invalid report token or format",
  "error": "Bad Request"
}

Code Statut: 403 Forbidden
Description: Vous n'avez pas les permissions nécessaires pour accéder à ce rapport.
Code Statut: 404 Not Found
Description: Aucun certificat trouvé pour ce reportToken.

{
  "statusCode": 404,
  "message": "No certificates found for this report token",
  "error": "Not Found"
}

Permissions Requises

Vous devez être authentifié via un token JWT valide.
Les certificats doivent appartenir à votre entreprise.

Cas d'Utilisation

Utilisez cet endpoint pour :

Télécharger tous les certificats d'un rapport en une seule fois (format ZIP)
Obtenir les liens de téléchargement individuels pour chaque certificat (format metadata)
Récupérer les certificats créés dans une fenêtre temporelle spécifique (paramètre hours)
Intégrer les certificats dans un système tiers via les URLs de partage

Différences entre les deux Endpoints

Critère	GET /reports/:reportToken	POST /reports/report/:reportToken
Authentification	Non requise (public)	Requise (JWT)
Type de données	Métadonnées détaillées (JSON)	ZIP ou URLs simples
Informations items	Oui (détails complets)	Non
Téléchargement ZIP	Non	Oui (si format=zip)
Filtrage temporel	Non	Oui (paramètre hours)
Usage typique	Consultation des détails	Téléchargement des PDFs

Recommandation :

Utilisez GET /reports/:reportToken pour obtenir toutes les métadonnées détaillées des certificats (items, géolocalisation, hash, etc.)
Utilisez POST /reports/report/:reportToken pour télécharger les PDFs en masse (ZIP) ou obtenir les URLs de téléchargement

Sécurité et Bonnes Pratiques

L'endpoint GET est public mais ne donne accès qu'aux métadonnées, pas aux fichiers sensibles
Utilisez le format zip pour télécharger plusieurs certificats en une seule requête
Utilisez le format metadata pour obtenir les URLs et les télécharger individuellement ou les partager
Le paramètre hours permet de limiter les résultats aux certificats récents
Les URLs de partage retournées sont publiques et ne nécessitent pas d'authentification
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 récupérer en toute sécurité les rapports complets via l'API Certificall.

Récupération des Métadonnées d'un Rapport​

Endpoint : GET /reports/:reportToken​

Description​

Requête​

Réponses​

Modèle de Données​

Cas d'Utilisation​

Récupération d'un Rapport Complet (ZIP ou URLs)​

Endpoint : POST /reports/report/:reportToken​

Description​

Requête​

Corps de la Requête (Payload)​

Réponses​

Permissions Requises​

Cas d'Utilisation​

Différences entre les deux Endpoints​

Sécurité et Bonnes Pratiques​

Récupération des Métadonnées d'un Rapport

Endpoint : `GET /reports/:reportToken`

Description

Requête

Réponses

Modèle de Données

Cas d'Utilisation

Récupération d'un Rapport Complet (ZIP ou URLs)

Endpoint : `POST /reports/report/:reportToken`

Description

Requête

Corps de la Requête (Payload)

Réponses

Permissions Requises

Cas d'Utilisation

Différences entre les deux Endpoints

Sécurité et Bonnes Pratiques