Crea un proceso de Human Token desde tu backend y obtén el humanToken en data.humanToken.
Human Token se ejecuta en el endpoint POST /client/v1/process de la Human API. Con los flujos API Only (api+humantoken, api+liveness+humantoken y api+liveness+humantoken+revalidation), el proceso se crea y se finaliza en una sola llamada: la respuesta ya trae el resultado en data.humanToken. Con los flujos Human Token Journey (humantoken y humantoken+revalidation), la respuesta trae el id del proceso, un token y el link de la jornada, y el resultado está disponible después de que el usuario completa la jornada. Los flujos +revalidation requieren un array references con un humanToken obtenido previamente para revalidación.
Flujos
Human Token funciona en dos modelos de integración:
- API Only — tu backend envía el selfie en
imageBase64. - Human Token Journey — el usuario recorre la jornada de Unico en la Web y regresa a tu
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
| Entorno | URL |
|---|---|
| Producción | POST https://humantoken.unico.app/client/v1/process |
Solicitud
| Header | Valor |
|---|---|
x-unico-accesskey | <your_access_key> (ver Autenticación) |
Content-Type | application/json |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
flow | string | sí | Flujo de Human Token: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) o humantoken, humantoken+revalidation (Human Token Journey). Ver Flujos. |
imageBase64 | string | API Only | El selfie, capturado por tu frontend y enviado directamente, en base64. PNG, JPEG o WebP, de hasta 800 KB. Sigue el Estándar de captura. |
callbackUri | string | Human Token Journey | URL a la que se redirige al usuario cuando finaliza la jornada. |
companyBranchId | string | no | Identificador de branch. Cuando se proporciona, el proceso utiliza la configuración del branch especificado. |
references | array | Flujos de revalidación | Array de objetos de referencia. Requerido para flujos +revalidation. Cada objeto tiene referenceType (REFERENCE_TYPE_HUMAN_TOKEN) y referenceContent (el valor del humanToken obtenido previamente). |
Respuestas
| Campo | Tipo | Descripción |
|---|---|---|
id | string (UUID) | Identificador del proceso. Úsalo para consultar el proceso nuevamente con Obtener Proceso. |
state | string | Estado del proceso — ver Interpretar el resultado. Solo en los flujos API Only. |
token | string | Token del proceso creado, puede usarlo para abrir la experiencia del Journey SDK. Solo en los flujos Human Token Journey (humantoken, humantoken+revalidation). |
link | string | URL de la Human Token Journey: envía al usuario a ella. Solo en los flujos Human Token Journey (humantoken, humantoken+revalidation). |
data.humanToken.value | string | Identificador estable y opaco del rostro (hasta 100 caracteres). La misma persona siempre resuelve al mismo valor. Solo en los flujos API Only (sin revalidación). |
data.humanTokenMatch | string | "true" si el selfie coincide con el humanToken referenciado, "false" en caso contrario. Solo en el flujo +revalidation API Only. |
state | Significado | Qué hacer |
|---|---|---|
PROCESS_STATE_FINISHED | data.humanToken.value con valor: persona real, con Human Token. | Busca el value en tus registros: si existe, es un usuario recurrente o un posible duplicado; si no, es una persona nueva. |
PROCESS_STATE_FINISHED | Sin data.humanToken, o con value vacío: no concluyente. | Trátalo como no concluyente. Nunca almacenes ni compares un value vacío; reintenta el proceso o recházalo, según tus reglas de negocio. |
PROCESS_STATE_FAILED | Falló el proceso de identificación. | Reintenta el proceso o recházalo, según tus reglas de negocio. |
PROCESS_STATE_CREATED | Proceso creado. | Espera. Consulta el resultado más tarde con Obtener Proceso. |
PROCESS_STATE_CANCELED | El proceso fue cancelado. | Crea un nuevo proceso, si el usuario aún necesita ser verificado. |
Verifica siempre que data.humanToken.value no esté vacío antes de usarlo.
Códigos de Error
El status HTTP que se devuelve cuando la clave de acceso en el header x-unico-accesskey está ausente o es inválida aún se está confirmando. Ver Autenticación.
- 400 Bad Request
- 403 Forbidden
- 429 Too Many Requests
- 500 Internal Server Error
| Código | Mensaje | Descripción |
|---|---|---|
3 | invalid flow | Cuando el flujo especificado no existe. |
3 | INVALID_IMAGE | Cuando la imagen no es un base64 válido o parece un intento de inyección. |
3 | IMAGE_TOO_LARGE | Cuando la imagen supera el tamaño máximo de 800 KB. |
3 | UNSUPPORTED_IMAGE_FORMAT | Cuando el formato de la imagen no es PNG, JPEG ni WebP. |
3 | MISSING_IMAGE | Cuando la imagen es obligatoria para este flujo y no se envió. |
3 | INVALID_REQUEST | Cuando el cuerpo de la solicitud es nulo o no se puede interpretar. |
9 | monthly process limit of <monthly_limit> reached for this tenant | Cuando se ha alcanzado el límite de uso mensual. |
9 | PROCESS_FAILED | Cuando el proceso alcanzó un fallo terminal durante su creación. |
| Código | Mensaje | Descripción |
|---|---|---|
7 | PERMISSION_DENIED | Cuando las credenciales son válidas pero no tienen permiso para esta acción. |
Se alcanzó el límite de tasa. Cuando su sistema recibe un error HTTP 429, debe implementar mecanismos para prevenir fallos en cascada y evitar empeorar la restricción.
Mejores prácticas:
- Período de enfriamiento (backoff): Detenga o reduzca inmediatamente las solicitudes posteriores de su sistema. No reintente continuamente las solicitudes fallidas en un bucle cerrado.
- Cola y limitación (Queueing & throttling): Almacene en búfer o ponga en cola las solicitudes salientes de su lado para controlar el flujo de tráfico antes de reenviarlas.
- Backoff exponencial con jitter: Al reintentar, aumente el tiempo de espera exponencialmente entre intentos (por ejemplo, 1 s, 2 s, 4 s, 8 s) y agregue un pequeño retraso aleatorio ("jitter") para evitar un efecto de manada donde todas las solicitudes en cola reintentan en el mismo milisegundo exacto.
Enviar solicitudes continuamente a un endpoint con límite de tasa sin aplicar backoff puede prolongar el período de restricción e impactar gravemente el rendimiento operativo de su sistema. Limitar adecuadamente las solicitudes de su lado garantiza una integración más fluida y resiliente.
Para conocer los límites predeterminados, aumentar solicitudes y obtener detalles adicionales, consulte Límites de tasa.
| Código | Mensaje | Descripción |
|---|---|---|
13 | Internal failure! Try again later | Cuando ocurre un error interno. |
Para ver la lista completa de códigos de este endpoint, consulta la referencia Crear Proceso de la Human API.
Qué sigue
- Almacena el valor de
humanTokenjunto al registro del usuario para reconocer a la misma persona en llamadas posteriores a Human Token. - Para consultar el proceso nuevamente, con fines de auditoría o soporte, usa Obtener Proceso.