API — KYB

El módulo KYB (Know Your Business) verifica empresas: lanza un check con los datos de la empresa y consulta su resultado. Requiere API key (X-API-Key: zkyc_...).

Prefijo: /v1/kyb.

Endpoints

Método	Ruta	Auth	Descripción
POST	/v1/kyb	API key	Lanzar verificación KYB
GET	/v1/kyb	API key	Listar checks KYB
GET	/v1/kyb/:id	API key	Detalle de un check

Lanzar verificación

POST /v1/kyb
X-API-Key: zkyc_...
Content-Type: application/json

{
  "companyName": "Acme Inc",
  "registrationNumber": "12345678",
  "country": "us"
}

Campo	Tipo	Requerido	Descripción
companyName	string 1–255	Sí	Razón social
registrationNumber	string 1–120	No	Número de registro mercantil
country	string 2–8	Sí	País (ISO 3166-1 alpha-2; se normaliza a minúsculas)

Respuesta 201 Created:

{
  "ok": true,
  "check": {
    "id": "a1b2c3d4-...",
    "companyName": "Acme Inc",
    "registrationNumber": "12345678",
    "country": "us",
    "status": "pending"
  }
}

curl -X POST https://kyc.zentto.net/v1/kyb \
  -H "X-API-Key: $KYC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyName":"Acme Inc","registrationNumber":"12345678","country":"us"}'

const { check } = await kyc.kyb.check({
  companyName: "Acme Inc",
  registrationNumber: "12345678",
  country: "us",
});

Listar checks

GET /v1/kyb
X-API-Key: zkyc_...

{
  "ok": true,
  "checks": [
    { "id": "a1b2c3d4-...", "companyName": "Acme Inc", "country": "us", "status": "completed" }
  ],
  "total": 1
}

const { checks, total } = await kyc.kyb.list();

Detalle de un check

GET /v1/kyb/a1b2c3d4-...
X-API-Key: zkyc_...

{ "ok": true, "check": { "id": "a1b2c3d4-...", "companyName": "Acme Inc", "country": "us", "status": "completed" } }

const { check } = await kyc.kyb.get("a1b2c3d4-...");

Flujo del usuario

Vista no técnica: cómo verificar que una empresa existe y no tiene riesgos de cumplimiento.

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 /v1/kyb → adaptador por país + AML de directivos → kyb_checks (PostgreSQL).

Componente	Tipo	Ubicación
POST /v1/kyb	Route Express	src/kyb/routes.ts
GET /v1/kyb	Route Express	src/kyb/routes.ts
GET /v1/kyb/:id	Route Express	src/kyb/routes.ts
src/kyb/kyb.service.ts	Servicio KYB	src/kyb/kyb.service.ts
src/kyb/adapters/	Patrón adaptador por país	src/kyb/adapters/
POST /v1/aml/screen	Llamada interna (AML directivos)	src/aml/routes.ts
kyb_checks	Tabla checks de empresa	src/db/migrations/
kyb_check_results	Tabla resultados detallados	src/db/migrations/

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