Receta de API: Cómo realizar una verificación completa de KYB en un perfil empresarial

Esta guía recorre el flujo completo de la API para ejecutar la verificación Know Your Business (KYB) utilizando Perfiles de Negocio. Cada paso se basa en el anterior, y se envían callbacks en cada etapa para que puedas seguir el progreso en tiempo real.

URL base: https://api.aiprise.com/api/v1/verify

Autenticación: Todas las solicitudes requieren el x-api-key encabezado.

Diagrama de flujo completo

aiprise_kyb_enhanced_flow.png

Resumen

Paso

Punto final

Propósito

1

POST /create_business_profile

Crear la entidad comercial

2

POST /run_verification_for_business_profile_id

Ejecutar verificaciones KYB (búsqueda en registro, AML, etc.)

3a

POST /related_person_v2

Agregar una persona relacionada (UBO/director)

3b

POST /run_verification_for_user_profile_id

Ejecutar KYC en la persona relacionada

3c

POST /create_verification_session_url_for_user_profile

Generar un enlace de verificación en su lugar

4a

POST /related_company_v2

Agregar una empresa relacionada

4b

POST /run_verification_for_business_profile_id

Ejecutar KYB en la empresa relacionada (usando su ID de perfil comercial)

5a

POST /add_business_document

Cargar un documento empresarial

5b

POST /run_check_on_business_document

Ejecutar verificación de documento

6

POST /make_decision_with_risk_scoring

Ejecutar puntuación de riesgo / toma de decisiones

7

POST /update_business_profile_result

Establecer la decisión final (Aprobar/Rechazar/Revisar)


Paso 1: Crear un perfil empresarial

Cree una entidad empresarial persistente que contendrá todos los datos de verificación, personas relacionadas, empresas y documentos.

POST /api/v1/verify/create_business_profile

Solicitud

{
  "name": "Acme Corporación",
  "alternate_name": "Acme Corp",
  "tax_identification_number": "12-3456789",
  "website": "<https://acme.com>",
  "country_code": "US",
  "state_code": "DE",
  "formation_date": "2015-03-15",
  "business_entity_id": "your-internal-id-123",
  "client_reference_id": "your-internal-tracking-id",
  "client_reference_data": {
    "internal_case_number": "CASE-2024-001",
    "onboarding_source": "partner-api"
  },
  "addresses": [
    {
      "address_street_1": "123 Calle Principal",
      "address_street_2": "Suite 400",
      "address_city": "Wilmington",
      "address_state": "DE",
      "address_zip_code": "19801",
      "address_country": "US"
    }
  ],
  "phone_numbers": ["+13025551234"],
  "email_addresses": ["compliance@acme.com"],
  "tags": ["alto valor", "fintech"]
}
  • client_reference_id — su ID de referencia interno para rastrear este negocio a través de los sistemas

  • client_reference_data — metadatos JSON arbitrarios que desea adjuntar a este perfil (se trasladan a todas las sesiones de verificación)

Respuesta

{
  "business_profile_id": "bp_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Devolución de llamada

Tipo de evento: BUSINESS_PROFILE_CREATE

{
  "callback_event_id": "evt_...",
  "event_type": "BUSINESS_PROFILE_CREATE",
  "business_profile_id": "bp_a1b2c3d4-..."
}

Guarda el business_profile_id — lo usarás en cada llamada posterior.


Paso 2: Ejecutar la verificación del perfil empresarial

Esto activa el flujo de trabajo KYB configurado en su plantilla (p.ej., búsqueda en el registro, verificación de TIN, filtrado AML, medios adversos).

POST /api/v1/verify/run_verification_for_business_profile_id

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "template_id": "your-kyb-template-id"
}

El client_reference_id y client_reference_data establecidos durante la creación del perfil se transfieren automáticamente a la sesión de verificación. No necesitas pasarlos de nuevo.

Respuesta

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "aiprise_result": {
    "verification_session_id": "vs_...",
    "business_profile_id": "bp_a1b2c3d4-...",
    "business_profile_result": "DESCONOCIDO",
    "lookup_info": {
      "company_name": "Corporación Acme",
      "registration_number": "1234567",
      "status": "Activo",
      "jurisdiction": "Delaware",
      "officers": []
    },
    "related_persons": [],
    "related_companies": [],
    "documents": []
  }
}

El lookup_info contiene los datos del registro extraídos en tiempo real. También puede devolver oficiales/directores sugeridos del registro que luego puedes agregar como personas relacionadas.

Devolución de llamada

Tipo de evento: RUN_BUSINESS_VERIFICATION

La carga útil de la devolución contiene el resultado completo de la verificación empresarial. Esto se envía a tu events_callback_url.

Además, cuando la sesión de verificación se complete, una VERIFICATION_SESSION_COMPLETION llamada se envía a tu callback_url con los datos completos del perfil empresarial.


Paso 3: Añadir Personas Relacionadas y Ejecutar Verificación

3a. Añadir una Persona Relacionada (UBO / Director / Oficial)

POST /api/v1/verify/related_person_v2

En la API v2, las personas relacionadas están respaldadas por un perfil de usuario completo, lo que permite datos más ricos y jerarquías de entidades de nivel n.

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "user_profile": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1985-06-15",
    "email_address": "jane.doe@acme.com",
    "phone_number": "+13025559876",
    "address": {
      "address_street_1": "456 Oak Ave",
      "address_city": "Wilmington",
      "address_state": "DE",
      "address_zip_code": "19801",
      "address_country": "US"
    },
    "client_reference_id": "your-person-ref-id",
    "client_reference_data": {}
  },
  "ownership_percent": 25.0,
  "shares_allocated": 1000,
  "roles": ["UBO", "Director"]
}

Respuesta

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "person_reference_id": "pr_f1e2d3c4-..."
}

Llamada de retorno

Tipo de evento: ADD_BUSINESS_OFFICER — la carga incluye el objeto de persona relacionada completo.


3b. Ejecutar verificación KYC en la persona relacionada

Una vez que se agrega la persona relacionada, realice KYC en su perfil de usuario. El person_reference_id devuelto en el paso 3a corresponde a un perfil de usuario que puede verificar.

POST /api/v1/verify/run_verification_for_user_profile_id

Solicitud

{
  "user_profile_id": "pr_f1e2d3c4-...",
  "template_id": "your-kyc-template-id",
  "user_data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1985-06-15",
    "email_address": "jane.doe@acme.com"
  },
  "additional_info": [
    {
      "additional_info_type": "PROOF_OF_ADDRESS",
      "additional_info_data": "\u003cbase64-encoded-document\u003e"
    }
  ]
}

user_data se pre-poblado a partir del registro de persona relacionado creado en el paso 3a. Los campos que pases aquí sobrescribirán los valores almacenados.

Respuesta

{
  "verification_session_id": "vs_...",
  "user_profile_id": "pr_f1e2d3c4-...",
  "user_profile_result": "UNKNOWN"
}

Llamada de retorno

Tipo de evento: BUSINESS_OFFICER_RUN_KYC — la carga útil incluye el resultado de la verificación KYC más el person_reference_id.


3c. Generar un enlace de verificación (alternativa a incrustado)

Utiliza esto cuando quieras que la persona complete el KYC por sí misma mediante un flujo de verificación alojado.

POST /api/v1/verify/create_verification_session_url_for_user_profile

Solicitud

{
  "user_profile_id": "pr_f1e2d3c4-...",
  "template_id": "your-kyc-template-id",
  "redirect_uri": "\u003chttps://your-app.com/verification-complete\u003e"
}

Campos opcionales: client_reference_id, client_reference_data, theme_options, ui_options.

Respuesta

{
  "verification_url": "<https://verify.aiprise.io/session/>..."
}

Comparte esta URL con la persona. Cuando completen el flujo, un BUSINESS_OFFICER_RUN_KYC callback se envía automáticamente.

Llamada de retorno

Tipo de evento: USER_PROFILE_CREATE_SESSION_URL

{
  "callback_event_id": "evt_...",
  "event_type": "USER_PROFILE_CREATE_SESSION_URL",
  "user_profile_id": "pr_f1e2d3c4-...",
  "session_url": "\u003chttps://verify.aiprise.io/session/\u003e...",
  "verification_session_id": "vs_...",
  "expires_at": 1735689600000
}

Paso 4: Añadir Empresas Relacionadas y Ejecutar Verificación

4a. Añadir una Empresa Relacionada

POST /api/v1/verify/related_company_v2

En la API v2, las empresas relacionadas están respaldadas por su propio perfil comercial, lo que permite jerarquías KYB recursivas de varios niveles (p. ej., empresa matriz > subsidiaria > sub-subsidiaria).

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "relationship_type": "PARENT",
  "business_profile": {
    "name": "Acme Holdings LLC",
    "tax_identification_number": "98-7654321",
    "country_code": "US",
    "state_code": "DE",
    "addresses": [
      {
        "address_street_1": "789 Corporate Blvd",
        "address_city": "Dover",
        "address_state": "DE",
        "address_zip_code": "19901",
        "address_country": "US"
      }
    ],
    "client_reference_id": "your-company-ref-id",
    "client_reference_data": {}
  },
  "ownership_percent": 100.0,
  "shares_allocated": 5000,
  "roles": ["Parent Company"]
}

Respuesta

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "company_reference_id": "cr_g7h8i9j0-..."
}

Llamada de retorno

Tipo de evento: ADD_RELATED_COMPANY — la carga útil incluye el objeto completo de la empresa relacionada.


4b. Ejecutar KYB en la empresa relacionada

Dado que las empresas relacionadas con v2 están respaldadas por su propio perfil comercial, ejecutas la verificación usando el mismo endpoint que el Paso 2 — simplemente pasa la empresa relacionada company_reference_id (que es su propio ID de perfil comercial).

POST /api/v1/verify/run_verification_for_business_profile_id

Solicitud

{
  "business_profile_id": "cr_g7h8i9j0-...",
  "template_id": "your-kyb-template-id"
}

El company_reference_id devuelto en el paso 4a es un ID de perfil empresarial. Pásalo directamente como business_profile_id aquí. Los datos de la empresa relacionada (nombre, NIT, dirección, etc.) ya se establecieron cuando la creaste en el paso 4a.

Respuesta

{
  "business_profile_id": "cr_g7h8i9j0-...",
  "aiprise_result": {
    "verification_session_id": "vs_...",
    "business_profile_id": "cr_g7h8i9j0-...",
    "business_profile_result": "UNKNOWN",
    "lookup_info": {}
  }
}

Llamada de retorno

Tipo de evento: RUN_BUSINESS_VERIFICATION — misma estructura de devolución de llamada que el Paso 2, limitada al perfil comercial de la empresa relacionada.


Paso 5: Cargar y Verificar Documentos Comerciales

5a. Subir un documento

POST /api/v1/verify/add_business_document

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "file_name": "certificate_of_incorporation.pdf",
  "file_type": "CERTIFICATE_OF_INCORPORATION",
  "file_blob": "<base64-encoded-file>"
}

Tamaño máximo de archivo: 50 MB. Formatos compatibles: PDF, PNG, JPG, JPEG.

Respuesta

{
  "file_uuid": "file_k1l2m3n4-..."
}

Llamada de retorno

Tipo de evento: ADD_ADDITIONAL_MEDIA


5b. Ejecutar una verificación del documento

POST /api/v1/verify/run_check_on_business_document

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "template_id": "your-document-check-template-id",
  "file_uuid": "file_k1l2m3n4-...",
  "document_input_title": "Certificate of Incorporation"
}

Respuesta

La respuesta contiene los resultados de la verificación del documento, incluyendo la extracción OCR, la detección de manipulación y cualquier verificación de documentos configurada.

{
  "verification_session_id": "vs_...",
  "document_check_result": {}
}

Llamada de retorno

Tipo de evento: RUN_BUSINESS_DOCUMENT_CHECK


Paso 6: Ejecutar puntuación de riesgo / toma de decisiones

La puntuación de riesgo utiliza el mismo endpoint que la toma de decisiones, pero con un ID de plantilla de puntuación de riesgo en lugar de una plantilla KYB regular. La plantilla de puntuación de riesgo agrega resultados de todos los pasos anteriores (datos del registro, resultados de KYC de UBO, verificaciones de documentos, etc.) y produce una puntuación de riesgo.

POST /api/v1/verify/make_decision_with_risk_scoring

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "template_id": "your-risk-scoring-template-id"
}

El template_id aquí debe ser una plantilla configurada como una plantilla de puntuación de riesgo o de toma de decisiones. Esta es una plantilla diferente de la utilizada en el Paso 2.

Respuesta

{
  "verification_session_id": "vs_...",
  "business_profile_id": "bp_a1b2c3d4-..."
}

Devolución de llamada

Tipo de evento: RUN_RISK_SCORING (para plantillas de puntuación de riesgo) o MAKE_DECISION (para plantillas de decisión)

La puntuación de riesgo/toma de decisiones requiere que todas las sesiones hijas (UBO KYC, KYB de la empresa relacionada, verificaciones de documentos) se hayan completado. Si alguna sesión hija aún está pendiente, el flujo de trabajo de puntuación de riesgo no tendrá todos los datos para trabajar.


Paso 7 (Opcional): Establecer manualmente la decisión final

Si deseas sobrescribir o establecer manualmente el resultado del perfil empresarial:

POST /api/v1/verify/update_business_profile_result

Solicitud

{
  "business_profile_id": "bp_a1b2c3d4-...",
  "result": "APPROVED"
}

Valores válidos para result: APPROVED, DECLINED, REVIEW, DEACTIVATED

Si está configurando DECLINED como valor, reason_code es obligatorio.

Devolución de llamada

Tipo de evento: RESULT_UPDATE

El perfil completo del negocio se envía a su callback_url, y una actualización incremental del evento se envía a su events_callback_url.


Referencia de callbacks

Configuración

Las URL de Callback se configuran en tu plantilla en el panel de AiPrise:

  • callback_url — recibe la carga completa del perfil empresarial cuando se completa una sesión de verificación (VERIFICATION_SESSION_COMPLETION)

  • events_callback_url — recibe actualizaciones incrementales de eventos a medida que cada acción ocurre en el perfil empresarial

Seguridad

Todas las llamadas de retorno incluyen una firma HMAC-SHA256 en el X-HMAC-SIGNATURE encabezado, calculada a partir de la carga útil usando la clave secreta de su empresa. Siempre valide esta firma antes de procesarla.

Tipos de Evento

Evento

Disparador

BUSINESS_PROFILE_CREATE

Perfil de negocio creado

RUN_BUSINESS_VERIFICATION

Verificación KYB ejecutada en el negocio

ADD_BUSINESS_OFFICER

Persona relacionada añadida

EDIT_BUSINESS_OFFICER

Persona relacionada actualizada

DELETE_BUSINESS_OFFICER

Persona relacionada eliminada

BUSINESS_OFFICER_RUN_KYC

Verificación KYC realizada en una persona relacionada

BUSINESS_OFFICER_CREATE_SESSION_URL

Enlace de verificación generado para una persona relacionada

ADD_RELATED_COMPANY

Empresa relacionada añadida

EDIT_RELATED_COMPANY

Empresa relacionada actualizada

DELETE_RELATED_COMPANY

Empresa relacionada eliminada

RELATED_COMPANY_RUN_KYB

Verificación KYB realizada en una empresa relacionada

ADD_ADDITIONAL_MEDIA

Documento de negocio cargado

UPDATE_ADDITIONAL_MEDIA

Documento de negocio actualizado

DELETE_ADDITIONAL_MEDIA

Documento de negocio eliminado

RUN_BUSINESS_DOCUMENT_CHECK

Revisión de documento ejecutada

RUN_RISK_SCORING

Puntuación de riesgo ejecutada

MAKE_DECISION

Decisión ejecutada

RESULT_UPDATE

Resultado del perfil de negocio actualizado manualmente

VERIFICATION_REQUEST_SUBMITTED

Solicitud de verificación enviada mediante invitación por correo electrónico

BUSINESS_PROFILE_INFO_UPDATE

Información del perfil de negocio actualizada

Estructura del Payload de Callback

Todas las devoluciones de llamada de eventos siguen esta estructura:

{
  "callback_event_id": "unique-event-id",
  "event_type": "EVENT_TYPE",
  "business_profile_id": "bp_...",
  "verification_session_id": "vs_... (when applicable)",
  "target_id": "person or company reference ID (when applicable)"
}

Reintentos

Las devoluciones de llamada se entregan de forma asíncrona. Si su endpoint devuelve una respuesta que no sea 2xx, la devolución de llamada se reintentará automáticamente.


Enlaces de referencia de API