API de vérification documentaire : guide d'intégration

Une API de vérification documentaire est une interface programmatique qui permet aux développeurs de soumettre des pièces d'identité, factures, attestations ou justificatifs de domicile et de recevoir des résultats de vérification structurés — contrôles d'authenticité, extraction de données, signaux de fraude — sans construire les modèles d'IA sous-jacents. L'API CheckFile traite un document en 4,2 secondes en moyenne, atteint 98,7 % de précision OCR sur 24 langues et gère plus de 3 200 types de documents dans 32 juridictions.

Le règlement européen sur l'IA (Règlement (UE) 2024/1689, art. 6 et annexe III) classe les systèmes d'IA utilisés pour la vérification de documents d'identité dans les services financiers comme à haut risque, imposant aux fournisseurs de maintenir une documentation technique, un système de gestion des risques et des capacités de supervision humaine. Toute API que vous intégrez doit satisfaire ces obligations — sinon vous héritez de la lacune de conformité.

Ce guide couvre l'authentification, les endpoints principaux, la configuration des webhooks, la gestion des erreurs, les SDK disponibles et les tarifs. Il s'adresse aux développeurs back-end, équipes DevOps et responsables techniques évaluant des API de vérification documentaire pour une intégration en production.

Cet article est fourni à titre informatif uniquement et ne constitue pas un conseil juridique, financier ou réglementaire.

Authentification et sécurité

L'API CheckFile utilise OAuth 2.0 client credentials pour l'authentification machine-à-machine, conformément au RFC 6749, Section 4.4. Vous échangez votre client_id et client_secret contre un jeton bearer à durée limitée (expiration 60 minutes), puis incluez ce jeton dans l'en-tête Authorization de chaque requête.

Tout le trafic API est chiffré en TLS 1.3. Les documents sont chiffrés au repos avec AES-256, et les données personnelles sont automatiquement expurgées des logs, conformément à l'article 32 du RGPD relatif aux mesures techniques appropriées (RGPD, art. 32).

 # Obtenir un jeton d'accès
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=VOTRE_ID&client_secret=VOTRE_SECRET"

 # Réponse
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Fonctionnalités de sécurité clés :

• Liste blanche d'IP — restreindre l'accès API à des IP serveur connues
• Limitation de débit — configurable par plan (voir section tarifs)
• Signatures webhook — vérification HMAC-SHA256 sur chaque callback
• Journal d'audit — chaque appel API est enregistré avec horodatage, identifiant client, type de document et résultat

Scopes et permissions

Endpoints principaux

L'API suit les conventions RESTful avec des payloads JSON. URL de base : https://api.checkfile.ai/v1.

Soumission de document

POST /v1/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # Champs :
 # file (requis) — image ou PDF du document (max 20 Mo)
 # document_type (optionnel) — "passport", "id_card", "invoice", "proof_of_address"
 # country (optionnel) — code ISO 3166-1 alpha-2
 # webhook_url (optionnel) — URL de callback pour résultats asynchrones
 # reference_id (optionnel) — votre référence interne pour corrélation

Réponse (HTTP 202 Accepted) :

{
  "document_id": "doc_8f3a2b1c",
  "status": "processing",
  "estimated_completion_seconds": 4,
  "created_at": "2026-03-19T10:15:00Z"
}

Lorsque document_type est omis, l'API utilise son moteur de classification IA — qui atteint 96,1 % de précision sur notre benchmark de 3 200+ types de documents — pour détecter automatiquement le type.

Récupération des résultats

GET /v1/documents/{document_id}
Authorization: Bearer {token}

Réponse (HTTP 200) :

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "carte_identite",
  "country": "FR",
  "verification": {
    "authentic": true,
    "confidence": 0.97,
    "fraud_signals": [],
    "checks": {
      "mrz_valid": true,
      "photo_tamper": false,
      "expiry_valid": true,
      "data_consistency": true
    }
  },
  "extracted_data": {
    "full_name": "Marie Dupont",
    "date_of_birth": "1990-05-12",
    "document_number": "AB1234567",
    "expiry_date": "2031-05-11",
    "nationality": "FRA"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

L'objet extracted_data atteint 94,3 % de précision d'extraction sur notre benchmark interne, couvrant les champs structurés de tous les types de documents supportés.

Vérification par lot

Pour les intégrations à haut volume, l'endpoint batch accepte jusqu'à 50 documents par requête :

POST /v1/documents/verify/batch
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # files[] — tableau de fichiers documents
 # options — objet JSON avec paramètres partagés

Les requêtes batch retournent un batch_id et livrent les résultats par webhook au fur et à mesure.

Configuration des webhooks

Les architectures événementielles évitent la surcharge du polling. Enregistrez un endpoint webhook pour recevoir des notifications en temps réel quand les vérifications sont terminées.

POST /v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://votre-app.com/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_votre_cle_secrete"
}

Chaque livraison webhook inclut un en-tête X-CheckFile-Signature contenant un hash HMAC-SHA256 du payload. Vérifiez-le avant traitement :

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Politique de retry webhook : 3 tentatives avec backoff exponentiel (5s, 30s, 300s). Après 3 échecs, le webhook est désactivé et votre équipe reçoit une alerte email.

SDK et options d'intégration

L'API REST fonctionne depuis n'importe quel langage, mais les SDK officiels réduisent le temps d'intégration de plusieurs jours à quelques heures.

SDK disponibles

Exemple d'intégration Python

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="VOTRE_CLIENT_ID",
    client_secret="VOTRE_CLIENT_SECRET"
)

 # Vérification synchrone
result = client.documents.verify(
    file=open("carte_identite.pdf", "rb"),
    document_type="id_card",
    country="FR"
)

print(f"Authentique : {result.verification.authentic}")
print(f"Nom : {result.extracted_data.full_name}")
print(f"Temps de traitement : {result.processing_time_ms}ms")

Exemple d'intégration Node.js

import { CheckFileClient } from '@checkfile/sdk';
import { readFileSync } from 'fs';

const client = new CheckFileClient({
  clientId: process.env.CHECKFILE_CLIENT_ID,
  clientSecret: process.env.CHECKFILE_CLIENT_SECRET,
});

const result = await client.documents.verify({
  file: readFileSync('carte_identite.pdf'),
  documentType: 'id_card',
  country: 'FR',
});

console.log(`Authentique : ${result.verification.authentic}`);
console.log(`Confiance : ${result.verification.confidence}`);

Les SDK gèrent le rafraîchissement des tokens, les retries avec backoff exponentiel et la vérification des signatures webhook automatiquement. Notre analyse montre que les intégrations via SDK réduisent le délai médian de mise en production de 8 jours (REST brut) à 2 jours.

Gestion des erreurs et limites de débit

L'API utilise les codes HTTP standard avec des corps d'erreur structurés :

{
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "Le fichier envoyé n'a pas pu être analysé. Vérifiez que le DPI >= 300.",
    "details": { "min_dpi": 300, "detected_dpi": 72 },
    "request_id": "req_9f2c4d1e"
  }
}

Codes d'erreur courants

Limites de débit par plan

Les en-têtes de limite de débit (X-RateLimit-Remaining, X-RateLimit-Reset) sont inclus dans chaque réponse. Construisez votre logique de retry autour de ces en-têtes plutôt que de coder des délais en dur.

Conformité et traitement des données

La vérification documentaire touche des données personnelles dans de multiples juridictions. L'API est conçue avec la conformité comme exigence de premier ordre.

Depuis mars 2026, le RGPD (Règlement (UE) 2016/679, art. 28) impose aux responsables de traitement de ne recourir qu'à des sous-traitants présentant des garanties suffisantes de mesures techniques et organisationnelles appropriées. CheckFile agit en tant que sous-traitant, avec un accord de traitement des données (DPA) inclus dans tous les plans Business et Enterprise.

Conformément à la recommandation de la CNIL sur les sous-traitants de données, l'API fournit :

• Rétention : les documents sont supprimés après traitement sauf demande explicite de stockage (configurable de 0 à 365 jours)
• Résidence des données : traitement en UE par défaut ; régions US et APAC disponibles sur les plans Enterprise
• Piste d'audit : chaque appel API génère un enregistrement immuable avec hash du document, horodatage, résultat et identifiant client
• Certification SOC 2 Type II couvrant l'infrastructure API
• Conformité PCI DSS pour le traitement des documents financiers

Pour les intégrations soumises aux orientations de l'ACPR sur l'externalisation des prestations essentielles, CheckFile fournit la documentation d'assurance tiers requise, les résultats de tests de continuité d'activité et les conditions de stratégie de sortie.

Grille tarifaire

CheckFile utilise un modèle de tarification par document avec dégressivité par volume. Tous les plans incluent l'accès complet à l'API, les webhooks et les journaux d'audit.

Consultez la page tarifs pour les détails sur les paliers de volume, les remises annuelles et les conditions SLA Enterprise.

Notre analyse de plateforme montre que les organisations passant de la vérification manuelle de documents à la vérification par API réduisent le coût par dossier de 67 % et le temps de traitement de 83 %. Le délai de retour sur investissement moyen pour les clients Business est inférieur à 3 mois pour un volume de 500+ documents par mois.

Patterns d'architecture d'intégration

Pattern 1 : synchrone (simple)

Pour les intégrations à faible volume (< 60 req/min), soumettez et interrogez :

Client → POST /v1/documents/verify → 202 Accepted
Client → GET /v1/documents/{id} (polling toutes les 2s) → 200 avec résultats

Adapté aux parcours d'onboarding où l'utilisateur attend la vérification.

Pattern 2 : asynchrone avec webhooks (recommandé)

Pour les charges de travail en production, soumettez et recevez les résultats par webhook :

Client → POST /v1/documents/verify (avec webhook_url) → 202 Accepted
CheckFile → POST webhook_url (payload signé) → Votre handler traite le résultat

Découple la soumission du traitement. Monte en charge linéairement avec le volume.

Pattern 3 : pipeline par lot

Pour le traitement back-office (revues KYC nocturnes, contrôles de conformité en masse) :

Client → POST /v1/documents/verify/batch (jusqu'à 50 fichiers) → batch_id
CheckFile → POST webhook_url par document au fil des traitements
CheckFile → POST webhook_url avec résumé batch.completed

Notre plateforme traite plus de 180 000 documents par mois en utilisant ces patterns. Le pattern asynchrone avec webhooks couvre 94 % des intégrations en production.

Démarrage rapide

L'intégration suit quatre étapes :

1. Créez un compte sur checkfile.ai et générez vos identifiants API depuis le tableau de bord
2. Testez en sandbox — l'environnement sandbox reproduit la production avec des documents synthétiques (sans facturation)
3. Intégrez en utilisant le SDK ou des appels REST directs, en commençant par le pattern synchrone
4. Passez en production — basculez vers les identifiants de production et configurez les webhooks

La documentation API inclut un playground interactif pour tester les endpoints, et la page tarifs détaille les options de plan selon votre volume prévu.

Pour les équipes construisant des workflows automatisés de vérification documentaire, l'API s'intègre directement aux patterns décrits dans notre guide de configuration. Si vous évaluez des solutions de vérification plus largement, notre guide d'automatisation de la vérification couvre l'ensemble du paysage des approches de vérification documentaire.

Questions fréquemment posées

Quels types de documents l'API prend-elle en charge ?

L'API CheckFile prend en charge plus de 3 200 types de documents dans 32 juridictions : passeports, cartes nationales d'identité, permis de conduire, factures, relevés bancaires, justificatifs de domicile, avis d'imposition, bulletins de salaire et documents d'enregistrement d'entreprise. Le moteur de classification IA identifie automatiquement le type de document avec 96,1 % de précision lorsque le paramètre document_type est omis.

Combien de temps dure la vérification ?

Le temps de traitement moyen est de 4,2 secondes par document. La latence P95 est inférieure à 12 secondes pour les types de documents standards. Les soumissions par lot traitent les documents en parallèle : un lot de 50 documents se termine généralement en 30 à 60 secondes selon la complexité des documents.

L'API est-elle conforme au RGPD ?

Oui. CheckFile agit en tant que sous-traitant au sens de l'article 28 du RGPD avec DPA signé, infrastructure de traitement hébergée en UE, rétention des données configurable (0 à 365 jours) et expurgation automatique des données personnelles des logs. Les certifications SOC 2 Type II et ISO 27001 couvrent l'infrastructure API.

Puis-je tester l'API avant de m'engager sur un plan payant ?

Le plan Starter inclut 100 vérifications gratuites par mois, et l'environnement sandbox permet des tests illimités avec des documents synthétiques sans frais. Aucune carte bancaire n'est requise pour commencer.

Que se passe-t-il si l'API ne parvient pas à vérifier un document ?

Les documents qui tombent en dessous du seuil de confiance sont signalés avec le statut review_required et dirigés vers votre file de revue humaine via webhook. La réponse inclut le résultat partiel avec le score de confiance, les données extraites et les signaux de fraude spécifiques qui ont déclenché le signalement. Cela garantit qu'aucun document ne passe entre les mailles du filet.