---
title: Integre seu backend
description: Como um serviço de back-end deve chamar o Human Plugin — o que armazenar, como fazer polling, como ler o resultado e como tratar falhas.
canonical: https://developer.unico.io/pt-BR/human-plugin/integrations/backend
locale: pt-BR
generated_by: markdown-export
---

# Integre seu backend

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

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

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

```javascript
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](/pt-BR/human-plugin/get-started/intelligence).

## 5. Tratamento de falhas

- Não faça retry automático de `500` ou `502` no create. Veja [Erros e retentativas](/pt-BR/human-plugin/api-reference/errors-and-retries).
- 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.