Vérification de l'âge

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 -- 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 de l'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 (AAAA-MM-JJ).
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'utilisation de l'opération.
subsidiaryId	string	non	ID de la succursale -- requis uniquement si plusieurs succursales existent.
imageBase64	string	oui	Sortie chiffrée du SDK ou image en base64 (PNG, JPEG, WebP).

Exigences d'image

• Résolution minimale : 640 x 480 (standard HD)
• Taille maximale du fichier : 800 Ko (compression JPEG92 recommandée)
• Les jetons 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. Utilisez-le avec Get Process pour les re-requêtes.
status	integer	3 (terminé avec succès), 5 (erreur). N'utilisez que status = 3 pour les décisions métier. Pour toutes les valeurs possibles, voir Get Process.
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

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.

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.	La résolution de l'image est en dessous du 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 ; compressez 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 (AAAA-MM-JJ).
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 de jeton 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 jeton d'accès contient des caractères invalides.
10502	O token informado está expirado.	Jeton d'accès expiré.
10501	O token informado é inválido.	Jeton 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.

Prochaines étapes

• Pour interroger un processus existant, voir Get Process.