Créer un processus

Ce endpoint gère deux cas d'utilisation 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).

Le cas d'utilisation 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 cas d'utilisation actif et les capacités activées.
`Content-Type`	`application/json`

Paramètres du corps

Intégration
Transactionnel

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

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_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`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 cas d'utilisation, 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.

Valeurs de duiType

Pays	Code	Description
BR	1	CPF brésilien
BR	5	Passeport brésilien
MX	2	CURP mexicain
AR	6	Passeport argentin
AR	7	DNI argentin
US	4	SSN américain
US	11	Passeport américain
US	18	Permis de conduire américain
ID	16	NIK indonésien
NG	8	NIN nigérian
CL	9	RUN chilien
EC	10	NI équatorien
GT	12	CUI guatémaltèque
UY	13	CI uruguayen
ZZ	15	Adresse e-mail
ZZ	17	Numéro de téléphone
MX	25	RFC mexicain (Personne physique)
CO	26	NIT colombien
PE	27	RUC péruvien
CA	28	Numéro d'assurance sociale canadien (NAS)
DK	29	CPR danois
GB	30	Numéro d'assurance nationale britannique (NINO)
PL	31	PESEL polonais
SE	32	Numéro personnel suédois (PNR)
AT	34	Numéro fiscal autrichien (STNR)
FI	35	Code d'identité personnelle finlandais (HETU)
—	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

Exemple

Intégration -- cURL
Intégration -- Node.js
Transactionnel -- cURL
Transactionnel -- Node.js

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..."
  }'

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();

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..."
  }'

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();

Réponses

Intégration
Transactionnel

200 OK

{
  "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
`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).
`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`, `NOT_FOUND` — voir Face Identifier.
`idFace.personId`	string	Identifiant opaque stable pour le visage. Présent uniquement lorsque `idFace.result = FOUND`.
`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.

200 OK

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

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

400 Bad Request

Le payload est malformé, l'image est invalide ou des champs requis sont manquants. Voir les Codes d'erreur ci-dessous.

403 Forbidden

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

409 Conflict

Le processId fourni existe déjà pour ce tenant. Voir les Codes d'erreur ci-dessous.

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.

Codes d'erreur

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Message	Description
`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.
`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.
`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.

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.

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

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 les opérations de Document et de Vérification de l'âge, voir les pages respectives dans cette section.

Endpoint​

Requête​

Exemple​

Réponses​

Codes d'erreur​

Prochaines étapes​