Integración

Lo primero que debemos plantearnos es qué necesidades exactas tiene el proyecto antes de lanzarnos a programar. Por favor echa un vistazo al artículo «Cómo integrar NeoCheck«.

Dicho esto, NeoCheck proporciona una API REST JSON intuitiva y poderosa para integrar verificaciones conformes con KYB (Know Your Business) y AML (Anti Money Laundering) en tu negocio o aplicación. Esta referencia de API proporciona información sobre los endpoints disponibles y cómo interactuar con ellos.

Para especificaciones técnicas detalladas, visita nuestro portal Swagger: https://kyb.neocheck.net/Swagger/index.html

Autenticación API

El acceso a la API de NeoCheck está protegido mediante tokens de autorización OAuth2. Para autenticar tus solicitudes, debes llamar a la solicitud de autenticación con un nombre de usuario y una contraseña válidos. Estos serán entregados por el equipo de de NeoCheck. El endpoint en cuestión es: /api/authorization/token

Nota: Los parámetros apiKey y apiSecret están obsoletos. Simplemente déjalos vacíos ya que el contenido se ignora y solo persisten para mantener la compatibilidad con versiones anteriores.

Gestión de Empresas

Luego de la autenticación se debe buscar la compañía a la cual se le va a realizar la verificación, para este pase se pueden utilizar dos endpoints distintos:

Nota: Para todos los endpoints a partir de este punto, se deben configurar los siguientes parámetros en el Headers. Authorization, se debe colocar el token obtenido en el request anterior de autenticación. Ejemplo: Bearer TU_ACCESS_TOKEN. Content-Type, se debe colocar el tipo de contenido correspondiente, application/json

/api/v1/kyb/companies/lookup
- Este método Get es utilizado para encontrar las empresas disponibles según los siguientes filtros como query parameters:
  - companyName: El nombre de la empresa
  - vatNumber: El CIF de la empresa
  - country: El país de registro de la empresa
- El método devuelve un listado en forma de array con las compañías con coincidencias
/api/v1/kyb/companies/{id}
- Este método Get es utilizado para obtener la empresa de la verificación KYB usando el identificador de proveedor como path parameter
- Devuelve la empresa de la verificación KYB correspondiente al identificador pasado como parámetro

Gestión de la Verificación KYB

Al obtener la información de la compañía correspondiente, se debe hacer la llamada al endpoint POST /api/v1/kyb/verifications con el fin de crear la verificación KYB.

En el body, se pueden configurar los siguientes parámetros:

companyProviderIdentifier: (String)
- Descripción: ID de la compañía por parte del proveedor.
- Ejemplo: «A12345678»
manualCompanyData: (Objeto)
- Descripción: Objeto con los datos de la compañía.
- Ejemplo:

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "providerIdentifier": "string",
    "businessName": "string",
    "businessRegNumber": "string",
    "vatNumber": "string",
    "dateOfRegistration": "2025-08-06T13:14:06.612Z",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "locality": "string",
      "province": "string",
      "country": "string",
      "currentAddress": true
    }

kybVerificationId: (Guid)
- Descripción: ID de la verificación KYB.
- Ejemplo: «00000000-0000-0000-0000-000000000000»
applicantId: (Guid)
- Descripción: ID del aplicante.
- Ejemplo: «00000000-0000-0000-0000-000000000000»
notificationApiUrl: (String)
- Descripción: URL a la que se enviarán las notificaciones de estado de la verificación.
- Ejemplo: «https://example.com/api/notifications»
kybVerificationTicket: (Objeto)
- Descripción: Objeto en el cual se añaden los datos del ticket y del aplicante, como nombre, dirección de correo, número de teléfono, lenguaje y si se enviará el link directamente al aplicante por correo.
- Ejemplo:

{
    "name": "string",
    "emailAddress": "string",
    "phoneNumber": "string",
    "language": "string",
    "sendLink": true
  }

Ejemplo completo del body

{
  "companyProviderIdentifier": "string",
  "manualCompanyData": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "providerIdentifier": "string",
    "businessName": "string",
    "businessRegNumber": "string",
    "vatNumber": "string",
    "dateOfRegistration": "2025-08-06T13:14:06.612Z",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "postalCode": "string",
      "locality": "string",
      "province": "string",
      "country": "string",
      "currentAddress": true
    },
    "kybVerificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "notificationApiUrl": "string",
  "kybVerificationTicket": {
    "name": "string",
    "emailAddress": "string",
    "phoneNumber": "string",
    "language": "string",
    "sendLink": true
  }
}

Este endpoint nos dará como respuesta un string, el cual corresponde como el ID de la verificación.

Obtener el link manualmente

En caso de que el link del ticket, se quiera obtener de forma manual, se puede hacer una llamada al siguiente endpoint: /api/v1/kyb/verifications/{id}/ticket/link. En el cual el id es el ID de la verificación obtenido en el paso anterior.

Devolverá un string correspondiente al url del ticket para el aplicante.

Manejo de errores

La API de Neocheck devuelve códigos de estado HTTP estándar para indicar el éxito o el fallo de una solicitud. Aquí algunos ejemplos comunes:

200 OK: La solicitud fue exitosa.
401 Unauthorized: La autenticación falló o la clave de API es inválida. Se debe revisar el token que se esta colocando para la request.
404 Not Found: El recurso solicitado no se encontró. Se debe revisar el endpoint al cual se esta apuntando.
500 Internal Server Error: fallo interno del sistema.