Espace développeur

Documentation de l'API PatriotAI

Une seule route à intégrer. Authentification par clé API, réponses JSON, codes d'erreur explicites.

🔑 Authentification

Chaque requête doit inclure l'en-tête X-API-KEY, fourni lors de l'approbation de votre dossier partenaire. La clé n'est jamais rediffusée : conservez-la comme un secret (variable d'environnement, coffre-fort de secrets).

📡 Endpoint de vérification

POST /api/v1/kyc/verify/

Corps de requête au format multipart/form-data.

Champ	Type	Description
`document_image`	fichier (image)	Photo de la CNI / du Permis de conduire.
`selfie_image`	fichier (image)	Photo instantanée du visage de l'utilisateur (un seul visage net).
`claimed_document_number`	string	Numéro de la pièce saisi par l'utilisateur.
`external_user_id`	string	Identifiant unique de l'utilisateur sur votre plateforme.

✅ Réponse de succès — 200 OK

{
  "status": "SUCCESS",
  "verification_id": "b3f1...",
  "identity_id": "9ad2...",
  "connected_account_id": "51ee...",
  "is_new_identity": true
}

⛔ Codes d'erreur

HTTP	Code	Signification
400	`INVALID_DOCUMENT_TEXT`	Le numéro déclaré n'a pas été retrouvé dans l'image du document.
400	`INVALID_DOC`	Ce document n'existe pas / n'est plus valide au registre d'État.
400	`FACE_NOT_DETECTED`	Aucun visage exploitable (ou plusieurs visages) sur le selfie.
400	`INVALID_UPLOAD`	Fichier non conforme (format, taille, contenu).
409	`MULTI_ACCOUNT_FRAUD_DETECTED`	Ce visage est déjà rattaché à une autre identité légale.
409	`DOCUMENT_IDENTITY_MISMATCH`	Ce numéro de document est déjà lié à un autre visage (usurpation potentielle).
401	`authentication_failed`	Clé API absente, invalide, ou plateforme non approuvée.
429	`throttled`	Quota d'appels dépassé.

💻 Exemple — cURL

curl -X POST https://api.patriotai.cm/api/v1/kyc/verify/ \
  -H "X-API-KEY: pai_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx" \
  -F "document_image=@cni.jpg" \
  -F "selfie_image=@selfie.jpg" \
  -F "claimed_document_number=102345678" \
  -F "external_user_id=driver_42"

🐍 Exemple — Python

import requests

resp = requests.post(
    "https://api.patriotai.cm/api/v1/kyc/verify/",
    headers={"X-API-KEY": "pai_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx"},
    files={
        "document_image": open("cni.jpg", "rb"),
        "selfie_image": open("selfie.jpg", "rb"),
    },
    data={
        "claimed_document_number": "102345678",
        "external_user_id": "driver_42",
    },
    timeout=15,
)
print(resp.status_code, resp.json())

📊 Quotas & disponibilité

Quota par défaut : 60 requêtes / minute par plateforme. Un garde-fou supplémentaire au niveau IP protège l'infrastructure contre les abus. Besoin d'un quota plus élevé pour votre volumétrie ? Contactez l'équipe technique via votre dossier partenaire.