Analyse documentaire par API — du dépôt au verdict

Ce guide décrit le parcours complet pour faire analyser un justificatif depuis votre système, sans application mobile ni intervention humaine :

Une fois — vous configurez dans l'admin Certificall une trame contenant une étape Upload document, et vous choisissez le régime du fichier : certifié et conservé (coffre-fort numérique) ou supprimé après analyse (minimisation RGPD).
À chaque pièce reçue — votre backend crée un dossier, y dépose le document, puis clôture le dossier. Trois appels.
Quelques instants plus tard — Certificall vous notifie sur votre webhook avec le score de confiance et le détail de l'analyse : détection de falsification, conformité du type de document, recoupement des données.

Le tout sans jamais exposer de valeur extraite du document : vous recevez des verdicts et des scores, pas des données personnelles.

Option requise

L'analyse documentaire est une option de votre contrat, activée par votre contact Certificall. Voir Analyse documentaire — administration.

Vue d'ensemble du parcours

   [ UNE FOIS, DANS L'ADMIN ]
   Trame + étape Upload document + Config +   →   frameId, stepId
   Webhooks configurés par Certificall


   [ À CHAQUE DOCUMENT ]

┌──────────────────────┐
│  Backend partenaire  │
└──────────┬───────────┘
           │
           │ (1) POST /cases/create            ──►  caseId   ◄── à stocker
           │ (2) POST /v2/.../items/:caseId/document
           │ (3) GET  /cases/close/:caseId     ──►  réponse immédiate + pdfUrl
           │
           ▼
┌──────────────────────────────────────────────┐
│           Backend Certificall                │
│                                              │
│  dépôt ──► analyse documentaire (async)      │
│  clôture ─► PDF scellé + horodatage          │
│              │                               │
│              ├──► webhook « dossier »        │  immédiat
│              │                               │
│              └──► webhook « analyse »        │  secondes → 15 min
│                   trustScore + détail        │
└──────────────────────────────────────────────┘

Deux moments distincts, donc deux webhooks : le contenu du dossier part à la clôture, le verdict part quand l'analyse est terminée. C'est le point à ne pas confondre.

Pré-requis

Pré-requis	Comment l'obtenir
Option analyse documentaire	Activée sur votre entreprise par votre contact Certificall. Sans elle, aucun résultat n'est produit et aucun webhook d'analyse n'est émis.
Compte API actif	Demandez à votre administrateur Certificall un utilisateur de type API. Le droit `p_api:case:create` suffit pour tout ce parcours.
Trame configurée	Une trame avec au moins une étape Upload document, dont l'analyse documentaire est activée. Voir l'étape 1 ci-dessous, et Trame et Étapes.
URL de webhook	Une URL HTTPS de votre côté, capable de recevoir un `POST` et d'authentifier l'appelant. Les adresses IP littérales sont refusées. Modes d'authentification acceptés : Webhook après validation d'un certificat.
Identifiants webhook	Le jeton que Certificall présentera à votre endpoint (`Authorization: Bearer …` ou en-tête `security-token`).

Étape 1 — Préparer la trame (dans l'admin, une seule fois)

Références : Trame et Étapes — Analyse documentaire — administration

Cette étape ne passe pas par l'API

L'API expose GET /frames en lecture seule : il n'existe pas d'endpoint de création de trame. La trame, ses étapes et la configuration d'analyse se font dans l'interface admin. C'est un travail de mise en place, pas une opération à répéter à chaque dossier.

1.1 — Ajouter une étape Upload document

Dans l'éditeur de trames, ajoutez une étape de type Upload document. Le rôle d'une trame et de ses étapes est décrit dans Trame et Étapes. C'est ce type d'étape qui ouvre l'endpoint de dépôt le plus simple (droit case:create, sans droit média supplémentaire).

L'analyse documentaire fonctionne aussi sur une étape Photo — pour un document photographié plutôt que déposé — mais le dépôt passe alors par POST /v2/certificall/api/items/:caseId, qui exige le droit p_api:item:create. Si votre parcours est un dépôt de fichier, restez sur Upload document.

1.2 — Activer l'analyse dans l'onglet « Config + »

Référence, captures d'écran à l'appui : Configurer une trame avec analyse documentaire

Sélectionnez l'étape, ouvrez Config +, puis :

activez « Activer l'analyse documentaire » ;
cochez les types de documents acceptés (facture, KBIS, avis d'imposition, pièce d'identité…). Une alerte est levée si le document détecté ne correspond à aucun type coché. Si le type attendu n'est pas dans la liste, cochez « Autre document » : le document bénéficie alors de l'analyse forensique générale, sans les contrôles de fond propres à un type ;
laissez « Activer le cross-check des données saisies » désactivé pour un premier parcours (voir Aller plus loin).

1.3 — Le choix structurant : certifier ou supprimer

Référence : Options complémentaires

Deux réglages, à deux endroits différents de l'éditeur, qui décident du sort du fichier :

Réglage	Où	Effet
« Horodater le document (horodatage + signature) »	sur l'étape, panneau de droite	Le fichier source est horodaté (eIDAS) et signé. Il est conservé et son intégrité reste vérifiable dans le temps : usage coffre-fort numérique. Activé par défaut.
« Supprimer le document après l'analyse (RGPD) »	onglet Config +	Le fichier source est purgé du stockage dès l'analyse terminée. Seul le résultat est conservé : usage minimisation des données.

Les deux ne se combinent pas

Cocher la suppression annule l'horodatage, même s'il est activé sur l'étape : on ne peut pas sceller un fichier qu'on s'apprête à détruire. L'admin affiche d'ailleurs un avertissement en ce sens. Choisissez selon votre exigence dominante — valeur probante d'un côté, non-rétention de l'autre.

1.4 — Faire configurer les webhooks

Références : Webhook de résultat d'analyse — Webhook après validation d'un certificat

Communiquez à votre contact Certificall l'URL et le jeton de vos deux webhooks. Le webhook de résultat d'analyse ne se configure pas depuis l'API : il est posé par Certificall dans les paramètres de votre entreprise.

Le webhook de réception du dossier, lui, est modifiable depuis votre backend :

curl -X POST https://admin.certificall.app/certificall/api/company-options/api-settings \
  -H "Authorization: Bearer <votre_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://votre-domaine.fr/webhooks/certificall/dossier",
    "authToken": "<le jeton que nous vous présenterons>",
    "authorizationHeader": "authorization"
  }'

Étape 2 — Authentification

Endpoint : POST /certificall/api/auth/token
Référence : Authentification Publique

curl -X POST https://admin.certificall.app/certificall/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{ "username": "votre_compte_api", "password": "votre_mot_de_passe" }'

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Ce token est à placer dans Authorization: Bearer <token> de tous les appels suivants.

Bonnes pratiques

Mettez le token en cache côté backend et rafraîchissez-le avant expiration. Ne l'exposez jamais au navigateur : tous les appels décrits ici partent de votre serveur.

Étape 3 — Récupérer le `frameId` et le `stepId`

Endpoint : GET /certificall/api/frames
Référence : Récupération de la Trame

curl https://admin.certificall.app/certificall/api/frames \
  -H "Authorization: Bearer <votre_token>"

[
  {
    "id": 42,
    "name": "Vérification de justificatif",
    "steps": [
      {
        "id": 305,
        "title": "Justificatif de domicile",
        "description": "PDF ou photo lisible",
        "stepAction": "DOCUMENT_UPLOAD",
        "isMandatory": true
      }
    ]
  }
]

C'est le champ stepAction qui identifie l'étape de dépôt : cherchez DOCUMENT_UPLOAD.

Une seule fois

frameId et stepId sont stables. Récupérez-les au démarrage de votre intégration, stockez-les de votre côté, et n'appelez plus cet endpoint à chaque document.

Étape 4 — Créer le dossier

Endpoint : POST /certificall/api/cases/create
Référence : Gestion des Dossiers

Seul frameId est obligatoire. Sans userId, userMail ni certilink, le dossier est rattaché à votre compte API : c'est le mode attendu pour un parcours entièrement serveur.

curl -X POST https://admin.certificall.app/certificall/api/cases/create \
  -H "Authorization: Bearer <votre_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "frameId": 42,
    "title": "Justificatif — dossier 2026-000871",
    "caseContext": {
      "metadata": {
        "dossierInterne": "2026-000871",
        "typeAttendu": "justificatif_domicile"
      }
    }
  }'

{
  "id": 12345,
  "cfRef": "CAS-12345_CMP-1",
  "frameId": 42,
  "title": "Justificatif — dossier 2026-000871",
  "createdAt": "2026-09-01T10:30:00Z",
  "closed": false
}

Stockez le caseId — c'est votre seule clé de rattachement

Le webhook de résultat d'analyse transporte caseId et cfRef, mais ni vos metadata ni votre reportToken. Sans une table de correspondance caseId → votre dossier écrite maintenant, vous ne saurez pas à quoi rattacher le verdict.

À propos du reportToken

Le reportToken sert à regrouper plusieurs dossiers sous un même rapport (plusieurs pièces d'un même client, plusieurs passages sur un même bien). Ce n'est pas un identifiant de dossier : en générer un par dossier lui fait perdre sa raison d'être. Pour transporter votre référence interne, utilisez caseContext.metadata. Voir Identifiant de rapport.

Étape 5 — Déposer le document

Endpoint : POST /v2/certificall/api/items/:caseId/document
Droit requis : p_api:case:create — le même que pour créer le dossier
Référence : Gestion des Items

Un seul appel crée l'item, transporte le fichier et déclenche l'analyse. Il n'y a pas d'item à créer au préalable.

curl -X POST https://admin.certificall.app/v2/certificall/api/items/12345/document \
  -H "Authorization: Bearer <votre_token>" \
  -F "file=@/chemin/vers/justificatif.pdf" \
  -F 'createItemDto={
    "companyId": 1,
    "stepId": 305,
    "data": "justificatif.pdf",
    "clientAppName": "Portail Souscription",
    "clientAppVersion": "4.2.0",
    "frontCreatedAt": "2026-09-01T10:31:12+02:00",
    "userDeviceManufacturer": "Serveur",
    "userDeviceModel": "API",
    "userDeviceName": "integration-souscription",
    "userDevicePlatform": "Server",
    "userDeviceOs": "Linux",
    "userDeviceOsVersion": "1.0"
  }'

{
  "companyId": 1,
  "caseId": 12345,
  "itemId": 98765,
  "documentUrl": "https://admin.certificall.app/certificall/documents/company-1/..."
}

Ce que ces champs deviennent sur le certificat

clientAppName, clientAppVersion et frontCreatedAt sont obligatoires en v2. Quand un fichier est capturé par votre application puis déposé via l'API, Certificall ne voit ni l'appareil ni le moment réel de la capture : le certificat porte donc un encart « Origine de la capture » qui nomme votre application et répartit les rôles. Un champ manquant renvoie un 400 qui le nomme.

Contraintes sur le fichier

Contrainte	Valeur
Formats analysés	PDF, JPEG, PNG
Taille maximale	~10 Mo
Vérification du type	Le type réel est contrôlé (signature binaire), pas l'extension

Réponses d'erreur

Code	Cause
`400`	Champ du contrat v2 manquant, `frontCreatedAt` mal formée, fichier trop volumineux, type non supporté, `createItemDto` malformé
`403`	L'étape ciblée n'est pas de type Upload document, ou le dossier n'appartient pas à votre entreprise
`404`	Aucune étape ne correspond à ce `stepId`

L'analyse ne répond pas ici

Cette réponse confirme le dépôt, pas l'analyse. L'analyse démarre en asynchrone dès la réception : son résultat arrive par webhook (étape 7).

Étape 6 — Clôturer le dossier

Endpoint : GET /certificall/api/cases/close/:caseId
Référence : Fermeture d'un Dossier

La clôture scelle le dossier, produit le PDF certifié et arme la remontée du résultat d'analyse. Sans elle, aucun webhook d'analyse n'est émis.

curl https://admin.certificall.app/certificall/api/cases/close/12345 \
  -H "Authorization: Bearer <votre_token>"

{
  "status": "Success",
  "message": "Case closed successfully",
  "caseId": 12345,
  "pdfUrl": "https://admin.certificall.app/certificall/share/..."
}

La clôture n'attend pas l'analyse

Cet appel répond immédiatement, dès que le PDF est scellé. L'analyse documentaire continue en arrière-plan. N'attendez rien ici : votre interface peut rendre la main à l'utilisateur tout de suite, le verdict arrivera par webhook.

Étape 7 — Recevoir le résultat

7.1 — Les deux webhooks, à ne pas confondre

	Webhook de réception du dossier	Webhook de résultat d'analyse
Déclenché	à la clôture, immédiatement	quand l'analyse est terminée
Contenu	items déposés, `documentUrl`, `caseUrl` (PDF), votre `context.metadata`	`caseId`, `cfRef`, `trustScore`, `analyzeStatus`, analyse détaillée
Configurable par vous	oui, `POST /company-options/api-settings`	non — posé par Certificall
Utile pour	archiver la pièce et le certificat	décider : validation automatique ou revue manuelle

Pour un parcours d'analyse documentaire, le second est celui qui porte la valeur. Le premier reste utile si vous archivez le PDF ou la pièce de votre côté : son contenu et ses modes d'authentification sont détaillés dans Webhook après validation d'un certificat.

7.2 — Payload du webhook de résultat d'analyse

Référence détaillée : Webhook de résultat d'analyse — conditions d'émission, authentification, garanties de livraison

{
  "caseId": 12345,
  "cfRef": "CAS-12345_CMP-1",
  "progress": "completed",
  "trustScore": 86,
  "analyzeStatus": "GOOD",
  "analysis": {
    "caseId": 12345,
    "trustScore": 86,
    "trustLevel": "GOOD",
    "itemsAnalyzed": 1,
    "signals": [
      { "key": "document", "score": 88, "trustLevel": "GOOD" }
    ],
    "documentAnalyses": [
      {
        "itemId": 98765,
        "expectedDocumentTypes": ["DOT-JUST_DOMICILE"],
        "detectedDocumentType": "DOT-JUST_DOMICILE",
        "typeMatchScore": 100,
        "crossCheckResults": null,
        "crossCheckScore": null,
        "suspicionScore": 96,
        "suspicionLevel": "NONE",
        "evaluation": 96,
        "progressStatusLevel": "ANALYSIS_COMPLETED",
        "trustScore": 97,
        "analysisDetails": [
          {
            "code": "FONT_CONSISTENCY",
            "label": "Cohérence des polices",
            "status": "VALID",
            "evaluation": 95,
            "suspicionLevel": "NONE",
            "weight": 2
          }
        ]
      }
    ]
  }
}

Deux champs pilotent votre décision :

progress — "completed" : analyse complète. "failed" : finalisée en mode dégradé, une analyse n'est pas revenue à temps. Les scores présents restent exploitables, mais ils sont partiels : ne validez pas automatiquement sur un failed.
analyzeStatus — GOOD (70-100), SUSPICIOUS (30-69), CRITICAL (0-29).

Le contenu de analysis est identique à celui renvoyé par GET /cases/:caseId/analysis, dont le modèle complet est détaillé dans API — Analyse documentaire.

7.3 — Traitement côté partenaire

// POST /webhooks/certificall/analyse (votre route)
app.post('/webhooks/certificall/analyse', verifySignature, async (req, res) => {
  const { caseId, progress, trustScore, analyzeStatus, analysis } = req.body;

  // 1) Retrouver votre dossier — via le caseId stocké à l'étape 4
  const dossier = await db.findByCaseId(caseId);
  if (!dossier) return res.status(200).end(); // jamais d'erreur sur un dossier inconnu

  // 2) Router selon le verdict
  const documentaire = analysis?.documentAnalyses?.[0];
  const decision =
    progress !== 'completed'      ? 'revue_manuelle' :
    analyzeStatus === 'GOOD'      ? 'valide' :
                                    'revue_manuelle';

  await db.update(dossier.id, {
    decision,
    trustScore,
    typeDetecte: documentaire?.detectedDocumentType ?? null,
    scoreFalsification: documentaire?.suspicionScore ?? null,
  });

  res.status(200).end();
});

Idempotence

Le webhook peut être ré-émis : une analyse arrivée tardivement peut corriger un verdict déjà livré. Traitez chaque réception comme une mise à jour du dossier caseId, jamais comme une insertion.

7.4 — Repli : interroger le résultat vous-même

Si vous ne pouvez pas exposer d'URL publique, le même contenu est disponible en lecture :

Endpoint : GET /certificall/api/cases/:caseId/analysis

curl https://admin.certificall.app/certificall/api/cases/12345/analysis \
  -H "Authorization: Bearer <votre_token>"

Tant que l'analyse n'est pas terminée, le bloc documentAnalyses peut être partiel : fiez-vous à progressStatusLevel — ANALYSIS_COMPLETED signale la fin.

Le polling a un coût

Vos appels API sont soumis à des quotas, et une analyse peut prendre plusieurs minutes : une boucle serrée les épuise pour rien. Espacez les interrogations (30 s puis 1 min, par exemple) et posez un plafond. Le webhook reste le mode recommandé.

Combien de temps ça prend

Étape	Ordre de grandeur
Dépôt du document	immédiat
Clôture du dossier	immédiat
Analyse documentaire	de quelques secondes à une dizaine de minutes selon le document
Émission du webhook d'analyse	dès que toutes les analyses du dossier sont revenues
Délai maximum avant finalisation dégradée	15 minutes — au-delà, le webhook part avec `progress: "failed"` et l'analyse partielle

Dimensionnez vos écrans en conséquence : un statut « vérification en cours » qui se met à jour à la réception du webhook, jamais une attente bloquante.

Étape 8 — Récupérer le PDF certifié

En mode certification (suppression après analyse désactivée), le document déposé est horodaté et signé, et le dossier produit un PDF certifié :

via le champ pdfUrl renvoyé par la clôture ;
via caseUrl dans le webhook de réception du dossier ;
via un Share Token si vous devez exposer le PDF à un tiers sans transmettre votre token — voir Certificat via un Share Token ;
via les rapports, si vous regroupez plusieurs dossiers sous un même reportToken.

En mode suppression après analyse, le fichier source n'existe plus et n'est donc pas certifié : seul le résultat d'analyse subsiste.

Aller plus loin — activer le cross-check

Le score documentaire agrège trois notes sur 100 : détection de falsification, conformité du type de document, et cohérence croisée — le recoupement entre ce que dit le document et ce que le dossier déclare par ailleurs.

Le parcours minimal décrit plus haut n'utilise que les deux premières : avec une seule étape dans la trame, il n'y a rien à recouper, et crossCheckScore reste à null.

Pour activer la troisième, ajoutez à la trame des étapes de saisie avant l'étape document (nom, adresse, montant…), puis dans Config + :

activez « Activer le cross-check des données saisies » ;
sélectionnez les étapes dont les valeurs doivent être recoupées avec le document.

Côté API, ces saisies se déposent avant le document :

curl -X POST https://admin.certificall.app/v2/certificall/api/items/create \
  -H "Authorization: Bearer <votre_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "caseId": 12345,
    "stepId": 303,
    "data": "12 rue des Lilas, 75011 Paris",
    "clientAppName": "Portail Souscription",
    "clientAppVersion": "4.2.0",
    "frontCreatedAt": "2026-09-01T10:30:45+02:00"
  }'

Le webhook renvoie alors un verdict par champ recoupé, sans jamais livrer les valeurs comparées :

"crossCheckResults": [
  { "fieldCode": "address", "fieldLabel": "Adresse", "match": "MATCH" },
  { "fieldCode": "lastName", "fieldLabel": "Nom", "match": "MISMATCH" }
],
"crossCheckScore": 50

Confidentialité : zéro donnée personnelle restituée

Ni le webhook ni l'API d'analyse ne renvoient les valeurs extraites du document (noms, montants, adresses, dates). Vous recevez uniquement des faits : verdicts MATCH / MISMATCH / MISSING, scores et critères de contrôle.

Combiné à l'option « Supprimer le document après l'analyse », cela permet une intégration où votre système ne stocke ni ne reçoit jamais la pièce : seulement le résultat.

Récapitulatif des endpoints

Étape	Méthode	Endpoint	Documentation
2. Authentification	`POST`	`/certificall/api/auth/token`	`/docs/api/token`
3. Lister les trames	`GET`	`/certificall/api/frames`	`/docs/api/create_certificate`
4. Créer le dossier	`POST`	`/certificall/api/cases/create`	`/docs/api/cases`
5. Déposer le document	`POST`	`/v2/certificall/api/items/:caseId/document`	`/docs/api/items`
5 bis. Déposer une saisie	`POST`	`/v2/certificall/api/items/create`	`/docs/api/items`
6. Clôturer	`GET`	`/certificall/api/cases/close/:caseId`	`/docs/api/cases`
7. Webhook d'analyse	`POST`	`<votre URL>`	`/docs/api/webhook_analyse`
7 bis. Lire le résultat	`GET`	`/certificall/api/cases/:caseId/analysis`	`/docs/api/analyse_documentaire`
1.4. Configurer le webhook dossier	`POST`	`/certificall/api/company-options/api-settings`	`/docs/api/webhook`

Swagger complet : admin.certificall.app/certificall/public/swagger

Check-list de mise en production

Pour aller plus loin

API — Analyse documentaire — modèle de données complet, triple scoring
Analyse documentaire — administration — configuration détaillée des trames
Gestion des Items — contrat de dépôt v2 et endpoints média
Webhook de résultat d'analyse — référence complète du webhook qui porte le verdict
Webhook après validation d'un certificat — webhook de réception du dossier
Trame et Étapes — ce qu'est une trame, quels types d'étapes existent
Identifiant de rapport — regrouper plusieurs dossiers sous un même rapport
Quotas de requêtes — limites applicables à vos appels
Intégration d'un bouton « Certifier » — le parcours équivalent avec capture par l'utilisateur final

Vue d'ensemble du parcours​

Pré-requis​

Étape 1 — Préparer la trame (dans l'admin, une seule fois)​

1.1 — Ajouter une étape Upload document​

1.2 — Activer l'analyse dans l'onglet « Config + »​

1.3 — Le choix structurant : certifier ou supprimer​

1.4 — Faire configurer les webhooks​

Étape 2 — Authentification​

Étape 3 — Récupérer le frameId et le stepId​

Étape 4 — Créer le dossier​

Étape 5 — Déposer le document​

Ce que ces champs deviennent sur le certificat​

Contraintes sur le fichier​

Réponses d'erreur​

Étape 6 — Clôturer le dossier​

Étape 7 — Recevoir le résultat​

7.1 — Les deux webhooks, à ne pas confondre​

7.2 — Payload du webhook de résultat d'analyse​

7.3 — Traitement côté partenaire​

7.4 — Repli : interroger le résultat vous-même​

Combien de temps ça prend​

Étape 8 — Récupérer le PDF certifié​

Aller plus loin — activer le cross-check​

Confidentialité : zéro donnée personnelle restituée​

Récapitulatif des endpoints​

Check-list de mise en production​

Pour aller plus loin​