Inicio rápido

Esta guía integra Zentto KYC en una aplicación backend en cinco pasos: obtener la API key, instalar el SDK, crear el cliente, ejecutar una verificación completa (sesión + documento + liveness + face-match) y consultar el resultado.

Flujo del usuario

Vista funcional del primer recorrido, desde preparar la integración hasta recibir el resultado.

Editable en draw.io: descarga el SVG → en draw.io: File → Import from → Device → selecciona el SVG.

Flujo técnico

Secuencia real verificada contra las rutas Express y el cliente @zentto/kyc-sdk.

URL base

Entorno	URL
Producción	https://kyc.zentto.net
Desarrollo	http://localhost:5100

Todas las rutas tienen el prefijo /v1 directo (no existe prefijo por dominio tipo /v1/kyc/...). El SDK ya las arma por ti.

Paso 1 — Obtener una API key

La verificación server-to-server se autentica con el header X-API-Key: zkyc_.... Cada empresa (tenant) genera su propia key:

• Desde el dashboard de operadores (sección API keys), o
• Vía API con un usuario operador: POST /v1/keys.

La key se muestra una sola vez al crearla. Guárdala en una variable de entorno (KYC_API_KEY) del backend; nunca la expongas en el frontend. Ver Autenticación.

Paso 2 — Instalar el SDK

El paquete @zentto/kyc-sdk es privado (requiere acceso al scope @zentto/*):

npm install @zentto/kyc-sdk

Paso 3 — Crear el cliente

import { ZenttoKyc } from "@zentto/kyc-sdk";

const kyc = new ZenttoKyc({
  apiKey: process.env.KYC_API_KEY, // zkyc_...
  baseUrl: "https://kyc.zentto.net",
});

Paso 4 — Verificación completa

Flujo típico: crear una sesión con las features deseadas, subir el documento de identidad, validar la prueba de vida y comparar el rostro de la selfie contra el del documento. Los uploads pasan al SDK como FileInput ({ data, filename, contentType? }).

import { readFile } from "node:fs/promises";

// 1. Crear la sesión de verificación
const { session } = await kyc.sessions.create({
  features: ["id", "liveness", "face_match", "aml"],
  vendorData: "user-1234",          // tu identificador interno (opcional)
  callbackUrl: "https://miapp.com/kyc/callback",
});

console.log(session.id, session.verificationUrl);

// 2. Verificación del documento de identidad (anverso + reverso)
const idResult = await kyc.documents.idVerification({
  sessionId: session.id,
  frontImage: {
    data: await readFile("./front.jpg"),
    filename: "front.jpg",
    contentType: "image/jpeg",
  },
  backImage: {
    data: await readFile("./back.jpg"),
    filename: "back.jpg",
    contentType: "image/jpeg",
  },
});

// 3. Liveness (prueba de vida) sobre la selfie
await kyc.biometrics.liveness({
  sessionId: session.id,
  image: {
    data: await readFile("./selfie.jpg"),
    filename: "selfie.jpg",
    contentType: "image/jpeg",
  },
});

// 4. Face-match: selfie vs rostro del documento
await kyc.biometrics.faceMatch({
  sessionId: session.id,
  userImage: {
    data: await readFile("./selfie.jpg"),
    filename: "selfie.jpg",
    contentType: "image/jpeg",
  },
  refImage: {
    data: await readFile("./front.jpg"),
    filename: "front.jpg",
    contentType: "image/jpeg",
  },
});

Cada subida que incluya sessionId consolida su resultado en la sesión y recalcula la decisión global. Un hit AML nunca auto-aprueba: la sesión queda en in_review para decisión manual del operador.

Paso 5 — Consultar el resultado

Puedes recibir el resultado por webhook firmado (recomendado, ver Webhooks) o por polling:

const { session } = await kyc.sessions.get(session.id);
console.log(session.status); // approved | in_review | declined | ...

Equivalente con curl

Mismo flujo usando el header X-API-Key:

# 1. Crear sesión
curl -X POST https://kyc.zentto.net/v1/sessions \
  -H "X-API-Key: $KYC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"features":["id","liveness","face_match","aml"],"vendorData":"user-1234"}'

# 2. Verificación de documento (multipart)
curl -X POST https://kyc.zentto.net/v1/documents/id-verification \
  -H "X-API-Key: $KYC_API_KEY" \
  -F "front_image=@./front.jpg" \
  -F "back_image=@./back.jpg" \
  -F "sessionId=<SESSION_ID>"

# 3. Liveness
curl -X POST https://kyc.zentto.net/v1/biometrics/liveness \
  -H "X-API-Key: $KYC_API_KEY" \
  -F "image=@./selfie.jpg" \
  -F "sessionId=<SESSION_ID>"

# 4. Face-match
curl -X POST https://kyc.zentto.net/v1/biometrics/face-match \
  -H "X-API-Key: $KYC_API_KEY" \
  -F "user_image=@./selfie.jpg" \
  -F "ref_image=@./front.jpg" \
  -F "sessionId=<SESSION_ID>"

# 5. Consultar resultado
curl https://kyc.zentto.net/v1/sessions/<SESSION_ID> \
  -H "X-API-Key: $KYC_API_KEY"

Migración desde Didit

Zentto KYC replica el modelo de Didit (sesiones, documentos, biometría, AML, KYB, webhooks firmados). Equivalencias principales:

Concepto Didit	Zentto KYC
API key del dashboard	API key zkyc_... (X-API-Key)
Workflow / verification flow	Workflow (POST /v1/sessions/workflows) + workflowId al crear sesión
Crear verification session	POST /v1/sessions
Estados de la sesión	not_started · in_progress · pending · in_review · approved · declined · abandoned
ID document verification	POST /v1/documents/id-verification
Liveness / Face match	POST /v1/biometrics/liveness · POST /v1/biometrics/face-match
AML screening	POST /v1/aml/screen
KYB (business verification)	POST /v1/kyb
Reusable KYC	POST /v1/sessions/:id/share + POST /v1/sessions/import
Webhooks firmados	POST /v1/webhooks con firma HMAC-SHA256 (X-Zentto-Signature)
SDK / API client	@zentto/kyc-sdk

Diferencia clave frente a Didit: el servicio es self-hosted; los documentos y datos biométricos se procesan en la infraestructura donde despliegues Zentto KYC, sin depender de una API biométrica de terceros por cada verificación.