Vérification de l'âge

Pour le flux d'intégration complet, consultez 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 — doit avoir les capacités de Vérification de l'âge activées.
Content-Type	application/json

Paramètres du corps

Champ	Type	Requis	Description
subject	object	oui	Conteneur d'informations utilisateur.
subject.code	string	conditionnel	CPF (BR) ou CURP (MX), sans formatage. Requis lorsque le flux inclut la Détection de Vie ou la Vérification d'identité (voir capacité Vérification de l'âge) ; non requis pour les flux de Vérification de l'âge uniquement.
subject.name	string	non	Nom complet de l'utilisateur.
subject.gender	string	non	M pour masculin ou F pour féminin.
subject.birthDate	string (ISO 8601)	non	Date de naissance (YYYY-MM-DD).
subject.email	string	non	Adresse e-mail de l'utilisateur.
subject.phone	string	non	Numéro de téléphone : indicatif pays + indicatif régional + numéro, sans séparateurs (ex. : 5519725570707).
useCase	string	non	Identifiant du cas d'usage de l'opération.
subsidiaryId	string	non	ID de la succursale — requis uniquement si plusieurs succursales existent.
imageBase64	string	oui	Sortie SDK chiffrée ou image en base64 (PNG, JPEG, WebP).

Exigences relatives aux images

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

Exemple

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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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: {
      code: '12345678909',
      name: 'Luke Skywalker',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Réponses

200 OK

Les champs de réponse retournés dépendent des capacités activées pour votre APIKEY.

Vérification de l'âge uniquement (sans Détection de Vie, sans Vérification d'identité) :

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

Vérification de l'âge + Détection de Vie + Vérification d'identité :

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

Champ	Type	Description
id	string (UUID)	Identifiant du processus. À utiliser avec Obtenir le processus pour les nouvelles requêtes.
status	integer	3 (terminé avec succès), 5 (erreur). N'utilisez status = 3 que pour les décisions métier. Pour toutes les valeurs possibles, voir Obtenir le processus.
idAge.result	string	yes, no, inconclusive — Résultat de la Vérification de l'âge. Présent dans toutes les réponses.
unicoId.result	string	yes, no, inconclusive — présent uniquement lorsque la Vérification d'identité est activée.
liveness	integer	1 (réussi), 2 (échoué) — présent uniquement lorsque la Détection de Vie est activée.

400 Bad Request

Le payload est malformé, l'image est invalide ou des champs requis sont manquants.

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.

500 Internal Server Error

Erreur serveur inattendue.

Codes d'erreur

400 Bad Request

Code	Message	Description
20900	O base64 informado não é válido.	Paramètre base64 invalide ; problème potentiel d'image ou d'injection.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Résolution de l'image inférieure au seuil minimum.
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.	Valeur d'identifiant malformée ou inexistante. Ne se déclenche que lorsque la Détection de Vie ou la Vérification d'identité est incluse dans le flux — non requis pour les flux de Vérification de l'âge uniquement.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Le payload dépasse 800 Ko ; compresser en JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Format non pris en charge ou préfixe base64 invalide.
20062	The useCase field is invalid.	Valeur non reconnue dans le champ useCase.
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.	Paramètre d'image selfie manquant.
20008	The subject.email field is invalid.	Format d'e-mail invalide dans subject.email.
20005	O parâmetro subject.code não foi informado.	Paramètre subject.code manquant. Ne se déclenche que lorsque la Détection de Vie ou la Vérification d'identité est incluse dans le flux — non requis pour les flux de Vérification de l'âge uniquement.
20004	O parâmetro subject não foi informado.	Objet subject manquant.
20003	The request body is missing or invalid.	Payload nul ou malformé.
20002	O parâmetro APIKey não foi informado.	En-tête APIKEY manquant.
20001	O parâmetro authtoken não foi informado.	En-tête du token d'authentification manquant.
10508	The JWT with the captured face has already been used.	Le JWT ne peut être consommé qu'une seule fois.
10507	The JWT with the captured face is expired.	Le JWT dépasse la fenêtre de validité de 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

Code	Message	Description
30017	User does not have permission to perform this action.	JWT malformé ou utilisateur sans permission pour effectuer cette opération.
30017	Jwt header is an invalid JSON.	Le access-token contient des caractères invalides.
10502	O token informado está expirado.	Access-token expiré.
10501	O token informado é inválido.	Token d'authentification invalide.
10201	O AppKey informado é inválido.	APIKEY manquante ou inexistante.

409 Conflict

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

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later.	Erreur de traitement côté serveur.

Étape suivante

• Pour interroger un processus existant, voir Obtenir le processus.