Retraitement et importation de base biométrique

Ce guide explique comment effectuer un retraitement ou une importation de base biométrique sur la plateforme Unico. Il détaille les exigences techniques et opérationnelles pour une intégration efficace et sécurisée, conforme aux bonnes pratiques de la plateforme.

Périmètre

Ce document couvre deux types de processus :

• Retraitement : retraitement des registres biométriques d'utilisateurs déjà passés par la base du client et d'Unico, en vue d'une réévaluation ou d'une migration entre systèmes.
• Importation de base biométrique : chargement initial ou mise à jour d'une base contenant des selfies à des fins de vérification d'identité et/ou de classification du risque de fraude.
• Importation de base de documents : chargement d'une base de documents accompagnée de selfies à des fins de vérification par Facematch ou CPF Match (Brésil uniquement).

Prérequis

• Le client doit disposer d'un contrat actif ou d'un accord de confidentialité (NDA) signé avec Unico et être en phase d'intégration (exception si approuvé par l'équipe de gouvernance).
• Le projet suivra des accords formels de TPS (transactions par seconde). Voir Accord TPS ci-dessous.
• Avant d'obtenir les identifiants de production, l'homologation complète de l'intégration est obligatoire pour garantir la qualité des données, la conformité du payload et la stabilité des performances.
• Un compte de service dédié doit être créé pour le retraitement ou l'importation (ex. : "Reprocessing" ou "Legacy_Import").
• Une clé API dédiée sera créée spécifiquement pour le retraitement/importation.
• (Optionnel) Une filiale dédiée peut être créée pour le retraitement/importation. Ce paramètre est identifié dans le payload par subsidiaryId. Voir Paramètres du payload ci-dessous.
• La clé API et le compte de service seront désactivés après la période convenue ou à la fin du traitement.

Capacités disponibles

Capacité	Description
Vérification d'identité	Vérifie si le selfie soumis appartient au véritable titulaire de l'identifiant.
Classification du risque de fraude	Vérifie s'il existe un historique de comportement frauduleux associé à ce visage.
Facematch	Vérifie si la photo du document correspond au selfie soumis.
CPF Match Brazil only	Vérifie si le CPF fourni correspond au numéro CPF imprimé sur le document. Remarque : tous les RGs n'ont pas le CPF imprimé.

Exigences relatives aux selfies

• Le selfie doit être soumis au format base64.
• L'image doit respecter la norme ICAO (fond clair, visage centré, pas d'accessoires obstruant l'identification, éclairage adéquat).
• Dimensions recommandées : ratio 1920x1080 ou 1080x1920.
• Taille maximale : 800 Ko (compresser en JPEG 92 si nécessaire).
• Orientation : portrait.

Exigences relatives aux documents

• Types de documents pris en charge : voir Capture de documents et réutilisation — Documents pris en charge.
• Les images doivent inclure à la fois le recto et le verso du document, entièrement visibles sans rognage.
• Le document doit être lisible — clair, bien éclairé et sans obstruction.

Accord TPS

• Le TPS maximum convenu pour ce projet est de 10 TPS.
• Répartissez les requêtes uniformément dans le temps plutôt que de les envoyer par rafales massives.
• Cette limite ne doit pas être dépassée sans approbation formelle de l'équipe Unico.
• Les requêtes au-delà de la limite peuvent être automatiquement rejetées ou bloquées.
• Si une augmentation temporaire est nécessaire, un accord formel préalable est requis.

Intégration

Endpoints

Environnement	URL de base	Accès	Notes
Staging	https://api.id.uat.unico.app	Ouvert	Obligatoire pour les tests
Production	https://api.id.unico.app	Uniquement après homologation approuvée	Nécessite un contrôle strict du TPS

En-têtes requis

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Paramètres du payload

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

Champ	Type	Requis	Description
subject	object	Oui	Données d'identification de l'utilisateur.
subject.duiType	integer	Oui	Identifiant du type de document. Voir valeurs de duiType ci-dessous.
subject.code	string	Oui	CPF ou autre identifiant utilisateur.
subject.name	string	Oui	Nom complet de l'utilisateur.
subject.email	string	Non	Adresse e-mail de l'utilisateur.
subject.phone	string	Non	Numéro de téléphone de l'utilisateur.
subject.birthDate	string	Non	Date de naissance de l'utilisateur (DD/MM/YYYY).
subject.gender	string	Non	Genre de l'utilisateur (M ou F).
useCase	string	Oui	Nom du cas d'utilisation ("Reprocessamento" ou "Importação de base").
subsidiaryId	string	Non	UUID de la filiale (fourni par Unico).
imageBase64	base64	Oui	Image selfie de l'utilisateur convertie en base64.
document	object	Non	Données du document associé au processus.
document.purpose	string	Non	Objet du document (ex. : "Reprocessamento").
document.documentId	string	Non	Identifiant du document.
document.files	array	Non	Liste des fichiers d'images du document.
document.files[].data	base64	Non	Image du document convertie en base64.
document.files[].faceDocumentMatch	boolean	Non	Indique si le visage dans le document correspond au selfie soumis.

Valeurs de duiType

Valeur	Description
0	Non spécifié
1	Brésil — CPF
2	Mexique — CURP
3	Identifiant interne Unico
4	États-Unis — SSN
5	Brésil — Passeport
6	Argentine — Passeport
7	Argentine — DNI
8	Nigéria — NIN
9	Chili — RUN
10	Équateur — NI
11	États-Unis — Passeport
12	Guatemala — CUI
13	Uruguay — CI
15	Adresse e-mail
16	Indonésie — NIK
17	Numéro de téléphone
18	États-Unis — Permis de conduire

Notes importantes

• Le selfie doit être conforme à la norme ICAO avec une qualité et un éclairage adéquats.
• Le selfie doit être au format base64.
• Évitez les envois massifs sans contrôle du TPS -- cela peut déclencher une limitation de débit (voir Gestion des erreurs ci-dessous).
• Testez toujours les données et l'intégration dans l'environnement de staging au préalable.

Réponses

Succès -- 200 OK

Sans document

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}

Champ	Type	Description
id	string	Identifiant du processus. Conservez-le pour des requêtes futures ou si vous implémentez la Validation (1:1) ultérieurement.
status	integer	Statut de la transaction.
unicoId.result	string	Réponse de la capacité Vérification d'identité.
identityFraudsters.result	string	Réponse de la capacité Classification du risque de fraude.

Avec document (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "identityFraudsters": {
    "result": "yes"
  }
}

Champ	Type	Description
id	string	Identifiant du processus. Conservez-le pour des requêtes futures ou si vous implémentez la Validation (1:1) ultérieurement.
status	integer	Statut de la transaction.
score	number	Score Facematch.
unicoId.result	string	Réponse de la capacité Vérification d'identité.
faceDocumentMatch.faceMatch	boolean	Si la photo du document correspond au selfie soumis.
identityFraudsters.result	string	Réponse de la capacité Classification du risque de fraude.

Erreur de traitement d'image

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

Erreurs courantes

Les codes dans la plage 4xx indiquent des erreurs de validation des données fournies. Les codes dans la plage 5xx indiquent des défaillances côté serveur.

Code HTTP	Type d'erreur	Cause probable	Action recommandée
400	Bad Request	Payload invalide	Validez la structure et le contenu.
401	Unauthorized	Token expiré ou invalide	Régénérez le token.
403	Forbidden	Clé API incorrecte ou permissions insuffisantes	Vérifiez les identifiants.
429	Too Many Requests	Débit de requêtes dépassé	Attendez et respectez la limite TPS.
500+	Internal Server Error	Défaillance interne	Réessayez après quelques secondes ; ouvrez un ticket si le problème persiste.

Gestion des erreurs

• Le Rate Limit (HTTP 429) doit être surveillé attentivement. Une surcharge de requêtes peut bloquer le pipeline.
• Respectez toujours le TPS convenu avec Unico (voir Accord TPS).
• Pour les défaillances persistantes (5xx), retraitez avec un contrôle de retry/backoff.