Integra tu backend

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

Markdown

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

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

5. Manejo de fallos

• No reintentes automáticamente un 500 ni un 502 en la creación. Consulta Errores y reintentos.
• 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.