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

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, incluant les documents canadiens (permis de conduire provinciaux, carte RAMQ, NAS, certificats de conformité REQ).

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. Au Canada, la Loi sur l'intelligence artificielle et les données (projet de loi C-27) prévoit des obligations similaires pour les systèmes à incidence élevée.

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

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 journaux, conformément à la Loi 25 et à la LPRPDE.

# 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", "drivers_license", "invoice"
# country (optionnel) — code ISO 3166-1 alpha-2 (ex: CA)
# 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 — 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": "drivers_license",
  "country": "CA",
  "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 Tremblay",
    "date_of_birth": "1990-05-12",
    "document_number": "T1234-567890-01",
    "expiry_date": "2031-05-11",
    "province": "QC"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

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

Configuration des webhooks

Les architectures événementielles évitent la surcharge du polling. Enregistrez un endpoint webhook pour recevoir des notifications en temps réel.

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.

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 par courriel.

SDK et options d'intégration

Les SDK gèrent le rafraîchissement des jetons, les retries avec backoff exponentiel et la vérification des signatures webhook automatiquement.

Gestion des erreurs et limites de débit

Limites de débit par plan

Conformité et traitement des données

La Loi 25 du Québec et la LPRPDE fédérale imposent aux responsables de traitement de ne recourir qu'à des sous-traitants présentant des garanties suffisantes. CheckFile agit en tant que sous-traitant, avec un accord de traitement des données inclus dans tous les plans Business et Enterprise.

• 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 au Canada et en UE par défaut ; régions additionnelles disponibles sur les plans Enterprise
• Piste d'audit : chaque appel API génère un enregistrement immuable
• Certification SOC 2 Type II couvrant l'infrastructure API

Grille tarifaire

Consultez la page tarifs pour les détails.

Prise en charge des documents canadiens

L'API CheckFile prend en charge nativement l'ensemble des documents d'identité et d'entreprise canadiens :

• Permis de conduire provinciaux : tous les formats provinciaux et territoriaux, incluant le format québécois de la SAAQ
• Carte RAMQ : carte d'assurance maladie du Québec émise par la RAMQ
• Passeport canadien : format actuel avec MRZ, émis par IRCC
• Certificats de conformité REQ : documents du Registre des entreprises du Québec
• Avis de cotisation ARC : documents fiscaux de l'Agence du revenu du Canada
• Relevés de paie canadiens : avec extraction automatique des retenues TPS/TVQ/RRQ/RQAP

Le moteur de classification identifie automatiquement la province d'émission pour appliquer les règles de validation appropriées.

Démarrage rapide

1. Créez un compte sur checkfile.ai et générez vos identifiants API
2. Testez en sandbox — l'environnement sandbox reproduit la production avec des documents synthétiques
3. Intégrez en utilisant le SDK ou des appels REST directs
4. Passez en production — basculez vers les identifiants de production et configurez les webhooks

La documentation API inclut un playground interactif.

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, permis de conduire provinciaux, cartes RAMQ, factures, relevés bancaires, justificatifs de domicile, avis de cotisation de l'ARC et documents d'enregistrement d'entreprise (certificats de conformité REQ, statuts).

L'API est-elle conforme à la Loi 25 et à la LPRPDE ?

Oui. CheckFile agit en tant que sous-traitant avec accord de traitement signé, infrastructure de traitement hébergée au Canada et en UE, rétention configurable et expurgation automatique des données personnelles des journaux. 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. 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 et les signaux de fraude spécifiques.