Criar um processoPOST

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

Markdown

POST /v1/processes

Inicia um processo com um dos fluxos e responde com id, state e o resultado em data: o Human Token e a inteligência 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 que você usa.
• Se você enviar um documento, o type dele está no catálogo de atributos.

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.

Flow	Description	Possible result	Integration components required	Example
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_FINISHEDPROCESS_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_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
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_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

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

Requisição

{
  "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
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.

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.

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

{
  "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.
• 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 e o guia de captura da sua plataforma.
• data.ndocs é a inteligência da pessoa. Pode estar ausente: veja Inteligência.

O resultado em data

Um processo finalizado tem estes campos em data. Os fluxos Journey os devolvem quando você lê o processo 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 da pessoa

Um resultado de Journey tem esta aparência:

{
  "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
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

Recusas do fluxo

Quando um fluxo recusa a requisição, a criação responde 4xx com o motivo em message, no envelope 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 antes de adicionar lógica de nova tentativa: uma nova tentativa exige um novo correlationId.

Próximo

Obter um processo