Saltar al contenido principal

Referencia de API (API Reference)

Esta sección cubre los endpoints estructurales que posibilitan la interacción con la API.

1. Authentication (Auth)​

POST
/signin

Endpoint de autenticación para obtener el token de acceso. Todos los requests subsecuentes requieren inyectar el token en el Header: Authorization: Bearer {accessToken}

Request Example​

curl -X POST "https://api.blacktrust.net/signin" \
     -H "Content-Type: application/json" \
     -d '{
           "email": "user@client.com",
           "password": "your_secure_password"
         }'

2. Inscribir Candidatos (Candidate Requests)​

POST
/candidate-requests

Este endpoint inicia el flujo asíncrono para ejecutar los Processes contenidos en un packageId asignado a tu entidad.

Business Validations (Pipe Logic)​

Nuestro Pipe de entrada valida los datos antes de agendar y correr los recursos asíncronos. Se retornará un error 400 si se incumplen estas reglas críticas:

Reglas Globales y Demográficas (Personas Físicas)
  • Mayoría de Edad: El candidato debe ser mayor de 18 años (calculado a partir de su birthDate).
  • Nacionalidad: Los países con soporte exclusivo de validación son: MX, DOM, GTM, HND, JAM, PAN.
  • Género: Datos aceptados estrictamente como H (Man), M (Woman), u X (Non-binary).
Identificadores y RFC (México)
  • Consistencia RFC/CURP: Si el candidato ingresa el RFC comercial (13 o 12 posiciones) y cuenta con la CURP federal provista, los primeros 10 caracteres del RFC deben colisionar idénticamente contra la CURP.
  • Reporte de Crédito: Si tu paquete incluye buró de crédito, el consentNIP de seguridad debe hacer match (Dígitos 3 y 4 del NIP deben coincidir con el año extraído del RFC en posiciones 5 y 6).
Entidades Corporativas (Personas Morales)
  • Comercialización: Validaciones exclusivas. Se omite el proceso de Referencias Personales.
  • Obligatorio: Todo registro corporativo requiere la provisión del parámetro regime (Régimen) y businessName (Razón Social).

Response (202 Accepted)​

Si el Pipe concluye sin anomalías, se encola la solicitud y se devuelve el uuid del candidato a nivel de paquete.

{
  "uuid": "8b9cad0e-1f20-4192-bff0-e1e043cea4db",
  "status": "Pending",
  "packageId": "vip-onboarding-tier1",
  "message": "Processes dispatched successfully."
}

3. Consultar Estado del Candidato (Candidate Request Status)​

GET
/candidate-requests/{uuid}

Este endpoint permite monitorear el progreso global de la solicitud y verificar el estado individual de cada proceso. Retorna el Resumen de la Solicitud (Request Overview) por defecto. Es el recurso principal para flujos de "polling" o consulta manual.

Request Example​

curl -X GET "https://api.blacktrust.net/candidate-requests/8b9cad0e-1f20-4192-bff0-e1e043cea4db" \
     -H "Authorization: Bearer {accessToken}"

Response (200 OK)​

A continuación se muestra un ejemplo de la respuesta estructural (Request Overview). El objeto processes contiene la lista de validaciones ejecutadas, sus fechas de inicio/fin y el resultado preliminar.

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "El registro del candidato con National Id SEVG920929HMNRLB01 fue satisfactorio",
    "data": {
        "isCandidateRegistered": true,
        "status": "Completed",
        "candidateId": "9bNONK0yqXYlbE8iBKZZ",
        "result": "Pendiente",
        "globalEndDate": null,
        "processes": [
            {
                "id": "0ggAQfM4NIFbShqLUxxF",
                "processName": "Peps",
                "result": "Riesgo Bajo",
                "status": "Finalizado",
                "startDate": 1758651740402,
                "endDate": 1758651743232
            },
            {
                "id": "0qUJmH8GRE4JCnmDFiy9",
                "processName": "Listas negras del SAT",
                "result": "Riesgo Bajo",
                "status": "Finalizado",
                "startDate": 1758651733591,
                "endDate": 1758651741203
            },
            {
                "id": "2Gk9ezpE2gAQEekFLCTO",
                "processName": "Referencias Personales",
                "result": "Pendiente",
                "status": "Con dependencia",
                "startDate": null,
                "endDate": null
            },
            {
                "id": "45hMSTayZYZGeUTgUp2A",
                "processName": "Validación de estudios",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651735562,
                "endDate": null
            },
            {
                "id": "4uHSRL06tV2tErX8zwcx",
                "processName": "BGC Laboral",
                "result": "No disponible",
                "status": "Finalizado",
                "startDate": 1758651734432,
                "endDate": 1758825295653
            },
            {
                "id": "698BbILPWd6I0oBGZOgk",
                "processName": "Global Watch List",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651729370,
                "endDate": 1758651737631
            },
            {
                "id": "7PQeIGuOJTUug6EISyYq",
                "processName": "Referencias Laborales",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651737626,
                "endDate": null
            },
            {
                "id": "A4mD4mGSe5Vn7ybXiHaC",
                "processName": "Geolocalización",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651734070,
                "endDate": null
            },
            {
                "id": "BGRgx6JHpDAFDszrQUGQ",
                "processName": "Documentos",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651735668,
                "endDate": null
            },
            {
                "id": "UZTVM67AaDcqVmPGKhdq",
                "processName": "BGC News",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651741571,
                "endDate": 1758651805644
            },
            {
                "id": "jbJ6ryPsJKqt60mA2bon",
                "processName": "Reporte de Crédito",
                "result": "Pendiente",
                "status": "Pendiente Candidato",
                "startDate": 1758651734729,
                "endDate": null
            },
            {
                "id": "kHQ71upc7krtkM21har2",
                "processName": "BGC Legal",
                "result": "Aprobado",
                "status": "Finalizado",
                "startDate": 1758651740531,
                "endDate": 1758651747070
            }
        ]
    }
}

4. Consultar Detalle de Proceso (Process Detail)​

GET
/candidate-requests/{uuid}/processes/{processId}

Una vez que un proceso ha finalizado, puedes consultar su Resumen del Proceso (Process Summary) o los Datos Técnicos Extendidos (Extended Technical Data).

Parámetros de Query​

  • detail (boolean): Si se establece en true, la respuesta incluirá el objeto rawDetails con los datos técnicos extendidos. Por defecto es false, retornando solo el resumen ejecutivo.

Referencia de Esquemas​

Para conocer la estructura específica de cada proceso (ej. qué campos devuelve BGC Legal vs Credit Report), consulta el Catálogo de Procesos.