Créez un processus Human Token depuis votre back-end et obtenez le humanToken dans data.humanToken.
Human Token s'exécute sur l'endpoint POST /client/v1/process de l'Human API. Avec les flux API Only (api+humantoken, api+liveness+humantoken et api+liveness+humantoken+revalidation), le processus est créé et finalisé en un seul appel : la réponse contient déjà le résultat dans data.humanToken. Avec les flux Human Token Journey (humantoken et humantoken+revalidation), la réponse contient l'id du processus, un token et le link du parcours, et le résultat est disponible une fois que l'utilisateur a terminé le parcours. Les flux +revalidation nécessitent un tableau references contenant un humanToken obtenu précédemment pour la revalidation.
Flux
Human Token fonctionne selon deux modèles d'intégration :
- API Only — votre back-end envoie le selfie dans
imageBase64. - Human Token Journey — l'utilisateur suit le parcours Unico sur le Web et revient à votre
callbackUri.
| Flow | Capabilities | Possible result | Integration components required | Example |
|---|---|---|---|---|
api+humantoken | Human Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken | LivenessHuman Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
humantoken | LivenessHuman Token | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb | |
humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb |
Endpoint
| Environnement | URL |
|---|---|
| Production | POST https://humantoken.unico.app/client/v1/process |
Requête
| En-tête | Valeur |
|---|---|
x-unico-accesskey | <your_access_key> (voir Authentification) |
Content-Type | application/json |
| Champ | Type | Requis | Description |
|---|---|---|---|
flow | string | oui | Flux Human Token : api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) ou humantoken, humantoken+revalidation (Human Token Journey). Voir Flux. |
imageBase64 | string | API Only | Le selfie, capturé par votre front-end et envoyé directement, en base64. PNG, JPEG ou WebP, jusqu'à 800 Ko. Suivez le Standard de capture. |
callbackUri | string | Human Token Journey | URL vers laquelle l'utilisateur est redirigé à la fin du parcours. |
companyBranchId | string | non | Identifiant de branche. Lorsqu'il est fourni, le processus utilise la configuration de la branche spécifiée. |
references | array | Flux de revalidation | Tableau d'objets de référence. Requis pour les flux +revalidation. Chaque objet contient referenceType (REFERENCE_TYPE_HUMAN_TOKEN) et referenceContent (la valeur du humanToken obtenu précédemment). |
Réponses
| Champ | Type | Description |
|---|---|---|
id | string (UUID) | Identifiant du processus. Utilisez-le pour récupérer à nouveau le processus via Récupérer un processus. |
state | string | État du processus — voir Interpréter le résultat. Uniquement dans les flux API Only. |
token | string | Token du processus créé, vous pouvez l'utiliser pour ouvrir l'expérience Journey SDK. Uniquement dans les flux Human Token Journey (humantoken, humantoken+revalidation). |
link | string | URL de la Human Token Journey : envoyez l'utilisateur vers celle-ci. Uniquement dans les flux Human Token Journey (humantoken, humantoken+revalidation). |
data.humanToken.value | string | Identifiant stable et opaque du visage (jusqu'à 100 caractères). La même personne correspond toujours à la même valeur. Uniquement dans les flux API Only (hors revalidation). |
data.humanTokenMatch | string | "true" si le selfie correspond au humanToken référencé, "false" sinon. Uniquement dans le flux +revalidation API Only. |
state | Signification | Que faire |
|---|---|---|
PROCESS_STATE_FINISHED | data.humanToken.value renseigné : personne réelle, avec un Human Token. | Recherchez value dans vos enregistrements : s'il existe, il s'agit d'un utilisateur récurrent ou d'un doublon possible ; sinon, il s'agit d'une nouvelle personne. |
PROCESS_STATE_FINISHED | Pas de data.humanToken, ou value vide : non concluant. | Considérez-le comme non concluant. Ne stockez ni ne comparez jamais une value vide ; relancez le processus ou rejetez-le, selon vos règles métier. |
PROCESS_STATE_FAILED | Échec du processus d'identification. | Relancez le processus ou rejetez-le, selon vos règles métier. |
PROCESS_STATE_CREATED | Processus créé. | Patientez. Récupérez le résultat plus tard via Récupérer un processus. |
PROCESS_STATE_CANCELED | Le processus a été annulé. | Créez un nouveau processus, si l'utilisateur doit encore être vérifié. |
Vérifiez toujours que data.humanToken.value n'est pas vide avant de l'utiliser.
Codes d'erreur
Le statut HTTP renvoyé lorsque la clé d'accès dans l'en-tête x-unico-accesskey est absente ou invalide est encore en cours de confirmation. Voir Authentification.
- 400 Bad Request
- 403 Forbidden
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Message | Description |
|---|---|---|
3 | invalid flow | Lorsque le flux spécifié n'existe pas. |
3 | INVALID_IMAGE | Lorsque l'image n'est pas un base64 valide ou ressemble à une tentative d'injection. |
3 | IMAGE_TOO_LARGE | Lorsque l'image dépasse la taille maximale de 800 Ko. |
3 | UNSUPPORTED_IMAGE_FORMAT | Lorsque le format de l'image n'est pas PNG, JPEG ou WebP. |
3 | MISSING_IMAGE | Lorsque l'image est requise pour ce flux et n'a pas été envoyée. |
3 | INVALID_REQUEST | Lorsque le corps de la requête est nul ou ne peut pas être interprété. |
9 | monthly process limit of <monthly_limit> reached for this tenant | Lorsque la limite d'utilisation mensuelle a été atteinte. |
9 | PROCESS_FAILED | Lorsque le processus a atteint un échec terminal lors de sa création. |
| Code | Message | Description |
|---|---|---|
7 | PERMISSION_DENIED | Lorsque les identifiants sont valides mais ne donnent pas droit à cette action. |
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 repos (backoff) : Arrêtez ou réduisez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées dans une boucle serrée.
- File d'attente et limitation (Queueing & throttling) : Mettez en mémoire 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 essais (par exemple, 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.
Envoyer continuellement des requêtes vers un endpoint soumis à une limite de débit sans appliquer 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é garantit 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, consultez Limites de débit.
| Code | Message | Description |
|---|---|---|
13 | Internal failure! Try again later | Lorsqu'une erreur interne se produit. |
Pour la liste complète des codes de cet endpoint, consultez la référence Créer un processus de l'Human API.
Prochaines étapes
- Stockez la valeur
humanTokenavec votre enregistrement utilisateur pour reconnaître la même personne lors des appels Human Token ultérieurs. - Pour récupérer à nouveau le processus, à des fins d'audit ou de support, utilisez Récupérer un processus.