API — Documentos

Los endpoints de documentos cruzan el documento de identidad del usuario por OCR (y MRZ cuando aplica) y lo consolidan en la sesión. Requieren API key (X-API-Key: zkyc_...).

Prefijo: /v1/documents. La verificación de identidad y el comprobante de domicilio usan multipart/form-data; la validación contra bases de datos usa JSON.

Endpoints

Método	Ruta	Auth	Cuerpo	Descripción
POST	/v1/documents/id-verification	API key	multipart	OCR + MRZ del documento de identidad
POST	/v1/documents/poa	API key	multipart	Comprobante de domicilio (próximamente)
POST	/v1/documents/database-validation	API key	JSON	Validación contra bases gubernamentales

Verificación de identidad

POST /v1/documents/id-verification
X-API-Key: zkyc_...
Content-Type: multipart/form-data

Campo	Tipo	Requerido	Descripción
front_image	archivo	Sí	Anverso del documento
back_image	archivo	No	Reverso del documento
sessionId	texto	No	Sesión a la que consolidar el resultado

Respuesta:

{
  "ok": true,
  "result": {
    "idStatus": "approved",
    "mrzValid": true,
    "fullName": "JOHN DOE",
    "documentType": "passport",
    "documentNumber": "X1234567",
    "dateOfBirth": "1990-05-12",
    "nationality": "USA",
    "expirationDate": "2030-05-11",
    "confidence": 0.97
  }
}

idStatus	Significado
approved	OCR correcto y MRZ válido (o sin MRZ)
in_review	Baja confianza o MRZ inválido → revisión manual
declined	Documento ilegible

Este endpoint no decide la aprobación final de la sesión: escribe id_status y la decisión global se recalcula a partir de todas las features. Si se envía sessionId, el resultado se consolida y se reevalúa la sesión.

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=9b1c0e2a-..."

const res = await kyc.documents.idVerification({
  sessionId: "9b1c0e2a-...",
  frontImage: { data: frontBuf, filename: "front.jpg", contentType: "image/jpeg" },
  backImage: { data: backBuf, filename: "back.jpg", contentType: "image/jpeg" },
});
console.log(res.result.idStatus);

Si falta front_image, la API responde 400 missing_file.

Comprobante de domicilio (próximamente)

POST /v1/documents/poa
X-API-Key: zkyc_...
Content-Type: multipart/form-data

Campo	Tipo	Requerido
document	archivo	Sí
sessionId	texto	No

Actualmente responde 501 not_implemented: el microservicio de inferencia aún no expone OCR de comprobantes de domicilio. La firma del SDK (kyc.documents.proofOfAddress) ya existe y queda lista para cuando se habilite.

{ "ok": false, "error": "not_implemented" }

Validación contra bases de datos

Cruza la identidad contra bases gubernamentales / registros civiles mediante un proveedor país-específico (patrón adaptador). Por defecto, sin proveedor configurado para el país, el status es unsupported.

POST /v1/documents/database-validation
X-API-Key: zkyc_...
Content-Type: application/json

{
  "issuingState": "us",
  "validationType": "identity",
  "fullName": "John Doe",
  "dateOfBirth": "1990-05-12",
  "documentNumber": "X1234567"
}

Campo	Tipo	Descripción
issuingState	string 2–8	País emisor (ISO 3166-1 alpha-2)
validationType	string 1–60	Tipo de validación
fullName	string 2–200	Nombre completo
dateOfBirth	string	Fecha de nacimiento
documentNumber	string 1–80	Número de documento

Respuesta:

{ "ok": true, "provider": "null", "result": { "status": "unsupported" } }

El campo provider indica el adaptador resuelto para el país. Si no hay adaptador, provider es el proveedor por defecto y result.status es unsupported.

const res = await kyc.documents.databaseValidation({
  issuingState: "us",
  validationType: "identity",
  fullName: "John Doe",
  dateOfBirth: "1990-05-12",
  documentNumber: "X1234567",
});

Flujo del usuario

Vista no técnica: el usuario sube su documento y el sistema lo valida automáticamente.

Editable en draw.io: descarga el SVG → en draw.io: File → Import from → Device → selecciona el SVG. Cada nodo queda editable.

Flujo técnico

Vista técnica: POST multipart → inferencia OCR+MRZ (PaddleOCR) → resultado → actualiza sesión.

Componente	Tipo	Ubicación
POST /v1/documents/id-verification	Route Express (multipart)	src/documents/routes.ts
POST /v1/documents/poa	Route Express (próximamente)	src/documents/routes.ts
POST /v1/documents/database-validation	Route Express (JSON)	src/documents/routes.ts
src/documents/adapters/	Patrón adaptador por país	src/documents/adapters/
POST /v1/ocr	Inferencia OCR (FastAPI :5200)	inference/app/routers/ocr.py
inference/app/models/ocr.py	Modelo PaddleOCR	inference/app/models/ocr.py
sessions	Tabla (UPSERT por sessionId)	src/db/migrations/
session_results	Tabla resultados (id_status, mrz_valid)	src/db/migrations/

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