API — Analyse documentaire

Cette page décrit l'utilisation de l'analyse documentaire via l'API Certificall : envoi d'un document à analyser, puis récupération du résultat (scores, verdicts et niveau de confiance).

Option requise

L'analyse documentaire est une option de votre contrat, activée par votre contact Certificall. La configuration des trames (types de documents acceptés, cross-check, suppression RGPD) est décrite dans la page Analyse documentaire — administration.

Vue d'ensemble du flux

#	Étape	Endpoint
1	S'authentifier	`POST /auth/token` — voir Authentification Publique
2	Récupérer la trame et le `stepId` de l'étape document	`GET /frames` — voir Création de Certificat
3	Créer un dossier	`POST /cases/create` — voir Gestion des Dossiers
4	Uploader le document	`POST /items/:caseId`
5	Récupérer le résultat de l'analyse	`GET /cases/:caseId/analysis`

Toutes les requêtes (sauf l'authentification) requièrent l'en-tête :

Authorization: Bearer <Votre_Token_JWT>

1. Uploader le document à analyser

Endpoint : `POST /items/:caseId`

Description

Crée un item sur une étape de type Upload document et déclenche l'analyse documentaire si l'étape est configurée pour. L'analyse s'exécute en asynchrone : son résultat n'est pas dans la réponse de cet endpoint.

Requête

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

Headers requis :

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

Corps (multipart form-data) :
- file : le document à analyser ;
- createItemDto : objet JSON stringifié (stepId, data, informations device…) — détail complet des champs dans Gestion des Items.

Contraintes sur le fichier

Contrainte	Valeur
Formats acceptés	PDF, JPEG, PNG
Taille maximale	~10 Mo
Vérification du type	Le type réel du fichier est vérifié (signature binaire), pas seulement son extension.

Exemple de requête

curl -X POST "https://admin.certificall.app/certificall/api/items/12345" \
  -H "Authorization: Bearer votre_token_jwt" \
  -F "file=@/chemin/vers/document.pdf" \
  -F 'createItemDto={
    "companyId": 1,
    "stepId": 101,
    "data": "document.pdf",
    "userDeviceManufacturer": "Serveur",
    "userDeviceModel": "API",
    "userDeviceName": "integration-api",
    "userDevicePlatform": "Server",
    "userDeviceOs": "Linux",
    "userDeviceOsVersion": "1.0"
  }'

Réponses

200 OK : item créé. Pour une étape configurée, l'analyse documentaire démarre en asynchrone.
400 Bad Request : fichier trop volumineux, type de fichier non supporté ou étape introuvable — le message précise la cause.
403 Forbidden : le dossier n'appartient pas à votre entreprise.

2. Récupérer le résultat de l'analyse

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

Description

Renvoie l'analyse de confiance complète du dossier : le score de confiance global (Trust Score), les signaux par dimension (géolocalisation, device, photo, document…), et le détail de chaque analyse documentaire.

Analyse asynchrone

L'analyse documentaire prend généralement quelques dizaines de secondes après l'upload. Tant qu'elle n'est pas terminée, le bloc documentAnalyses peut être partiel — fiez-vous au champ progressStatusLevel (ANALYSIS_COMPLETED = terminé) avant d'exploiter les scores.

Requête

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

Réponse en cas de succès

Code Statut : 200 OK
Type : ApiCaseAnalysisDto

{
  "caseId": 798,
  "trustScore": 86,
  "trustLevel": "GOOD",
  "itemsAnalyzed": 5,
  "signals": [
    { "key": "gps", "score": 95, "trustLevel": "GOOD" },
    { "key": "device", "score": 90, "trustLevel": "GOOD" },
    { "key": "document", "score": 88, "trustLevel": "GOOD" }
  ],
  "documentAnalyses": [
    {
      "itemId": 12345,
      "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 du dossier (0-100).
`trustLevel`	String	`GOOD` \| `SUSPICIOUS` \| `CRITICAL`.
`signals`	Array	Score par dimension : `gps`, `battery`, `motion`, `device`, `image`, `duplicate`, `document`. Le signal `document` n'apparaît que si une analyse documentaire existe sur le dossier.
`itemsAnalyzed`	Number	Nombre d'items analysés.
`documentAnalyses`	Array	Détail de chaque analyse documentaire (voir ci-dessous).

`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é.
`typeMatchScore`	Number \| null	Conformité du type (0-100) : le document correspond-il au type attendu.
`crossCheckResults`	Array \| null	Verdict par champ recoupé : `MATCH` \| `MISMATCH` \| `MISSING`. Les valeurs comparées ne sont jamais renvoyées (zéro donnée personnelle).
`crossCheckScore`	Number \| null	Cohérence croisée (0-100) : recoupement document ↔ données saisies.
`suspicionScore`	Number \| null	Analyse d'anomalies (0-100) : détection forensique de falsification.
`suspicionLevel`	String \| null	Niveau de suspicion (`NONE`, `LOW`, `MEDIUM`, `HIGH`…).
`evaluation`	Number \| null	Note brute de l'évaluation du document.
`progressStatusLevel`	String \| null	Avancement de l'analyse (`ANALYSIS_COMPLETED` = terminé).
`trustScore`	Number \| null	Score documentaire agrégé (0-100), intégré au Trust Score global.
`analysisDetails`	Array \| null	Détail des critères de contrôle : `code`, `label`, `status`, `evaluation` (0-100), `suspicionLevel`, `weight`.

Correspondance avec le triple scoring

Note	Champ API
Analyse d'anomalies	`suspicionScore`
Conformité du type de document	`typeMatchScore`
Cohérence croisée (cross-check)	`crossCheckScore`
Score documentaire global	`trustScore` (intégré au `trustScore` du dossier via le signal `document`)

Réponses en cas d'échec

403 Forbidden : le dossier n'appartient pas à votre entreprise.
404 Not Found : dossier introuvable.

Confidentialité : zéro donnée personnelle

L'API d'analyse ne renvoie jamais les valeurs extraites du document (noms, montants, dates…). Seuls des faits sont exposés : verdicts (MATCH/MISMATCH/MISSING), scores et critères de contrôle. Combinée à l'option « Supprimer le document après l'analyse », cette approche permet une intégration entièrement compatible avec votre politique RGPD : vous ne conservez que le résultat.

Cas d'utilisation

Vérification de pièces en marche automatique : votre back-office uploade les justificatifs reçus, attend ANALYSIS_COMPLETED, et route le dossier (validation auto si trustLevel = GOOD, revue manuelle sinon).
Coffre-fort numérique : chaque document uploadé est certifié (horodatage eIDAS, signature) — vous récupérez les certificats via les rapports.
Collecte minimisée (RGPD) : avec la suppression après analyse, votre SI ne stocke ni ne reçoit aucune pièce — uniquement les scores de cette API.

Vue d'ensemble du flux​

1. Uploader le document à analyser​

Endpoint : POST /items/:caseId​

Description​

Requête​

Contraintes sur le fichier​

Exemple de requête​

Réponses​

2. Récupérer le résultat de l'analyse​

Endpoint : GET /cases/:caseId/analysis​

Description​

Requête​

Réponse en cas de succès​

Modèle de données​

ApiCaseAnalysisDto — analyse du dossier​

ApiDocumentAnalysisDto — analyse d'un document​

Correspondance avec le triple scoring​

Réponses en cas d'échec​

Confidentialité : zéro donnée personnelle​

Cas d'utilisation​

Vue d'ensemble du flux

1. Uploader le document à analyser

Endpoint : `POST /items/:caseId`

Description

Requête

Contraintes sur le fichier

Exemple de requête

Réponses

2. Récupérer le résultat de l'analyse

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

Description

Requête

Réponse en cas de succès

Modèle de données

`ApiCaseAnalysisDto` — analyse du dossier

`ApiDocumentAnalysisDto` — analyse d'un document

Correspondance avec le triple scoring

Réponses en cas d'échec

Confidentialité : zéro donnée personnelle

Cas d'utilisation