---
title: Criar um processo
description: POST /v1/processes — os campos comuns, os limites de validação, os campos dos fluxos e a resposta 201 com o Human Token e a inteligência.
canonical: https://developer.unico.io/pt-BR/human-plugin/api-reference/create-process
locale: pt-BR
generated_by: markdown-export
---

# Criar um processo

Inicie um processo e obtenha o Human Token e a inteligência da pessoa.

`POST /v1/processes`

Inicia um processo com um dos [fluxos](#flows) e responde com `id`, `state` e o resultado em `data`: o Human Token e a [inteligência](/pt-BR/human-plugin/get-started/intelligence) da pessoa, `data.ndocs`.

## Antes de chamar

- O Human Plugin está em execução e `GET /health/ready` responde `200`.
- Sua chave de acesso está habilitada para o [fluxo](#flows) que você usa.
- Se você enviar um documento, o `type` dele está no [catálogo de atributos](/pt-BR/human-plugin/additional-resources/attribute-catalog).

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

## Fluxos

O campo `flow` escolhe o que o processo faz. O Human Plugin executa estes fluxos, em dois modelos de integração:

- **API Only**: seu back-end envia a selfie em `imageBase64`, e a criação responde com o resultado.
- **Human Token Journey**: a pessoa tira a selfie na jornada de captura e retorna ao seu `callbackUri`. A criação responde com um `token` e um `link`, e você lê o resultado com [Obter um processo](/pt-BR/human-plugin/api-reference/get-process).

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | Recebe uma selfie pelo seu back-end e gera o Human Token, um identificador facial único. A resposta é final: sem captura, sem segunda chamada. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | Captura uma selfie na jornada de captura, com verificação de prova de vida, e gera o Human Token. A criação retorna o `token` e o `link`; leia o resultado quando a captura terminar. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | Captura uma selfie e compara o rosto com o Human Token esperado. Retorna se é a mesma pessoa ou não, por exemplo antes de uma ação sensível. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`, `correlationId` e `credential` são iguais em todos os fluxos.

## Requisição

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

### Campos comuns

| Campo | Obrigatório | Limite (bytes) | Observações |
| --- | --- | --- | --- |
| `flow` | Sim | 64 | Um dos [fluxos](#flows) |
| `clientId` | Sim | 128 | Seu id para o cliente. A inteligência conta valores distintos |
| `correlationId` | Sim | 128 | Sua referência para este processo. **Único**: um que outro processo já tenha, em qualquer estado, é recusado com `409` |
| `credential` | Sim, mas pode ser vazio | | A chave deve estar presente. Veja abaixo |
| `credential.type` | Com documento | | Um código do catálogo de atributos, exato e com diferenciação de maiúsculas e minúsculas |
| `credential.value` | Com documento | 64 | O número do documento |

`flow`, `clientId` e `correlationId` devem ser strings, sem caracteres de controle e sem espaços no início ou no fim. Valores inválidos são rejeitados, nunca reescritos.

### O campo `credential`

- **Com documento:** um objeto com exatamente `type` e `value`, ambos strings, enviados juntos.
- **Sem documento:** `null` ou `{}`. O processo ainda conta como uma transação e como um cliente na inteligência.
- **Omitido, ou um objeto com strings vazias:** rejeitado com `400 MISSING_CREDENTIAL_TYPE`. Isso detecta uma chave com erro de grafia antes de qualquer processamento.
- Qualquer outra chave dentro de `credential` é rejeitada.

### Campos dos fluxos

O que cada fluxo acrescenta aos campos comuns:

| Campo | Fluxo | Obrigatório | Valor |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | Sim | A selfie em base64. PNG, JPEG ou WebP, até 800 KB |
| `callbackUri` | `humantoken`, `humantoken+revalidation` | Sim | Para onde a pessoa retorna quando a captura termina: uma página sua, ou o URL scheme do seu app |
| `references` | `humantoken+revalidation` | Sim | Um item com o Human Token esperado, como no exemplo acima |

O Human Plugin não armazena esses campos, e um campo opcional com erro de grafia pode ser ignorado sem erro.

Use com `api+humantoken` uma selfie frontal, bem iluminada, de um único rosto. Um valor que não seja imagem é recusado, e o processo é armazenado como falho: veja [Recusas do fluxo](#flow-refusals).

Com `humantoken+revalidation`, o resultado tem `humanTokenMatch` em vez de `humanToken`:

- `"true"`: é a mesma pessoa. O processo conta para essa pessoa, e `ndocs` a descreve.
- Qualquer outro valor, ou uma captura que não seja de uma pessoa viva: não está confirmado. O processo não conta para ninguém, e não há `ndocs`.

`PROCESS_STATE_FINISHED` é devolvido nos dois casos: leia `humanTokenMatch`. Veja [Obter um processo](/pt-BR/human-plugin/api-reference/get-process#finished-and-failed-processes).

Alguns nomes são reservados pelo Human Plugin e recusados com `400 INVALID_REQUEST`, como `clientReference`. O mesmo vale para outra grafia dos campos do próprio Human Plugin, como `client_id`, `correlation_id` ou `Flow`: apenas `flow`, `clientId`, `correlationId` e `credential` são lidos, grafados exatamente assim.

### Regras do corpo

- Um objeto JSON, de no máximo **2 MiB** (o suficiente para uma selfie em base64). Um corpo maior é recusado com `400 REQUEST_TOO_LARGE`.
- Nada pode vir depois do objeto JSON.

## Resposta

`201 Created`, com `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` é o UUID do Human Plugin. Cada requisição aceita cria um novo.
- `state` é o status local. Veja o [ciclo de vida](/pt-BR/human-plugin/api-reference/process-lifecycle).
- `humantoken` e `humantoken+revalidation` respondem `PROCESS_STATE_CREATED` com um `token` e um `link`. Eles são devolvidos **uma única vez** e nunca são armazenados: guarde-os. Veja [Human Token Journey](/pt-BR/human-plugin/integrations/human-token-journey) e o guia de captura da sua plataforma.
- `data.ndocs` é a inteligência da pessoa. Pode estar ausente: veja [Inteligência](/pt-BR/human-plugin/get-started/intelligence).

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

### O resultado em `data`

Um processo finalizado tem estes campos em `data`. Os fluxos Journey os devolvem quando você [lê o processo](/pt-BR/human-plugin/api-reference/get-process) depois da captura.

| Campo | Quando | Valor |
| --- | --- | --- |
| `humanToken` | `api+humantoken`, `humantoken` | Quem é a pessoa: `value` é o Human Token, e `status` é `validated` quando ele foi gerado |
| `humanTokenMatch` | `humantoken+revalidation` | `"true"` quando é a mesma pessoa do Human Token em `references` |
| `liveness` | Fluxos que verificam a prova de vida, como os fluxos Journey | `value` é `live` quando a captura veio de uma pessoa viva, ou `not_live` quando não veio; `status` é `validated` quando a verificação foi executada |
| `ndocs` | Quando há inteligência para a pessoa | A [inteligência](/pt-BR/human-plugin/get-started/intelligence) da pessoa |

Um resultado de Journey tem esta aparência:

```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": [] }
  }
}
```

Verifique `liveness` antes de confiar no resultado: com `not_live`, trate a captura como falha e peça à pessoa que tente novamente. Um processo com `not_live` não conta para a inteligência de ninguém.

## Erros

| Status | `message` | Significado |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | Não é um único objeto JSON, campo reservado, tipo incorreto ou corpo acima de 2 MiB |
| 400 | `MISSING_<FIELD>`, `INVALID_<FIELD>` | Um campo obrigatório está ausente ou malformado, como `MISSING_CLIENT_ID` |
| 401 | Vazio (`""`) | A Unico recusou sua chave de acesso: ausente, incorreta ou não mais válida. O processo é armazenado como falho. Verifique `HUMAN_API_ACCESS_KEY` |
| 409 | `CORRELATION_ID_ALREADY_USED` | Outro processo já tem o `correlationId`. Nada é armazenado nem enviado |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` não está no catálogo. Nada é armazenado nem enviado |
| 4xx | O `message` do fluxo | O fluxo recusou a requisição, por exemplo por uma imagem inválida. Veja [Recusas do fluxo](#flow-refusals) |
| 502 | `UPSTREAM_UNAVAILABLE` | Não foi possível confirmar o processo a tempo |
| 503 | `DATABASE_UNAVAILABLE` | O banco de dados falhou. Nada foi processado |
| 500 | `INTERNAL` | Erro inesperado |

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

### Recusas do fluxo

Quando um fluxo recusa a requisição, a criação responde `4xx` com o motivo em `message`, no [envelope](/pt-BR/human-plugin/api-reference/errors-and-retries) habitual. Os mais comuns:

| `message` | Causa |
| --- | --- |
| `invalid flow` | `flow` não é um fluxo habilitado para a sua conta |
| `INVALID_IMAGE` (`400`) | `api+humantoken` sem `imageBase64` |
| `INVALID_REQUEST` (`400`) | `imageBase64` não é uma imagem em base64 |
| `IMAGE_TOO_LARGE` | A imagem tem mais de 800 KB |
| `UNSUPPORTED_IMAGE_FORMAT` | A imagem não é PNG, JPEG nem WebP |
| `PERMISSION_DENIED` (`403`) | Sua chave de acesso não está habilitada para este fluxo |

Um processo recusado é armazenado como falho. Corrija a requisição e crie um novo processo com um novo `correlationId`.

Leia [Erros e novas tentativas](/pt-BR/human-plugin/api-reference/errors-and-retries) antes de adicionar lógica de nova tentativa: uma nova tentativa exige um novo `correlationId`.

## Próximo

[Obter um processo](/pt-BR/human-plugin/api-reference/get-process)