API validation documentaire : guide intégration

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.

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

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 Résultats    |
                                    |  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.

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

Consultez nos tarifs pour le détail des plans.

Sécurité du transport

Tout le trafic est chiffré en TLS 1.3, les documents sont chiffrés au repos en AES-256 et automatiquement purgés selon la période de rétention (ISO/IEC 27001). Le certificate pinning est disponible pour les clients Enterprise. En savoir plus sur nos pratiques de sécurité.

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

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", ("req.pdf", open("req.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)

# É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';

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('req.pdf')]), 'req.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}`);

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());
}

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}`);
  }
}

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.

Vérification des signatures webhook

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)

Conformité réglementaire et API de validation documentaire au Canada

L'intégration d'une API de validation documentaire au Canada s'inscrit dans un cadre réglementaire précis. Les compagnies assujetties aux obligations de la LRPCFAT doivent mettre en place des contrôles automatisés de vérification d'identité. CANAFE recommande explicitement l'adoption de solutions automatisées pour les flux à distance, et la CAI du Québec encadre la conservation des renseignements personnels extraits des documents conformément à la Loi 25 et à la LPRPDE fédérale.

Démarrer

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_).

Pour une vue d'ensemble, consultez notre Guide pratique de la vérification de documents en 2026.

Passez à l'action

CheckFile vérifie 180 000 documents par mois avec 98,7 % de précision OCR. Testez la plateforme avec vos propres documents — résultats sous 48h.

Demander un pilote gratuit

---

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.

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.

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, et 22 secondes pour un dossier complexe de 15 à 20 documents.

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. 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. Consultez nos tarifs ou contactez directement l'équipe technique.