---
title: Integra tu backend
description: 'Cómo debe llamar un servicio de backend a Human Plugin: qué almacenar, cómo hacer polling, cómo leer el resultado y cómo manejar los fallos.'
canonical: https://developer.unico.io/es/human-plugin/integrations/backend
locale: es
generated_by: markdown-export
---

# Integra tu backend

La lista de verificación para llamar a Human Plugin desde un servicio del lado del servidor.

Human Plugin está pensado para ser llamado únicamente por tu backend. No lo expongas a navegadores ni a aplicaciones móviles: no tiene autenticación de entrada.

## 1. Crear

### 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 is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;
```

Configura el timeout de tu cliente en **al menos 60 segundos**: una creación puede tardar hasta 30 segundos en procesarse, más los pasos de base de datos. El `id` llega solo en la respuesta de la creación, por lo que un cliente que se rinda antes de tiempo puede perder un proceso que sí termina.

## 2. Persiste lo que necesitarás después

| Guarda | Porque |
| --- | --- |
| `id` | Es el identificador para el `GET` |
| El `token` y el `link` del Journey, si los hay | Se devuelven solo en la respuesta de la creación y Human Plugin nunca los almacena |
| Tu `correlationId` | Debe ser único. Genera uno nuevo para cada intento, reintentos incluidos, salvo tras un `503` |

## 3. Lee el resultado

1. Si `state` es `PROCESS_STATE_FINISHED`, lee el resultado en `data`: `humanToken` (o `humanTokenMatch` en una revalidación), `liveness` y `ndocs`. Finalizado no es lo mismo que aprobado.
2. Si `state` es `PROCESS_STATE_CREATED`, haz polling a `GET /v1/processes/{id}` con backoff hasta que cambie. Nada más hace avanzar el proceso.
3. Si `state` es `PROCESS_STATE_FAILED`, el proceso terminó sin resultado. Inicia uno nuevo si tu flujo lo permite.

## 4. Usa la inteligencia

`data.ndocs` te indica lo que la persona ha hecho con tu organización: con cuántos de tus clientes y documentos se la vio, y cuándo. Úsalo en tu decisión junto con el Human Token, y recuerda que puede estar ausente. Consulta [Inteligencia](/es/human-plugin/get-started/intelligence).

## 5. Manejo de fallos

- No reintentes automáticamente un `500` ni un `502` en la creación. Consulta [Errores y reintentos](/es/human-plugin/api-reference/errors-and-retries).
- Reintenta un `503` en la creación con el mismo `correlationId`, y cualquier fallo en el `GET`, con backoff.
- `409` significa que el `correlationId` ya está en uso. Nunca reutilices uno.
- Genera una alerta ante `503` repetidos: significa que Human Plugin no puede conectarse a su base de datos.

## Expectativas operativas

- Llama a Human Plugin desde la misma red que el contenedor. Termina TLS delante de él si la ruta atraviesa redes no confiables.
- Una instalación de Human Plugin es un límite de aislamiento. Los clientes, marcas o entornos que no deban compartir inteligencia necesitan instalaciones y bases de datos separadas, cada una con su propia inteligencia.