---
title: Crear un proceso
description: POST /v1/processes — los campos comunes, los límites de validación, los campos de cada flujo y la respuesta 201 con el Human Token y la inteligencia.
canonical: https://developer.unico.io/es/human-plugin/api-reference/create-process
locale: es
generated_by: markdown-export
---

# Crear un proceso

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

`POST /v1/processes`

Inicia un proceso con uno de los [flujos](#flows) y responde con `id`, `state` y el resultado en `data`: el Human Token y la [inteligencia](/es/human-plugin/get-started/intelligence) 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](#flows) que usa.
- Si envía un documento, su `type` está en el [catálogo de atributos](/es/human-plugin/additional-resources/attribute-catalog).

<a id="flows"></a>

## 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](/es/human-plugin/api-reference/get-process).

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `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_FINISHED`, `PROCESS_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_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `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_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

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

## Solicitud

```json
{
  "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](#flows) |
| `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](#flow-refusals).

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](/es/human-plugin/api-reference/get-process#finished-and-failed-processes).

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>`.

```json
{
  "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](/es/human-plugin/api-reference/process-lifecycle).
- `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](/es/human-plugin/integrations/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](/es/human-plugin/get-started/intelligence).

<a id="result"></a>

### El resultado en `data`

Un proceso finalizado tiene estos campos en `data`. Los flujos Journey los devuelven cuando usted [lee el proceso](/es/human-plugin/api-reference/get-process) 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](/es/human-plugin/get-started/intelligence) de la persona |

Un resultado de Journey tiene este aspecto:

```json
{
  "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](#flow-refusals) |
| 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 |

<a id="flow-refusals"></a>

### Rechazos del flujo

Cuando un flujo rechaza la solicitud, la creación responde `4xx` con el motivo en `message`, en el [envoltorio](/es/human-plugin/api-reference/errors-and-retries) 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](/es/human-plugin/api-reference/errors-and-retries) antes de añadir lógica de reintento: un nuevo intento necesita un `correlationId` nuevo.

## Siguiente

[Obtener un proceso](/es/human-plugin/api-reference/get-process)