Crear un procesoPOST

Inicie un proceso y obtenga el Human Token y la inteligencia de la persona.

Markdown

POST /v1/processes

Inicia un proceso con uno de los flujos y responde con id, state y el resultado en data: el Human Token y la inteligencia de la persona, data.ndocs.

Antes de llamar

• Human Plugin está en ejecución y GET /health/ready responde 200.
• Su clave de acceso está habilitada para el flujo que usa.
• Si envía un documento, su type está en el catálogo de atributos.

Flujos

El campo flow elige lo que hace el proceso. Human Plugin ejecuta estos flujos, en dos modelos de integración:

• API Only: su back-end envía la selfie en imageBase64 y la creación responde con el resultado.
• Human Token Journey: la persona toma la selfie en el journey de captura y regresa a su callbackUri. La creación responde con un token y un link, y usted lee el resultado con Obtener un proceso.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	Recibe una selfie a través de su back-end y genera el Human Token, un identificador facial único. La respuesta es final: sin captura, sin segunda llamada.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	Captura una selfie en el journey de captura, con una verificación de Detección de Vida, y genera el Human Token. La creación devuelve el `token` y el `link`; lea el resultado cuando termine la captura.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	Captura una selfie y compara el rostro con el Human Token que usted espera. Devuelve si es la misma persona o no, por ejemplo antes de una acción sensible.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId y credential son iguales en todos los flujos.

Solicitud

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

Campos comunes

Campo	Obligatorio	Límite (bytes)	Notas
flow	Sí	64	Uno de los flujos
clientId	Sí	128	Su id para el cliente. La inteligencia cuenta valores distintos
correlationId	Sí	128	Su referencia para este proceso. Único: uno que otro proceso ya tenga, sea cual sea su estado, se rechaza con 409
credential	Sí, pero puede estar vacío		La clave debe estar presente. Vea más abajo
credential.type	Con un documento		Un código del catálogo de atributos, exacto y sensible a mayúsculas y minúsculas
credential.value	Con un documento	64	El número del documento

flow, clientId y correlationId deben ser cadenas, sin caracteres de control y sin espacios al inicio ni al final. Los valores inválidos se rechazan, nunca se reescriben.

El campo credential

• Con un documento: un objeto con exactamente type y value, ambos cadenas, enviados juntos.
• Sin un documento: null o {}. El proceso sigue contando como una transacción y como un cliente en la inteligencia.
• Omitido, o un objeto con cadenas vacías: se rechaza con 400 MISSING_CREDENTIAL_TYPE. Esto detecta una clave mal escrita antes de procesar nada.
• Cualquier otra clave dentro de credential se rechaza.

Campos de cada flujo

Lo que cada flujo añade a los campos comunes:

Campo	Flujo	Obligatorio	Valor
imageBase64	api+humantoken	Sí	La selfie en base64. PNG, JPEG o WebP, de hasta 800 KB
callbackUri	humantoken, humantoken+revalidation	Sí	Adonde regresa la persona cuando termina la captura: una página suya, o el esquema de URL de su app
references	humantoken+revalidation	Sí	Un elemento con el Human Token que usted espera, como en el ejemplo anterior

Human Plugin no almacena estos campos, y un campo opcional mal escrito puede ignorarse sin error.

Use una selfie frontal y bien iluminada de un solo rostro con api+humantoken. Un valor que no es una imagen se rechaza y el proceso se almacena como fallido: consulte Rechazos del flujo.

Con humantoken+revalidation, el resultado trae humanTokenMatch en lugar de humanToken:

• "true": es la misma persona. El proceso cuenta para esa persona y ndocs la describe.
• Cualquier otro valor, o una captura que no es viva: no está confirmado. El proceso no cuenta para nadie y no hay ndocs.

Se responde PROCESS_STATE_FINISHED en ambos casos: lea humanTokenMatch. Consulte Obtener un proceso.

Human Plugin reserva algunos nombres y los rechaza con 400 INVALID_REQUEST, como clientReference. Lo mismo ocurre con otra grafía de los campos propios de Human Plugin, como client_id, correlation_id o Flow: solo se leen flow, clientId, correlationId y credential, escritos exactamente así.

Reglas del cuerpo

• Un objeto JSON, de 2 MiB como máximo (aproximadamente lo suficiente para una selfie en base64). Un cuerpo mayor se rechaza con 400 REQUEST_TOO_LARGE.
• Nada puede seguir al objeto JSON.

Respuesta

201 Created, con Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id es el UUID de Human Plugin. Cada solicitud aceptada crea uno nuevo.
• state es el estado local. Consulte el ciclo de vida.
• humantoken y humantoken+revalidation responden PROCESS_STATE_CREATED con un token y un link. Se devuelven una sola vez y nunca se almacenan: guárdelos. Consulte Human Token Journey y la guía de captura de su plataforma.
• data.ndocs es la inteligencia de la persona. Puede estar ausente: consulte Inteligencia.

El resultado en data

Un proceso finalizado tiene estos campos en data. Los flujos Journey los devuelven cuando usted lee el proceso después de la captura.

Campo	Cuándo	Valor
humanToken	api+humantoken, humantoken	Quién es la persona: value es el Human Token y status es validated cuando se generó
humanTokenMatch	humantoken+revalidation	"true" cuando es la misma persona que el Human Token de references
liveness	Flujos que verifican la vida, como los flujos Journey	value es live cuando la captura provino de una persona viva, o not_live cuando no; status es validated cuando se ejecutó la verificación
ndocs	Cuando hay inteligencia para la persona	La inteligencia de la persona

Un resultado de Journey tiene este aspecto:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

Revise liveness antes de confiar en el resultado: con not_live, trate la captura como fallida y pida a la persona que lo intente de nuevo. Un proceso con not_live no cuenta para la inteligencia de nadie.

Errores

Estado	message	Significado
400	INVALID_REQUEST, REQUEST_TOO_LARGE	No es un objeto JSON, un campo reservado, un tipo incorrecto, o un cuerpo superior a 2 MiB
400	MISSING_<FIELD>, INVALID_<FIELD>	Falta un campo obligatorio o está mal formado, como MISSING_CLIENT_ID
401	Vacío ("")	Unico rechazó su clave de acceso: falta, es incorrecta o ya no es válida. El proceso se almacena como fallido. Revise HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	Otro proceso ya tiene el correlationId. No se almacena ni se envía nada
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type no está en el catálogo. No se almacena ni se envía nada
4xx	El message del flujo	El flujo rechazó la solicitud, por ejemplo por una imagen inválida. Consulte Rechazos del flujo
502	UPSTREAM_UNAVAILABLE	No se pudo confirmar el proceso a tiempo
503	DATABASE_UNAVAILABLE	Falló la base de datos. No se procesó nada
500	INTERNAL	Error inesperado

Rechazos del flujo

Cuando un flujo rechaza la solicitud, la creación responde 4xx con el motivo en message, en el envoltorio habitual. Los más comunes:

message	Causa
invalid flow	flow no es un flujo habilitado para su cuenta
INVALID_IMAGE (400)	api+humantoken sin imageBase64
INVALID_REQUEST (400)	imageBase64 no es una imagen en base64
IMAGE_TOO_LARGE	La imagen supera los 800 KB
UNSUPPORTED_IMAGE_FORMAT	La imagen no es PNG, JPEG ni WebP
PERMISSION_DENIED (403)	Su clave de acceso no está habilitada para este flujo

Un proceso rechazado se almacena como fallido. Corrija la solicitud y cree un nuevo proceso con un correlationId nuevo.

Lea Errores y reintentos antes de añadir lógica de reintento: un nuevo intento necesita un correlationId nuevo.

Siguiente

Obtener un proceso