Créer un processus

Ce point de terminaison gère deux cas d'usage 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 qui est l'utilisateur en comparant son visage avec la base d'identité d'Unico (subject.code requis).
Transactionnel — vérifie qu'il s'agit de la même personne qu'un processus précédent en comparant face à face (referenceProcessId OU tableau references avec selfie / process id requis).

Le cas d'usage 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.

Point de terminaison

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

Paramètres du corps

Intégration
Transactionnel

Champ	Type	Requis	Description
`subject.code`	string	oui	CPF (BR) ou CURP (MX).
`subject.name`	string	oui	Nom complet.
`subject.gender`	string	non	`M` ou `F`.
`subject.birthDate`	string (ISO 8601)	non	Date de naissance (`YYYY-MM-DD`).
`subject.email`	string	non	Adresse e-mail.
`subject.phone`	string	non	Numéro de téléphone E.164.
`useCase`	string	non	Contexte de l'opération, ex. `Onboarding`.
`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 du processus).
`referenceProcessId`	string	conditionnel	Déprécié. Utilisez `references` à la place. ID du processus d'Onboarding de référence à comparer. 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 sur l'utilisateur.
`subject.code`	string	non	CPF (BR) ou CURP (MX).
`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 (`YYYY-MM-DD`).
`subject.email`	string	non	Adresse e-mail.
`subject.phone`	string	non	Numéro de téléphone E.164.
`useCase`	string	non	Contexte de l'opération, ex. `Transactional`.
`subsidiaryId`	string	non	ID de la filiale — requis uniquement si plusieurs filiales existent.

info

Pour ce cas d'usage, il n'est pas possible d'orchestrer avec la Classification du risque de fraude. Le résultat est toujours retourné de manière synchrone dans la réponse POST.

Exigences relatives à l'image

Résolution minimale : 640 × 480 (standard HD)
Taille maximale du fichier : 800 Ko (compression JPEG92 recommandée)
Formats acceptés : PNG, JPEG, WebP
Les tokens 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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    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" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Champ	Type	Description
`id`	string (UUID)	Identifiant du processus. À utiliser avec Obtenir le processus pour les nouvelles requêtes.
`status`	integer	`1` (en traitement), `3` (terminé avec succès), `5` (erreur). Pour toutes les valeurs possibles, voir Obtenir le processus.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — voir Vérification d'identité.
`identityFraudsters.result`	string	`yes`, `inconclusive` — voir Classification du risque de fraude.
`government.serpro`	integer	Score de similarité Serpro (0–100, -1, -2). Voir Retour de similarité Serpro.
`liveness`	integer	`1` (réussi), `2` (échoué) — voir Détection de Vie.

info

Lorsque unicoId.result = inconclusive et que l'orchestration de la Classification du risque de fraude est active, le processus peut retourner status: 1 (en traitement). Interrogez Obtenir le processus 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 Obtenir le processus.
`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 Codes d'erreur ci-dessous.

403 Forbidden

Token Bearer ou APIKEY manquant, expiré ou invalide. Voir Authentification.

409 Conflict

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

429 Too Many Requests

Limite de débit atteinte. Réessayez après l'intervalle indiqué dans l'en-tête de réponse Retry-After. 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 la 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 (`YYYY-MM-DD`).
`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 absent de l'en-tête de la requête.
`20001`	O parâmetro authtoken não foi informado.	Le paramètre de token d'intégration est absent de 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.	JWT expiré ; 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 token 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'une erreur interne survient.

Étapes suivantes

Pour interroger le résultat d'un processus d'intégration, voir Obtenir le processus.
Pour les opérations de document et de Vérification de l'âge, voir les pages correspondantes dans cette section.

Point de terminaison​

Requête​

Exemple​

Réponses​

Codes d'erreur​

Étapes suivantes​