Créer un processus

MarkdownChatGPTClaude

Ce endpoint gère trois produits qui partagent le même chemin mais diffèrent par les paramètres du corps, les capacités et les champs de réponse :

• Intégration -- valide l'identité de l'utilisateur en comparant son visage à la base d'identité Unico (subject.duiType + subject.code requis).
• Transactionnel -- vérifie que c'est la même personne qu'un processus précédent en comparant face à face (referenceProcessId OU tableau references avec selfie / ID de processus requis).
• Cardholder Verification -- confirme qu'une carte appartient à son titulaire déclaré, sans aucune capture de selfie (subject.code + card requis). Réutilise éventuellement un processus déjà validé via referenceProcessId pour activer le déclencheur de réutilisation ; sans lui, la réponse revient par défaut à unsure. Voir la capacité Cardholder Verification.

Le produit actif est déterminé par l'APIKEY envoyée dans l'en-tête de la requête.

Pour le flux d'intégration complet, voir Vue d'ensemble de l'API.

Endpoint

Environnement	URL
Production	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Requête

En-têtes

En-tête	Valeur
Authorization	Bearer <access_token> (voir Authentification)
APIKEY	Clé API provisionnée -- définit le produit actif et les capacités activées.
Content-Type	application/json

Paramètres du corps

Intégration

Champ	Type	Requis	Description
subject.duiType	integer	oui	Identifiant du type de document. Voir valeurs de duiType ci-dessous.
subject.code	string	oui	Valeur de l'identifiant telle que définie par subject.duiType. Sans points ni tirets.
subject.name	string	non	Nom complet.
subject.gender	string	non	M ou F.
subject.birthDate	string (ISO 8601)	non	Date de naissance (AAAA-MM-JJ).
subject.email	string	non	Adresse e-mail.
subject.phone	string	non	Numéro de téléphone au format E.164.
subject.clientReference	string	conditionnel	Identifiant unique de l'utilisateur dans votre système. Requis pour la capacité Multi-comptes. Unique dans votre base, maximum de 256 caractères, sans espaces.
useCase	string	non	Contexte de l'opération, ex. Onboarding.
subsidiaryId	string	non	ID de la filiale — requis uniquement si plusieurs filiales existent.
imageBase64	string	oui	Selfie capturé par votre front-end, en base64.

Transactionnel

Champ	Type	Requis	Description
references	array	conditionnel	Entrées de référence pour les flux de Validation 1:1. Chaque élément contient referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) et referenceContent (image encodée en base64 ou UUID de processus).
referenceProcessId	string	conditionnel	Déprécié. Utilisez references à la place. ID du processus d'Intégration de référence pour la comparaison. Si la référence est un processus by-Unico, utilisez authenticationInfo.authenticationId.
imageBase64	string	oui	Selfie capturé par votre front-end, en base64.
subject	object	non	Conteneur d'informations de l'utilisateur.
subject.duiType	string	non	Type d'identifiant. Valeurs possibles : DUI_TYPE_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
subject.code	string	non	Valeur de l'identifiant telle que définie par subject.duiType. Sans points ni tirets.
subject.name	string	non	Nom complet de l'utilisateur.
subject.gender	string	non	M ou F.
subject.birthDate	string (ISO 8601)	non	Date de naissance (AAAA-MM-JJ).
subject.email	string	non	Adresse e-mail.
subject.phone	string	non	Numéro de téléphone au format E.164.
useCase	string	non	Contexte de l'opération, ex. Transactional.
subsidiaryId	string	non	ID de la succursale -- requis uniquement si plusieurs succursales existent.

info

Pour ce produit, il n'est pas possible d'orchestrer avec le Score de Risque. Le résultat est toujours retourné de manière synchrone dans la réponse POST.

Cardholder Verification

Champ	Type	Requis	Description
subject.duiType	integer	oui	Identifiant du type de document. Voir valeurs de duiType ci-dessous. Actuellement DUI_TYPE_BR_CPF uniquement.
subject.code	string	oui	CPF du titulaire de la carte en cours de vérification. Sans points ni tirets.
card.bin	string	conditionnel	6 ou 8 premiers chiffres de la carte (BIN). Requis avec card.last4.
card.last4	string	conditionnel	4 derniers chiffres de la carte. Requis avec card.bin.
card.name	string	non	Nom du titulaire de la carte tel qu'imprimé sur la carte.
referenceProcessId	string (UUID)	non	ID d'un processus déjà validé à réutiliser -- un processus avec un résultat de Vérification d'identité ou de Détection de Vie approuvé pour le même CPF. La version actuelle de cette capacité repose sur la réutilisation : sans ce champ, le déclencheur n'est jamais activé et la réponse revient par défaut au résultat standard unsure — la requête elle-même n'échoue jamais.
useCase	string	non	Contexte de l'opération, ex. CardholderVerification.
subsidiaryId	string	non	ID de la filiale -- requis uniquement si plusieurs filiales existent.

info

Aucun imageBase64 n'est envoyé pour ce produit -- Cardholder Verification s'exécute entièrement côté back-end, sans étape de capture de selfie.

Valeurs de duiType

Pays	Code	Description
AR	6	Passeport argentin
AR	7	DNI argentin
AR	49	Permis de conduire argentin (Licencia Nacional de Conducir)
AT	34	Numéro fiscal autrichien (STNR)
BE	36	Numéro national belge (NN)
BR	1	CPF brésilien
BR	5	Passeport brésilien
BR	14	CNPJ brésilien
CA	28	Numéro d'assurance sociale canadien (NAS)
CH	33	Numéro AVS/AHV suisse
CL	9	RUN chilien
CL	52	Passeport chilien
CL	57	Permis de conduire chilien (Licencia de Conducir)
CO	26	NIT colombien
CO	53	Passeport colombien
CO	55	Permis de conduire colombien (Licencia de Conducción)
CO	56	Carte de citoyenneté colombienne (Cédula de Ciudadanía)
DE	41	Numéro d'identification fiscale allemand (IdNr)
DK	29	CPR danois
EC	10	NI équatorien
ES	50	Numéro d'identité d'étranger espagnol (NIE)
ES	51	Document national d'identité espagnol (DNI)
FI	35	Code d'identité personnelle finlandais (HETU)
FR	46	Numéro de référence fiscale français (SPI)
GB	30	Numéro d'assurance nationale britannique (NINO)
GT	12	CUI guatémaltèque
ID	16	NIK indonésien
IE	47	Numéro personnel de service public irlandais (PPSN)
IT	37	Codice Fiscale italien (CF)
LU	48	Numéro d'identification national luxembourgeois (Matricule)
MX	2	CURP mexicain
MX	25	RFC mexicain (Personne physique)
MX	58	Permis de conduire mexicain (Licencia de Conducir)
NG	8	NIN nigérian
NG	20	Numéro de vérification bancaire nigérian (BVN)
NG	43	Jeton BVN nigérian (haché)
NG	44	Jeton NIN nigérian (haché)
NL	42	Numéro de service citoyen néerlandais (BSN)
NO	39	Numéro d'identité national norvégien (Fødselsnummer)
PE	27	RUC péruvien
PE	40	DNI péruvien
PE	54	Passeport péruvien
PL	31	PESEL polonais
PT	45	Numéro d'identification fiscale portugais (NIF)
SE	32	Numéro personnel suédois (PNR)
SE	38	Numéro de coordination suédois (Samordningsnummer)
TR	24	Numéro d'identification turc (TCKN)
US	4	SSN américain
US	11	Passeport américain
US	18	Permis de conduire américain
US	21	Carte de passeport américaine
US	22	Passeport américain en polycarbonate
US	23	Carte d'identité américaine
UY	13	CI uruguayen
ZZ	15	Adresse e-mail
ZZ	17	Numéro de téléphone
—	0	Non spécifié
—	3	Identifiant interne Unico

Exigences d'image

• Résolution minimale : 640 x 480 (standard HD)
• Taille maximale du fichier : 800 Ko (compression JPEG92 recommandée)
• Formats acceptés : PNG, JPEG, WebP
• Les jetons JWT du SDK expirent après 10 minutes et ne peuvent être utilisés qu'une seule fois

Requêtes compressées

L'API prend en charge l'envoi du corps de la requête compressé, en utilisant l'en-tête HTTP standard Content-Encoding. Cela est optionnel et entièrement rétrocompatible : les clients qui n'envoient pas cet en-tête continuent de fonctionner exactement comme avant.

Formats pris en charge

Encodage	En-tête Content-Encoding	Statut
Gzip	gzip	✅ Recommandé
Deflate	deflate	✅ Pris en charge
Aucune compression	(en-tête absent)	✅ Pris en charge (comportement par défaut)

Recommandation

Utilisez gzip. Il bénéficie de la prise en charge la plus universelle parmi les langages et bibliothèques HTTP, évitant les ambiguïtés d'implémentation présentes dans les autres formats.

La compression est recommandée pour les requêtes avec un corps volumineux (ex. payloads JSON étendus, envois d'images encodées en base64, soumissions en batch). Pour les petites requêtes, le surcoût de la compression peut ne pas apporter de bénéfice pertinent.

Comment envoyer une requête compressée

1. Compressez le corps de la requête (ex. le JSON sérialisé) avec l'algorithme choisi.
2. Envoyez le corps compressé sous forme d'octets binaires dans la requête.
3. Incluez l'en-tête Content-Encoding avec la valeur correspondante (gzip ou deflate).
4. Conservez Content-Type décrivant le format du contenu d'origine (ex. application/json), pas l'encodage de transport.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

conseil

Pour l'exemple Python, utilisez le paramètre data=, pas json=. Le paramètre json= sérialise automatiquement la payload, mais ne la compresse pas.

En utilisant deflate à la place : le flux ci-dessus est identique — seuls l'appel de compression et la valeur Content-Encoding changent.

Langue	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (à partir de qpdf), puis -H "Content-Encoding: deflate"
Python	zlib.compress(data) au lieu de gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream au lieu de GZipStream

deflate est ambigu en pratique

L'encodage de contenu deflate de HTTP est spécifié comme un flux zlib (RFC 1950), mais certains clients et serveurs émettent ou attendent historiquement du DEFLATE brut (RFC 1951) à la place. Cette API attend le flux zlib standard — la même sortie que produisent par défaut zlib.compress() (Python) ou DeflateStream (.NET). En cas de doute, préférez gzip, qui ne présente pas cette ambiguïté.

Comportement en cas d'erreur

Si Content-Encoding est envoyé avec une valeur non prise en charge, ou si le corps est corrompu ou invalide pour l'encodage déclaré, l'API retourne 400 Bad Request avec un message indiquant que la décompression du corps de la requête a échoué.

FAQ

Dois-je changer quelque chose si je ne veux pas utiliser la compression ? Non. La prise en charge de Content-Encoding est additive — les requêtes sans cet en-tête continuent d'être traitées normalement.

Cela affecte-t-il la réponse de l'API ? Non. Cette fonctionnalité concerne uniquement le corps envoyé par le client (requête). La compression de la réponse (ce que l'API retourne) est contrôlée séparément par l'en-tête Accept-Encoding.

Quel format dois-je choisir ? Utilisez gzip, sauf si une contrainte spécifique de votre environnement exige un autre format.

Exemple

Intégration -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Intégration -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Transactionnel -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Transactionnel -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Réponses

Intégration

200 OK

Le contrat est unique — le champ idCloud.result porte le verdict consolidé des capacités utilisées.

Unico consolide les résultats des capacités exécutées en un seul idCloud.result, prêt à décider de la prochaine étape de votre flux — sans besoin d'orchestrer les résultats individuels.

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

Champ	Type	Description
id	string (UUID)	Identifiant du processus. Utilisez-le avec Get Process pour les re-requêtes.
status	integer	1 (en traitement), 3 (terminé avec succès), 5 (erreur).

Valeurs possibles du résultat

idCloud.result	Signification	Action recommandée
approved	Personne réelle et identité validée.	Poursuivez le flux.
denied	Identité non validée, échec de la détection de vie, ou risque extrême identifié.	Terminez le flux ou redirigez vers un flux alternatif.
critical-risk	Niveau de risque critique identifié.	Terminez le flux ou orientez vers une révision manuelle.
high-risk	Niveau de risque élevé identifié.	Orientez vers une révision manuelle ou un flux alternatif.
retry	Capture ou score insuffisant pour l'évaluation.	Demandez à l'utilisateur une nouvelle capture.
inconclusive	Preuves insuffisantes pour un verdict.	Orientez vers une révision manuelle ou un flux alternatif.

Les valeurs retournées dépendent de la recette configurée dans votre APIKey. Consultez Flux pour connaître les valeurs de résultat que chaque recette peut retourner.

Les clients au Brésil peuvent recevoir la réponse par capacité

La structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.

Les intégrations au Brésil peuvent recevoir les résultats ouverts, par capacité. Chaque capacité activée dans l'APIKey ajoute son propre bloc à la réponse — les champs des capacités désactivées sont omis.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Les champs de réponse dépendent de votre APIKey

L'exemple ci-dessus présente tous les champs de capacité possibles. Votre réponse réelle n'inclura que les champs correspondant aux capacités activées dans votre configuration APIKey — les champs des capacités désactivées sont entièrement omis. Contactez votre chef de projet Unico pour activer ou ajuster des capacités.

Champ	Type	Description
unicoId.result	string	yes, no, inconclusive -- voir Vérification d'identité.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive -- voir les valeurs possibles ci-dessous ou la Classification du risque de fraude.
idFace.result	string	FOUND — voir Identifiant Facial.
idFace.personId	string	Identifiant opaque stable pour le visage, retourné conjointement à idFace.result = FOUND. Lorsqu'aucun visage ne peut être identifié dans l'image, la requête échoue avec l'erreur 20532 au lieu de retourner un bloc idFace.
identityFraudsters.result	string	Obsolète. Utilisez riskLevel à la place. Les clients dont les intégrations sont en cours peuvent continuer à l'utiliser pendant qu'ils coordonnent la migration avec l'équipe responsable du projet.
government.serpro	integer	Score de similarité Serpro (0-100, -1, -2). Disponible au Brésil uniquement. Voir Retour de similarité Serpro.
liveness	integer	1 (réussi), 2 (échoué) -- voir Détection de Vie.

riskLevel.result — valeurs possibles

Valeur	Signification
approved	Il s'agit du visage du titulaire de la pièce d'identité et aucun indice lié à une fraude n'a été détecté.
reproved	Le rejet est recommandé, car plusieurs indicateurs de fraude ont été détectés.
risk-critical	Le rejet est recommandé, mais la décision finale appartient à votre appréciation. Le risque critique indique qu'au moins 2 preuves solides de fraude ont été trouvées.
risk-high	Le rejet est également recommandé, mais la décision vous appartient. Le risque élevé indique qu'au moins une preuve solide de fraude a été trouvée.
inconclusive	Aucune preuve solide de fraude n'a été trouvée. Il n'est donc pas possible de conclure s'il existe un risque pertinent ou non.

info

Lorsque unicoId.result = inconclusive et que l'orchestration du Score de Risque est active, le processus peut retourner status: 1 (en traitement). Interrogez Get Process ou utilisez les webhooks pour récupérer le résultat final.

Les clients au Mexique peuvent recevoir le bloc RENAPO Verification

La réponse conserve la même structure et ajoute le bloc idGov.

Les intégrations au Mexique avec RENAPO Verification activé reçoivent un bloc `idGov` supplémentaire contenant l'enregistrement que le RENAPO détient pour la CURP de l'utilisateur. Il s'agit d'une réponse distincte du résultat d'identité.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Champ	Type	Description
idGov	object	Enregistrement du RENAPO pour la CURP. Absent lorsque la capacité n'est pas activée. {} lorsque le RENAPO n'a pas répondu. Mexique uniquement. Voir RENAPO Verification.

Transactionnel

200 OK

Le contrat est unique — le champ idCloud.result porte le verdict consolidé des capacités utilisées.

Unico consolide les résultats des capacités exécutées en un seul idCloud.result, prêt à décider de la prochaine étape de votre flux — sans besoin d'orchestrer les résultats individuels.

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

Champ	Type	Description
id	string (UUID)	Identifiant du processus.
status	integer	3 (terminé avec succès), 5 (erreur). Pour toutes les valeurs possibles, voir Get Process.

Valeurs possibles du résultat

idCloud.result	Signification	Action recommandée
approved	Personne réelle et identité validée.	Poursuivez le flux.
denied	Identité non validée, échec de la détection de vie, ou risque extrême identifié.	Terminez le flux ou redirigez vers un flux alternatif.
critical-risk	Niveau de risque critique identifié.	Terminez le flux ou orientez vers une révision manuelle.
high-risk	Niveau de risque élevé identifié.	Orientez vers une révision manuelle ou un flux alternatif.
retry	Capture ou score insuffisant pour l'évaluation.	Demandez à l'utilisateur une nouvelle capture.
inconclusive	Preuves insuffisantes pour un verdict.	Orientez vers une révision manuelle ou un flux alternatif.

Les valeurs retournées dépendent de la recette configurée dans votre APIKey. Consultez Flux pour connaître les valeurs de résultat que chaque recette peut retourner.

Les clients au Brésil peuvent recevoir la réponse par capacité

La structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.

Les intégrations au Brésil peuvent recevoir les résultats ouverts, par capacité. Chaque capacité activée dans l'APIKey ajoute son propre bloc à la réponse — les champs des capacités désactivées sont omis.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": {
    "result": true
  },
  "liveness": 1
}

Champ	Type	Description
biometryToken.result	boolean	true si le visage soumis correspond au processus de référence ; false sinon.
liveness	integer	1 (réussi), 2 (échoué) -- voir Détection de Vie.

Cardholder Verification

200 OK

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

Champ	Type	Description
id	string (UUID)	Identifiant du processus.
status	integer	1 (en traitement), 3 (terminé avec succès), 5 (erreur). Pour toutes les valeurs, voir Get Process.
cardholderVerification.result	string	approved -- le CPF et la carte appartiennent à la même personne. unsure -- soit la condition de réutilisation n'a pas été satisfaite, soit la vérification elle-même était non concluante. Absent lorsque status n'est pas encore 3. Voir Cardholder Verification.

Codes d'erreur

400 Bad Request

Code	Message	Description
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	Le flux de réutilisation (referenceProcessId/bioTokenId, sans image) a été rejeté car la réutilisation de processus n'est pas activée pour cette clé API.
20900	O base64 informado não é válido.	Le paramètre base64 est invalide. Causes possibles : ce n'est pas une image ou c'est une tentative d'injection.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	La résolution de l'image téléchargée est trop faible.
20532	No face detected in image.	Aucun visage n'a pu être détecté dans l'image envoyée.
20513	The referenced process was not found.	Le referenceProcessId pointe vers un processus qui n'existe pas ou n'est plus accessible.
20512	The referenced process is not available for reuse.	Le processus référencé existe mais n'est pas disponible pour réutilisation.
20509	The subject.name field is invalid.	subject.name contient des caractères invalides.
20508	The subject.gender field is invalid.	subject.gender doit être M ou F.
20507	O parâmetro subject.code é inválido.	CPF non standard ou inexistant.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	La taille de l'image dépasse 800 Ko ; compressez en JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Le format base64 est invalide ou non pris en charge.
20065	The referenceProcessId field is invalid.	Le referenceProcessId n'est pas un UUID valide.
20062	The useCase field is invalid.	Valeur non reconnue dans le champ useCase.
20024	The referenceProcessId field is missing.	Le paramètre referenceProcessId n'a pas été fourni et references n'a pas été envoyé comme alternative. Ne s'applique pas à Cardholder Verification -- son referenceProcessId n'est jamais validé comme requis ; une condition de réutilisation non satisfaite répond unsure à la place.
20533	The card field is missing.	Cardholder Verification : l'objet card n'a pas été fourni.
20534	The card.bin field is missing.	Cardholder Verification : card.bin n'a pas été fourni.
20535	The card.last4 field is missing.	Cardholder Verification : card.last4 n'a pas été fourni.
20536	The card data is invalid.	Cardholder Verification : les données de la carte ont été rejetées comme invalides.
20021	The subject.phone field is invalid.	Le format de subject.phone est invalide (IDD + indicatif régional + numéro, 13 caractères).
20019	The subject.birthDate field is invalid.	subject.birthDate n'est pas au format ISO 8601 (AAAA-MM-JJ).
20009	O parâmetro imagebase64 não foi informado.	Le paramètre d'image selfie est manquant.
20008	The subject.email field is invalid.	Format d'e-mail invalide dans subject.email.
20006	O parâmetro subject.name não foi informado.	Le paramètre subject.name est manquant.
20005	O parâmetro subject.code não foi informado.	Le paramètre subject.code est manquant.
20004	O parâmetro subject não foi informado.	Le paramètre subject est manquant.
20003	The request body is missing or invalid.	Payload nul ou invalide.
20002	O parâmetro APIKey não foi informado.	Le paramètre APIKEY est manquant dans l'en-tête de la requête.
20001	O parâmetro authtoken não foi informado.	Le paramètre de jeton d'intégration est manquant dans l'en-tête de la requête.
10508	The JWT with the captured face has already been used.	Le JWT ne peut être utilisé qu'une seule fois.
10507	The JWT with the captured face is expired.	Le JWT a expiré ; il doit être envoyé dans les 10 minutes.
10506	The imageBase64 field is not a valid JWT from SDK.	Le champ imageBase64 n'est pas un JWT valide généré par le SDK.

403 Forbidden

Le Bearer token ou l'APIKEY est manquant, expiré ou invalide. Voir Authentification.

Code	Message	Description
30017	User does not have permission to perform this action.	JWT malformé ou utilisateur sans permission pour effectuer cette opération.
10502	O token informado está expirado.	Le jeton d'accès a expiré.
10501	O token informado é inválido.	Le jeton d'authentification est invalide.
10201	O AppKey informado é inválido.	L'APIKEY est invalide ou n'existe pas.

409 Conflict

Code	Message	Description
20073	The processID already exists.	Le processId fourni existe déjà pour ce tenant.

429 Too Many Requests

Limite de débit atteinte. Lorsque votre système reçoit une erreur HTTP 429, vous devez implémenter des mécanismes pour prévenir les défaillances en cascade et éviter d'aggraver la restriction.

Bonnes pratiques :

• Période de refroidissement (backoff) : Arrêtez ou limitez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées en boucle serrée.
• Mise en file d'attente et limitation : Mettez en tampon ou en file d'attente les requêtes sortantes de votre côté pour contrôler le flux de trafic avant de les renvoyer.
• Backoff exponentiel avec jitter : Lors des nouvelles tentatives, augmentez le temps d'attente de manière exponentielle entre les tentatives (ex. : 1 s, 2 s, 4 s, 8 s) et ajoutez un petit délai aléatoire (« jitter ») pour éviter un effet de troupeau où toutes les requêtes en file d'attente réessaient exactement à la même milliseconde.

avertissement

Frapper continuellement un endpoint limité en débit sans faire de backoff peut prolonger la période de restriction et impacter sévèrement le débit opérationnel de votre système. Limiter correctement les requêtes de votre côté assure une intégration plus fluide et plus résiliente.

Pour les limites par défaut, l'augmentation des requêtes et des détails supplémentaires, voir Limites de débit.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later	Lorsqu'il y a une erreur interne.

Prochaines étapes

• Pour interroger le résultat d'un processus d'Intégration, voir Get Process.
• Pour voir toutes les combinaisons de recettes et leurs valeurs de résultat possibles, voir Flux.
• Pour les opérations de Document et de Vérification de l'âge, voir les pages respectives dans cette section.