Integre seu backend

O checklist para chamar o Human Plugin a partir de um serviço server-side.

Markdown

O Human Plugin deve ser chamado apenas pelo seu back-end. Não o exponha a navegadores nem a apps mobile: ele não tem autenticação de entrada.

1. Criar

curl

curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

Node.js

const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body é { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;

Defina o timeout do seu cliente para no mínimo 60 segundos: um create pode levar até 30 segundos para ser processado, mais as etapas de banco de dados. O id vem apenas na resposta do create, então um cliente que desiste cedo pode perder um processo que termina.

2. Persista o que você vai precisar depois

Guarde	Porque
id	É a referência para o GET
token e link da Journey, se houver	Retornam apenas na resposta do create e nunca são armazenados pelo Human Plugin
Seu correlationId	Ele deve ser único. Gere um novo a cada tentativa, inclusive em retentativas, exceto após um 503

3. Leia o resultado

1. Se state for PROCESS_STATE_FINISHED, leia o resultado em data: humanToken (ou humanTokenMatch em uma revalidação), liveness e ndocs. Finalizado não é o mesmo que aprovado.
2. Se state for PROCESS_STATE_CREATED, faça polling em GET /v1/processes/{id} com backoff até que ele mude. Nada mais faz o processo avançar.
3. Se state for PROCESS_STATE_FAILED, o processo terminou sem resultado. Inicie um novo, se o seu fluxo permitir.

4. Use a inteligência

data.ndocs mostra o que a pessoa já fez com você: com quantos dos seus clientes e documentos ela foi vista, e quando. Use esse dado na sua decisão junto com o Human Token, e lembre-se de que ele pode estar ausente. Veja Inteligência.

5. Tratamento de falhas

• Não faça retry automático de 500 ou 502 no create. Veja Erros e retentativas.
• Faça retry de 503 no create com o mesmo correlationId, e de qualquer falha no GET, com backoff.
• 409 significa que o correlationId já está em uso. Nunca reutilize um.
• Configure alerta para 503 repetido: significa que o Human Plugin não consegue acessar o banco de dados.

Expectativas operacionais

• Chame o Human Plugin a partir da mesma rede do container. Termine o TLS na frente dele se o caminho cruzar redes não confiáveis.
• Uma instalação do Human Plugin é um limite de isolamento. Clientes, marcas ou ambientes diferentes que não devem compartilhar inteligência precisam de instalações e bancos de dados separados, cada um com a sua própria inteligência.