API de validation documentaire : guide technique d'intégration pour développeurs

Ce guide couvre tout ce dont vous avez besoin pour intégrer la validation documentaire automatisée dans votre application -- de l'authentification à la gestion des webhooks. Que vous construisiez un parcours d'onboarding client, un pipeline de conformité ou un outil d'automatisation back-office, l'API CheckFile donne un accès programmatique au même moteur de validation IA que celui utilisé dans la plateforme. Vous trouverez ici les choix d'architecture, les références d'endpoints, des exemples de code en Python et Node.js, les payloads webhook, les stratégies de gestion d'erreurs et les patterns d'intégration qui passent à l'échelle du prototype à la production.

Architecture générale

L'API suit un modèle asynchrone REST avec upload via POST, file d'attente de traitement IA (2 à 15 secondes par document), et livraison des résultats par polling GET ou webhook callback. L'architecture asynchrone découplée permet de traiter jusqu'à 500 requêtes par minute (plan Business) sans bloquer l'application cliente.

                                    +-------------------+
                                    |  API Resultats    |
                                    |  GET /files/{id}  |
                                    +--------^----------+
                                             |
Application cliente                          | Poll ou fetch
    |                                        |
    |  POST /v1/files                +-------+--------+
    +------------------------------->| API Upload     |
    |                                +-------+--------+
    |                                        |
    |                                        v
    |                               +--------+--------+
    |                               | File de         |
    |                               | traitement (IA) |
    |                               +--------+--------+
    |                                        |
    |         Callback webhook               |
    |<---------------------------------------+
    |         POST votre-endpoint

Trois décisions de conception structurent cette architecture :

1. Asynchrone par défaut. La validation documentaire implique de l'OCR, de la détection de fraude, de la vérification croisée et de l'évaluation de règles. Ces opérations prennent 2 à 15 secondes selon la complexité du document. L'API accepte les uploads immédiatement et les traite en arrière-plan.

2. Double mode de livraison. Vous pouvez interroger l'endpoint de statut (polling) ou enregistrer un webhook. Le polling convient aux intégrations simples ; les webhooks sont l'approche recommandée pour les systèmes de production traitant plus de quelques documents par minute.

3. Uploads idempotents. Chaque upload retourne un file_id unique. Re-uploader le même document avec la même clé d'idempotence retourne le résultat existant au lieu de relancer le traitement, économisant temps et crédits API.

Authentification et sécurité

L'API supporte deux méthodes d'authentification : clé API dans le header X-API-Key pour les intégrations serveur-à-serveur, et OAuth 2.0 avec flow authorization code pour les applications multi-tenant. OWASP API Security Top 10 2023 classe l'authentification cassée (API2:2023 Broken Authentication) au rang 2 des risques critiques (OWASP API Top 10). Les clés API ne doivent jamais être utilisées pour l'authentification utilisateur, uniquement pour l'authentification client API.

Authentification par clé API

Pour les intégrations serveur-à-serveur, transmettez votre clé API dans le header X-API-Key :

curl -H "X-API-Key: ck_live_abc123..." \
     https://api.checkfile.ai/v1/files

Les clés API sont scopées à votre organisation. Vous pouvez générer plusieurs clés depuis le dashboard -- une par environnement (développement, staging, production) est la pratique recommandée. Les clés préfixées ck_test_ ciblent l'environnement sandbox ; les clés préfixées ck_live_ ciblent la production.

OAuth 2.0 pour un accès scopé utilisateur

Si votre application agit au nom d'utilisateurs finaux (par exemple un SaaS multi-tenant), utilisez OAuth 2.0 avec le flow authorization code. Cela fournit des traces d'audit au niveau utilisateur et un scope de permissions granulaire.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://votreapp.com/callback

Les access tokens expirent après 1 heure. Utilisez le refresh token pour obtenir de nouveaux access tokens sans ré-authentification.

Limites de débit

Les limites de débit sont appliquées par clé API, mesurées en requêtes par minute :

Lorsque vous dépassez la limite, l'API retourne 429 Too Many Requests avec un header Retry-After indiquant le nombre de secondes à attendre. Consultez nos tarifs pour le détail des plans.

Sécurité du transport

Tout le trafic est chiffré en TLS 1.3 (refus de TLS 1.2), les documents sont chiffrés au repos en AES-256 et automatiquement purgés selon la période de rétention (ISO/IEC 27001 définit les exigences des systèmes de management de la sécurité de l'information, avec principes de confidentialité, intégrité et disponibilité). Le certificate pinning est disponible pour les clients Enterprise. En savoir plus sur nos pratiques de sécurité.

Endpoints principaux

L'API est organisée autour de six endpoints principaux :

Tous les endpoints acceptent et retournent du JSON (sauf les endpoints d'upload de fichiers, qui acceptent du multipart/form-data). L'URL de base est https://api.checkfile.ai. Le versioning est basé sur le path ; la version stable actuelle est v1.

Upload et validation -- étape par étape

Le workflow le plus courant est : uploader les documents, attendre le traitement, récupérer les résultats. Voici le flux complet en Python et Node.js.

Python (requests)

import requests
import time

API_KEY = "ck_live_abc123..."
BASE_URL = "https://api.checkfile.ai/v1"
HEADERS = {"X-API-Key": API_KEY}

# Étape 1 : Uploader un lot de documents en tant que dossier
response = requests.post(
    f"{BASE_URL}/files/batch",
    headers=HEADERS,
    files=[
        ("files", ("contrat.pdf", open("contrat.pdf", "rb"), "application/pdf")),
        ("files", ("accord.pdf", open("accord.pdf", "rb"), "application/pdf")),
        ("files", ("kbis.pdf", open("kbis.pdf", "rb"), "application/pdf")),
    ],
    data={"rule_set": "equipment-leasing"}
)
response.raise_for_status()
file_id = response.json()["id"]
print(f"Dossier uploadé : {file_id}")

# Étape 2 : Poll du statut
while True:
    status_resp = requests.get(
        f"{BASE_URL}/files/{file_id}/status",
        headers=HEADERS
    )
    status = status_resp.json()["status"]
    if status in ("completed", "failed"):
        break
    time.sleep(2)  # Poll toutes les 2 secondes

# Étape 3 : Récupérer les résultats
results = requests.get(
    f"{BASE_URL}/files/{file_id}/results",
    headers=HEADERS
).json()

for doc in results["documents"]:
    print(f"{doc['filename']}: {doc['verdict']} (confiance: {doc['confidence']})")
    if doc["alerts"]:
        for alert in doc["alerts"]:
            print(f"  - {alert['severity']}: {alert['message']}")

Node.js (fetch + FormData)

import fs from 'node:fs';

const API_KEY = process.env.CHECKFILE_API_KEY;
const BASE_URL = 'https://api.checkfile.ai/v1';

// Étape 1 : Uploader un lot de documents
const form = new FormData();
form.append('files', new Blob([fs.readFileSync('contrat.pdf')]), 'contrat.pdf');
form.append('files', new Blob([fs.readFileSync('accord.pdf')]), 'accord.pdf');
form.append('files', new Blob([fs.readFileSync('kbis.pdf')]), 'kbis.pdf');
form.append('rule_set', 'equipment-leasing');

const uploadRes = await fetch(`${BASE_URL}/files/batch`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: form,
});
const { id: fileId } = await uploadRes.json();
console.log(`Dossier uploadé : ${fileId}`);

// Étape 2 : Poll du statut
let status = 'processing';
while (status !== 'completed' && status !== 'failed') {
  await new Promise((r) => setTimeout(r, 2000));
  const statusRes = await fetch(`${BASE_URL}/files/${fileId}/status`, {
    headers: { 'X-API-Key': API_KEY },
  });
  ({ status } = await statusRes.json());
}

// Étape 3 : Récupérer les résultats
const results = await fetch(`${BASE_URL}/files/${fileId}/results`, {
  headers: { 'X-API-Key': API_KEY },
}).then((r) => r.json());

for (const doc of results.documents) {
  console.log(`${doc.filename}: ${doc.verdict} (confiance: ${doc.confidence})`);
  for (const alert of doc.alerts) {
    console.log(`  - ${alert.severity}: ${alert.message}`);
  }
}

Les deux exemples suivent le même pattern en trois étapes : upload, poll, récupération. Pour les systèmes de production, remplacez la boucle de polling par un listener webhook (couvert dans la section suivante).

Payloads webhook

Les webhooks éliminent le besoin de polling. Enregistrez une URL webhook dans le dashboard ou via l'API, et CheckFile enverra un payload JSON signé en POST vers votre endpoint lorsque le traitement est terminé ou qu'une alerte est détectée.

Événement de validation terminée

{
  "event": "validation.completed",
  "timestamp": "2026-02-09T14:32:08Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "rule_set": "equipment-leasing",
    "verdict": "approved",
    "processing_time_ms": 4280,
    "documents": [
      {
        "filename": "contrat.pdf",
        "type": "contract",
        "verdict": "valid",
        "confidence": 0.97,
        "alerts": []
      },
      {
        "filename": "accord.pdf",
        "type": "agreement",
        "verdict": "valid",
        "confidence": 0.95,
        "alerts": []
      },
      {
        "filename": "kbis.pdf",
        "type": "company_registration",
        "verdict": "valid",
        "confidence": 0.99,
        "alerts": []
      }
    ]
  }
}

Événement d'alerte détectée

Lorsque l'IA détecte un problème potentiel pendant la validation, un événement d'alerte est émis immédiatement -- avant la fin de la validation complète. Cela permet à votre application de réagir aux problèmes de haute sévérité en temps réel.

{
  "event": "validation.alert",
  "timestamp": "2026-02-09T14:32:06Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "document": {
      "filename": "kbis.pdf",
      "type": "company_registration"
    },
    "alert": {
      "code": "DOC_EXPIRED",
      "severity": "high",
      "message": "Extrait Kbis expiré le 2025-11-30",
      "field": "validity_date",
      "extracted_value": "2025-11-30",
      "expected": "Le document doit dater de moins de 3 mois"
    }
  }
}

Vérification des signatures webhook

Chaque requête webhook inclut un header X-Checkfile-Signature contenant une signature HMAC-SHA256. Vérifiez-la avec votre secret webhook pour vous assurer que le payload n'a pas été altéré :

import hmac
import hashlib

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

Gestion des erreurs

L'API utilise les codes HTTP standards. Voici les erreurs les plus courantes et comment les gérer :

Stratégie de retry avec backoff exponentiel

Pour les erreurs transitoires (429, 500, 502, 503), implémentez un backoff exponentiel avec jitter :

import time
import random
import requests

def api_request_with_retry(method, url, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code < 400:
            return response

        if response.status_code in (429, 500, 502, 503):
            base_delay = min(2 ** attempt, 60)  # Plafond à 60 secondes
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            if response.status_code == 429:
                retry_after = response.headers.get("Retry-After")
                if retry_after:
                    delay = float(retry_after)

            time.sleep(delay)
            continue

        # Erreur non retryable
        response.raise_for_status()

    raise Exception(f"Nombre maximum de retries dépassé pour {url}")

Principes clés : ne jamais retrier les erreurs client 400 (sauf 429), toujours respecter le header Retry-After, et ajouter du jitter pour éviter le phénomène de "thundering herd" lorsque plusieurs clients retryent simultanément.

Patterns d'intégration

Trois patterns couvrent la majorité des scénarios d'intégration. Choisissez celui qui correspond à vos exigences de latence et de débit.

Pattern 1 : Validation en temps réel (upload, poll, affichage)

Idéal pour : les parcours utilisateur où l'utilisateur final attend le résultat (ex. formulaires d'onboarding).

L'utilisateur soumet un document
       |
       v
POST /v1/files  -->  retourne file_id
       |
       v
GET /v1/files/{id}/status  (poll toutes les 2s)
       |
       v
status == "completed"
       |
       v
GET /v1/files/{id}/results  -->  afficher à l'utilisateur

Latence typique : 3 à 8 secondes pour un document unique. Affichez un indicateur de progression. Si le traitement dépasse 15 secondes, affichez un message et proposez une notification par email.

Pattern 2 : Traitement par lots (upload batch, notification webhook)

Idéal pour : les workflows back-office traitant de gros volumes (ex. imports nocturnes, onboarding en masse).

Le système uploade N dossiers
       |
       v
POST /v1/files/batch  (pour chaque dossier)
       |
       v
La file de traitement gère tous les dossiers
       |
       v
Le webhook se déclenche pour chaque dossier terminé
       |
       v
Votre handler webhook met à jour la base de données interne

Ce pattern découple totalement la soumission du traitement. Votre système envoie et oublie, puis réagit aux événements webhook. Pour les très gros lots (1 000+ dossiers), étalez les uploads à 50 par minute pour rester dans les limites de débit et ne pas surcharger votre propre handler webhook.

Pattern 3 : Intégration CRM (Salesforce, HubSpot, custom)

Idéal pour : les équipes qui gèrent les dossiers clients dans un CRM et veulent que le statut de validation se synchronise automatiquement.

Le CRM déclenche l'upload (ex. changement de phase du deal)
       |
       v
Le middleware appelle POST /v1/files/batch
       |
       v
Le webhook se déclenche à la complétion
       |
       v
Le middleware mappe le résultat sur les champs CRM
       |
       v
Enregistrement CRM mis à jour (champs custom : validation_status, alerts)

La couche middleware (une fonction serverless légère ou une plateforme d'intégration comme Zapier/Make) traduit entre l'API CheckFile et le modèle de données de votre CRM. Mappings CRM courants :

Benchmarks de performance

Les temps de traitement dépendent du nombre de documents, de leur complexité et du jeu de règles appliqué. Les benchmarks suivants ont été mesurés sur l'infrastructure de production sous charge typique :

Ces temps reflètent le traitement de bout en bout incluant OCR, analyse IA, vérification croisée et évaluation des règles. Le temps d'upload (transfert réseau) n'est pas inclus et dépend de votre vitesse de connexion et de la taille des fichiers.

Pour les applications sensibles à la latence, deux optimisations sont utiles :

1. Compression pré-upload. Réduire la taille d'un PDF de 5 Mo à 1 Mo diminue le temps d'upload sans affecter la précision de validation. L'API accepte des fichiers jusqu'à 50 Mo, mais les fichiers plus légers traversent le pipeline plus rapidement.

2. Uploads parallèles. L'endpoint batch accepte jusqu'à 20 fichiers par requête. Pour les dossiers plus volumineux, découpez en plusieurs requêtes batch et uploadez en parallèle (dans votre limite de concurrence).

Démarrer

Le chemin le plus rapide de zéro à une intégration fonctionnelle :

1. Créez un compte et générez une clé API de test (ck_test_) depuis le dashboard.
2. Uploadez un document de test en utilisant l'exemple curl ci-dessus ou les exemples de code de ce guide.
3. Enregistrez un webhook pour recevoir les résultats de manière asynchrone.
4. Configurez un jeu de règles qui correspond à vos exigences métier.
5. Passez en production en remplaçant votre clé de test par une clé live (ck_live_).

FAQ

Quelle méthode d'authentification utiliser pour une intégration serveur-à-serveur ?

Pour les intégrations serveur-à-serveur, la clé API transmise dans le header X-API-Key est la méthode recommandée. Pour les applications multi-tenant où chaque utilisateur final doit avoir ses propres traces d'audit et permissions, OAuth 2.0 avec le flow authorization code est préférable. Les clés API doivent être stockées dans un gestionnaire de secrets (Vault, AWS Secrets Manager) et jamais en clair dans le code source ou les fichiers d'environnement committés.

Pourquoi utiliser des webhooks plutôt que du polling pour recevoir les résultats ?

Les webhooks éliminent le besoin de polling répété qui génère du trafic inutile et de la latence artificielle. En production, la validation d'un document prend 2 à 15 secondes : un système de polling toutes les 2 secondes effectue entre 1 et 8 requêtes inutiles avant d'obtenir le résultat. Les webhooks reçoivent le résultat dès qu'il est disponible, avec une signature HMAC-SHA256 à vérifier pour garantir l'authenticité du payload.

Quels délais de traitement peut-on espérer avec l'API en production ?

Les délais médians mesurés en production sont de 2,1 secondes pour un document d'identité unique, 3,4 secondes pour un contrat multi-pages, 12 secondes pour un dossier standard de 8 à 12 documents (leasing équipement), et 22 secondes pour un dossier complexe de 15 à 20 documents (conformité complète). Un lot de 100 dossiers est traité en 8 minutes au temps médian.

Comment implémenter une stratégie de retry robuste pour les erreurs transitoires ?

Les erreurs transitoires (429 Too Many Requests, 500, 502, 503) doivent être gérées avec un backoff exponentiel plafonné à 60 secondes, auquel s'ajoute un jitter aléatoire pour éviter que plusieurs clients ne refrappent simultanément. Le header Retry-After doit être respecté pour les erreurs 429. Les erreurs 4xx (sauf 429) ne doivent jamais être retriées car elles indiquent un problème dans la requête elle-même.

La documentation complète des endpoints, les SDKs (Python, Node.js, Go) et un explorateur API interactif sont disponibles sur docs.checkfile.ai. Pour un guide sur les architectures d'intégration ERP (Salesforce, SAP), consultez notre article intégration API et ERP. Si vous hésitez entre développer en interne et utiliser une plateforme, lisez notre analyse build vs buy. Si vous avez des questions sur le plan adapté à votre volume, consultez nos tarifs ou contactez directement l'équipe technique.