Jabali OCR API

Documentation officielle

Sommaire

Introduction

Bienvenue dans la documentation de l'API Jabali OCR. Cette API permet de scanner et d'extraire automatiquement les données de documents d'identité comme les passeports et les cartes d'identité nationales. Ce document vous guidera à travers les différentes fonctionnalités et vous montrera comment utiliser cette API.

L'API Jabali OCR est capable de traiter trois types de documents : les passeports (PASSPORT), le recto de la carte d'identité (IDENTITY_CARD_RECTO) et le verso de la carte d'identité (IDENTITY_CARD_VERSO).

Authentification

Pour utiliser l'API Jabali OCR, vous devez d'abord vous authentifier pour obtenir un token JWT. Ce token sera nécessaire pour toutes les requêtes ultérieures.

Endpoint d'authentification

POST https://tests.eyone.cartaware.cartalink.com/auth/signin

Corps de la requête:

{
  "emailAddress": "votre_email@exemple.com",
  "password": "votre_mot_de_passe"
}

En-têtes requis:

  • X-Tenant-ID: [votre_tenant_id]

Exemple de requête (cURL):

curl --request POST \
    --url https://tests.eyone.cartaware.cartalink.com/auth/signin \
    --header 'Content-Type: application/json' \
    --header 'X-Tenant-ID: votre_tenant_id' \
    --data '{
      "emailAddress":"votre_email@exemple.com",
      "password":"votre_mot_de_passe"
  }'

Réponse en cas de succès:

{
    "timestamp": 1743115909,
    "status": 200,
    "message": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "account": {
        "userId": "admin",
        "accountFirstname": "Admin",
        "accountLastname": "CLK",
        "accountEmail": "admin@sens-numerik.com",
        "userRoles": "DEVELOPPER",
        "brigade": "CARTALINK",
        "companyId": "1",
        "companyName": "Sens NumeriK",
        "accountId": "1"
    },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Important: Conservez la valeur du champ access_token qui vous sera nécessaire pour toutes les requêtes suivantes. Ce token doit être inclus dans l'en-tête Authorization de chaque requête sous la forme Bearer [token].

Endpoints

Traitement d'un document unique

Cet endpoint vous permet de traiter un seul document, qu'il s'agisse d'un passeport ou d'une carte d'identité (recto ou verso).

Endpoint

POST https://tests.eyone.cartaware.cartalink.com/ocr/document/process

En-têtes requis:

  • Authorization: Bearer [votre_token_jwt]
  • X-Customer-ID: [votre_clé_client]
  • X-Tenant-ID: [votre_tenant_id]

Paramètres du formulaire:

Paramètre Description Requis
file Fichier image (JPG, PNG) ou PDF du document Oui
documentType Type de document: PASSPORT, IDENTITY_CARD_RECTO ou IDENTITY_CARD_VERSO Oui

Exemple de requête (cURL):

curl -X POST https://tests.eyone.cartaware.cartalink.com/ocr/document/process \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "X-Customer-ID: votre_cle_client" \
  -H "X-Tenant-ID: votre_tenant_id" \
  -F "file=@/chemin/vers/votre/document.jpg" \
  -F "documentType=PASSPORT"

PASSPORT

Passport Image

Traitement multi-documents

Cet endpoint vous permet de traiter à la fois le recto et le verso d'une carte d'identité en une seule requête.

Endpoint

POST https://tests.eyone.cartaware.cartalink.com/ocr/document/multi-page

En-têtes requis:

  • Authorization: Bearer [votre_token_jwt]
  • X-Customer-ID: [votre_clé_client]
  • X-Tenant-ID: [votre_tenant_id]

Paramètres du formulaire:

Paramètre Description Requis
files Fichier image (JPG, PNG) ou PDF du recto et verso de la carte d'identité Oui
documentTypes Type de document (IDENTITY_CARD_RECTO et IDENTITY_CARD_VERSO) Oui

Exemple de requête (sur Insomnia):

curl --request POST \
--url https://tests.eyone.cartaware.cartalink.com/ocr/document/multi-page \
--header 'Authorization: Bearer votre_token_jwt' \
--header 'Content-Type: multipart/form-data' \
--header 'X-Customer-ID: votre_clé_client' \
--header 'X-Tenant-ID: votre_tenant_id' \
--form 'files=@/chemin/vers/votre/recto.jpg' \
--form documentTypes=IDENTITY_CARD_RECTO \
--form 'files=@/chemin/vers/votre/verso.jpg' \
--form documentTypes=IDENTITY_CARD_VERSO
UploadMultiple Image

Formats de réponse

Les réponses de l'API varient en fonction du type de document traité. Voici les différentes structures de réponse:

Réponse pour un passeport (PASSPORT)

{
    "firstName": "John",
    "lastName": "DOE",
    "dateOfBirth": "01/01/1990",
    "gender": "M",
    "placeOfBirth": "PARIS",
    "issueDate": "01/01/2020",
    "expirationDate": "01/01/2030",
    "countryCode": "FRA",
    "documentType": "P",
    "passportNumber": "12AB34567",
    "nationality": "FRANÇAISE",
    "personalNumber": "123456789012",
    "issuingAuthority": "PRÉFET",
    "detectedDocumentType": "PASSPORT",
    "processingCost": 2.50
}
Champ Description Type
firstName Prénom String
lastName Nom String
dateOfBirth Date de naissance String
gender Genre String ("M" ou "F")
placeOfBirth Lieu de naissance String
issueDate Date d'émission String
expirationDate Date d'expiration String
countryCode Code pays String
documentType Type de document String
passportNumber Numéro de passeport String
nationality Nationalité String
personalNumber Numéro d'identification national String
issuingAuthority Autorité émettrice String
detectedDocumentType Type de document détecté String
processingCost Coût de traitement Number

Réponse pour le recto d'une carte d'identité (IDENTITY_CARD_RECTO)

{
    "cardNumber": "123456789012",
    "firstName": "JEAN",
    "lastName": "DUPONT",
    "dateOfBirth": "01/01/1990",
    "gender": "M",
    "height": "180",
    "placeOfBirth": "PARIS",
    "issueDate": "01/01/2020",
    "expirationDate": "01/01/2030",
    "registrationCenter": "PRÉFECTURE DE POLICE",
    "homeAddress": "1 RUE DE LA PAIX 75001 PARIS",
    "detectedDocumentType": "IDENTITY_CARD_RECTO",
    "processingCost": 2.50
}
Champ Description Type
cardNumber Numéro de carte String
firstName Prénom String
lastName Nom String
dateOfBirth Date de naissance String
gender Genre String ("M" ou "F")
height Taille String
placeOfBirth Lieu de naissance String
issueDate Date d'émission String
expirationDate Date d'expiration String
registrationCenter Centre d'enregistrement String
homeAddress Adresse de résidence String
detectedDocumentType Type de document détecté String
processingCost Coût de traitement Number

Réponse pour le verso d'une carte d'identité (IDENTITY_CARD_VERSO)

{
    "countryCode": "FRA",
    "voterNumber": "123456789",
    "region": "ILE-DE-FRANCE",
    "department": "PARIS",
    "commune": "PARIS",
    "votingPlace": "MAIRIE DU 1ER",
    "votingBooth": "BUREAU 12",
    "nin": "1900175123456",
    "detectedDocumentType": "IDENTITY_CARD_VERSO",
    "processingCost": 2.50
}
Champ Description Type
countryCode Code pays String
voterNumber Numéro d'électeur String
region Région String
department Département String
commune Commune String
votingPlace Lieu de vote String
votingBooth Bureau de vote String
nin Numéro d'identification national String
detectedDocumentType Type de document détecté String
processingCost Coût de traitement Number

Réponse pour un traitement multi-documents (recto et verso d'une carte d'identité)

[
    {
        "cardNumber": "123456789012",
        "firstName": "JEAN",
        "lastName": "DUPONT",
        "dateOfBirth": "01/01/1990",
        "gender": "M",
        "height": "180",
        "placeOfBirth": "PARIS",
        "issueDate": "01/01/2020",
        "expirationDate": "01/01/2030",
        "registrationCenter": "PRÉFECTURE DE POLICE",
        "homeAddress": "1 RUE DE LA PAIX 75001 PARIS",
        "detectedDocumentType": "IDENTITY_CARD_RECTO",
        "processingCost": 2.50
    },
    {
        "countryCode": "FRA",
        "voterNumber": "123456789",
        "region": "ILE-DE-FRANCE",
        "department": "PARIS",
        "commune": "PARIS",
        "votingPlace": "MAIRIE DU 1ER",
        "votingBooth": "BUREAU 12",
        "nin": "1900175123456",
        "detectedDocumentType": "IDENTITY_CARD_VERSO",
        "processingCost": 2.50
    }
]

Dans le cas d'un traitement multi-documents, la réponse est un tableau contenant deux objets : le premier correspond aux données du recto de la carte d'identité et le second aux données du verso.

Gestion des erreurs

L'API Jabali OCR renvoie des codes d'état HTTP standard pour indiquer le succès ou l'échec d'une requête. En cas d'erreur, le corps de la réponse contiendra des informations supplémentaires sur la nature de l'erreur.

Code HTTP Description
200 OK La requête a réussi.
400 Bad Request La requête était incorrecte. Vérifiez les paramètres fournis.
401 Unauthorized Authentification requise ou token invalide.
403 Forbidden Vous n'avez pas les permissions nécessaires pour cette opération.
404 Not Found La ressource demandée n'existe pas.
415 Unsupported Media Type Le format de fichier n'est pas pris en charge.
422 Unprocessable Entity Le document ne peut pas être traité (qualité insuffisante, document non reconnu, etc.).
500 Internal Server Error Une erreur interne s'est produite sur le serveur.

Exemple de réponse d'erreur

{
    "errors": [
    "Description de l'erreur"
    ]
}

Bonnes pratiques

Qualité des images

Assurez-vous que les images de documents soumises sont de bonne qualité pour un meilleur taux de reconnaissance:

  • Résolution recommandée: au moins 300 DPI
  • Bon éclairage, sans reflets ni ombres
  • Document complet et bien cadré dans l'image
  • Format préféré: JPEG ou PNG

Gestion des tokens

Pour une meilleure expérience d'intégration:

  • Stockez le token JWT de manière sécurisée
  • Implémentez un mécanisme de rafraîchissement de token
  • Gérez les erreurs 401 en réessayant l'authentification automatiquement

Traitement des résultats

Pour exploiter efficacement les résultats de l'OCR:

  • Validez toujours les données extraites côté client
  • Mettez en place une interface utilisateur permettant de corriger les erreurs potentielles
  • Vérifiez la cohérence des dates (émission, expiration)
  • Stockez les données extraites en respectant les réglementations en vigueur (RGPD, CDP)

Gestion des erreurs

Pour une expérience utilisateur optimale:

  • Implémentez un système de nouvelle tentative en cas d'échec temporaire
  • Proposez des messages d'erreur clairs à vos utilisateurs
  • Loggez les erreurs pour faciliter le diagnostic
  • Prévoyez un mode de secours pour la saisie manuelle des informations en cas d'échec répété

Besoin d'aide supplémentaire ?

Si vous avez des questions sur l'intégration de l'API Jabali OCR dans votre application, n'hésitez pas à contacter notre équipe technique à support@jabali.sn.