Solicitudes KYB

KYB («Know Your Business», conozca su empresa) verifica la identidad y la estructura de una entidad empresarial. El ciclo de vida es el mismo que el de KYC (crear, subir los documentos de respaldo, enviar y recibir una decisión), pero con un paso adicional: envía una carga útil de entidad KYB que describe la empresa y sus personas principales.

Cree la solicitud con type: "BUSINESS" y, a continuación, haga POST al endpoint /kyb para adjuntar los datos de la entidad.

La extensión KYB

POST /api/v1/kyc/requests/:id/kyb    Ámbito: kyc:write

Adjunta los datos de la empresa, sus directores y sus beneficiarios finales (UBO) a una solicitud BUSINESS existente.

Cuerpo de la solicitud

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Cada director y cada UBO incluye fullName, dateOfBirth, nationality, además de campos específicos de su papel (appointedAt para los directores, ownershipPercentage para los UBO).

Respuesta (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

La respuesta también inicia en segundo plano una consulta en el registro: Certivant consulta el registro mercantil correspondiente (Companies House para GB, OpenCorporates para muchos otros países) y guarda los resultados asociados a la solicitud. Los resultados del registro son visibles en GET /kyb.

Obtener los datos KYB

GET /api/v1/kyc/requests/:id/kyb    Ámbito: kyc:read

Devuelve los datos de la entidad enviados junto con los resultados de la consulta en el registro, si los hay.

Respuesta

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta enumera los cargos que aparecen en el registro pero no se declararon en su array directors: es útil para detectar información que falta.

Documentos requeridos

Una solicitud BUSINESS normalmente necesita un conjunto de documentos distinto al de una persona física:

• CERTIFICATE_OF_INCORPORATION: prueba de que la empresa existe.
• PROOF_OF_ADDRESS: para el domicilio social.
• GOVERNMENT_ID y SELFIE para cada UBO y director (en algunas configuraciones, estos van en subsolicitudes por persona).
• COMPANY_OWNERSHIP_STRUCTURE: organigrama o libro de accionistas.

La lista exacta aparece en pendingDocTypes de la solicitud una vez adjuntados los datos de la entidad KYB. La configuración KYB de su organización determina qué se exige.

Subsolicitudes KYC por cada cargo

Según la configuración de su organización, Certivant puede crear automáticamente subsolicitudes KYC individuales para cada UBO y cada director. Aparecen como solicitudes separadas vinculadas a la solicitud BUSINESS principal mediante el campo parentRequestId. Usted sube los documentos a cada subsolicitud de la misma forma que a una solicitud KYC independiente: consulte Documentos.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

La solicitud principal permanece en PENDING_UPLOAD hasta que todas las subsolicitudes estén al menos en PROCESSING; después, atraviesa el mismo ciclo de vida que una solicitud individual: PROCESSING → APPROVED / REJECTED / ESCALATED.

Envío y decisión

Una vez subidos los documentos de la empresa y enviadas todas las subsolicitudes, envíe la principal:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

El motor de riesgo agrega las comprobaciones de empresa de la principal y el veredicto de cada subsolicitud en una única decisión. Los eventos de webhook se disparan para la solicitud principal: no necesita seguir por separado cada subsolicitud, salvo que quiera una vista detallada.

Errores

• 400 BAD_REQUEST: la solicitud no es de tipo BUSINESS. Los endpoints KYB solo funcionan con solicitudes de empresa.
• 409 CONFLICT: ya se han adjuntado datos KYB. Para cambiarlos, contacte con soporte: los datos de la entidad forman parte del rastro de auditoría y no pueden editarse libremente.

Relacionado

• Solicitudes KYC: los endpoints de solicitud subyacentes, con el mismo ciclo de vida.
• Documentos: cargar el justificante de constitución y los documentos de cada cargo.
• Webhooks: se aplican los mismos eventos kyc.request.*.