KYC

Todos los endpoints requieren Authorization: Bearer <token> y están acotados al tenant (clientId) resuelto desde OAuth. El producto KYC debe estar habilitado para tu tenant — de lo contrario las llamadas devuelven 403.

Descripción general

La API de KYC permite que tu tenant solicite procesos de verificación de identidad (background-check y, opcionalmente, verificación documental) para personas físicas (PF) y personas jurídicas (PJ), íntegramente vía API. Cada consulta se cobra por llamada exitosa, según el tipo (PF/PJ) y el modelo elegido.

Modelos de background-check

El campo backgroundcheckModel define la profundidad de la verificación (y el volumen de datos devuelto):

Modelo	Descripción
BASIC	Validación de identidad esencial
MEDIUM	Validación extendida
COMPLETE	Verificación completa (background check)

El precio unitario varía por tipo (PF/PJ) y modelo, según tu contrato.

Flujo asíncrono

El KYC es asíncrono:

1. Inicias el proceso (POST /v1/kyc/person o /v1/kyc/company). La respuesta devuelve un kycUUID y status: "PROCESSING".
2. El resultado se procesa de forma asíncrona (procesos kyc-backgroundcheck y kyc-documentscopy) — haz seguimiento por polling en GET /v1/kyc/list (el push por webhook para eventos kyc-* está en el roadmap).
3. Cuando documentscopyFlag = true, se genera una URL de webview (entregada de forma asíncrona) que el usuario final debe completar para finalizar la verificación documental.

El cobro ocurre en la iniciación exitosa (cuando se devuelve el kycUUID), de forma idempotente por kycUUID.

---

POST /v1/kyc/person

Inicia un proceso de KYC para una persona física (identificada por CPF).

Body:

Campo	Tipo	Obligatorio	Descripción
backgroundcheckModel	string	Sí	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Sí	Si es true, inicia la verificación documental (genera webview) tras el background-check
vatNumber	string	Sí	CPF (11 dígitos)
name	string	Sí	Nombre completo
birthDate	string	Sí	Fecha de nacimiento (dd-mm-aaaa)
motherName	string	Sí	Nombre completo de la madre

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PF",
    "model": "BASIC",
    "documentscopy": true,
    "webviewUrl": null
  }
}

webviewUrl puede llegar null en la iniciación y completarse después — consulta GET /v1/kyc/list hasta que aparezca.

---

POST /v1/kyc/company

Inicia un proceso de KYC para una persona jurídica (identificada por CNPJ).

Body:

Campo	Tipo	Obligatorio	Descripción
backgroundcheckModel	string	Sí	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Sí	Si es true, genera una webview de verificación documental para cada integrante del qsa
vatNumber	string	Sí	CNPJ (14 dígitos)
legalName	string	Sí	Razón social
qsa	array	Sí	Cuadro de socios y administradores (1 a 3 registros); al menos un SOCIO_ADMINISTRADOR

Cada ítem de qsa:

Campo	Tipo	Descripción
ownerType	string	SOCIO_ADMINISTRADOR | SOCIO
vatNumber	string	CPF del socio
name	string	Nombre del socio
birthDate	string	Fecha de nacimiento (dd-mm-aaaa)
motherName	string	Nombre de la madre del socio

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PJ",
    "model": "COMPLETE",
    "documentscopy": false
  }
}

---

GET /v1/kyc/list

Lista los procesos de KYC de tu tenant (con el estado más reciente). La lista se sirve desde nuestro registro interno, acotada a tu tenant — nunca ves procesos de otros tenants.

Query params:

Param	Tipo	Obligatorio	Descripción
kycUUID	string	No	Filtra por un proceso específico

Response 200 OK:

{
  "data": {
    "result": [
      {
        "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
        "vatNumber": "111***11",
        "process": "kyc-backgroundcheck",
        "status": "APPROVED",
        "kycType": "PF"
      }
    ]
  }
}

• process: kyc-backgroundcheck | kyc-documentscopy
• status: APPROVED | REPROVED | PROCESSING | PENDING
• vatNumber se devuelve enmascarado.

---

POST /v1/kyc/manual-decision

Aplica una decisión manual (aprobar/rechazar) a uno de los procesos de KYC de tu tenant. El kycUUID debe pertenecer a tu tenant.

Body:

Campo	Tipo	Obligatorio	Descripción
kycUUID	string	Sí	Identificador del proceso
decision	string	Sí	APPROVED | REPROVED
reason	string	Sí	Justificación (hasta 500 caracteres)

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "decision": "APPROVED"
  }
}

---

Seguimiento de estado

Los procesos de KYC se actualizan de forma asíncrona:

Proceso	Cuándo dispara
kyc-backgroundcheck	Finalización/actualización del background-check
kyc-documentscopy	Generación de la webview y finalización/actualización de la verificación documental

Cada registro lleva el kycUUID y el status (APPROVED | REPROVED | PROCESSING | PENDING).

Consulta por polling. Hoy el seguimiento se hace vía GET /v1/kyc/list (p. ej. cada 30s mientras esté PROCESSING). Los eventos kyc-* aún no se entregan en el webhook del tenant — el push por webhook (payload mínimo kycUUID + status) está en el roadmap. Los webhooks de onboarding de cuenta (onboarding-*, incluido onboarding-biometrics) no se ven afectados y se entregan normalmente.

---

Errores comunes

HTTP	Situación
400	backgroundcheckModel inválido, CPF/CNPJ ausente, qsa sin SOCIO_ADMINISTRADOR
403	Producto KYC no habilitado para el tenant; o un kycUUID de otro tenant en manual-decision

Consulta Manejo de Errores para el envelope de error estándar.