Reporte de Crédito (Buró de Crédito)

El proceso de Reporte de Crédito permite evaluar de manera automatizada el historial crediticio, comportamiento de pago, nivel de endeudamiento y score de riesgo financiero de un candidato.

Este servicio está diseñado bajo una arquitectura flexible y modular, facilitando su adaptación a las necesidades de cumplimiento y conversión de cada cliente.

Flujos de Consentimiento Legal

Para llevar a cabo la consulta de Buró de Crédito, es indispensable contar con la autorización legal del candidato. El cliente debe elegir contractualmente uno de los siguientes dos esquemas operativos para recolectar dicha autorización:

Opción A: Recolección por Blacktrust (Plataforma btapp)

Cuándo aplica: Cuando apiConsentRequired se configura en false comercialmente.
Flujo del desarrollador: El cliente registra al candidato mediante la API enviando únicamente los datos demográficos básicos (sin incluir el objeto consent).
Experiencia del Candidato: Blacktrust envía automáticamente un correo electrónico con una invitación al candidato. Este inicia sesión o crea una cuenta en la plataforma btapp, visualiza el contrato de términos y condiciones, y acepta el consentimiento digital ingresando su fecha de nacimiento como firma.

Opción B: Recolección por el Cliente (Firma vía API)

Cuándo aplica: Cuando apiConsentRequired se configura en true comercialmente.
Flujo del desarrollador: El cliente asume la responsabilidad legal de recolectar la autorización del candidato dentro de su propio sistema o aplicación. Al registrar al candidato mediante la API de Blacktrust, debe enviar de manera obligatoria el nodo estructurado consent.
Experiencia del Candidato: El flujo se agiliza drásticamente. Si adicionalmente se envían las direcciones (homeAddress / workAddress), el candidato se salta por completo los formularios adicionales de la plataforma, maximizando la tasa de conversión (conversion rate) del reclutamiento.

1. Modos de Configuración (Flujo Comercial)

Este proceso es altamente parametrizable y se configura a nivel de contrato con el equipo comercial de Blacktrust mediante 4 flags clave. Dependiendo de la habilitación de estos flags, la experiencia del candidato y el detalle del resultado variarán de la siguiente manera:

Configuración a Nivel Contrato

Los siguientes flags regulan el flujo de consentimiento y la granularidad de la información devuelta por la API:

Flag	Tipo	Descripción	Comportamiento con `true`	Comportamiento con `false`
`apiConsentRequired`	`Boolean`	Regula el origen de la firma de consentimiento.	El objeto `consent` es estrictamente obligatorio en el payload de registro.	El candidato firma digitalmente entrando de forma manual a la plataforma `btapp`.
`creditReportPdf`	`Boolean`	Habilita la exportación del PDF oficial del buró.	La respuesta de la API incluirá el campo `creditReportFile` con la URL temporal del PDF.	Se omite el enlace de descarga del archivo PDF oficial.
`creditScore`	`Boolean`	Agrega el score de buró simplificado.	Agrega el objeto `bcScore` con el score unificado y la calificación estandarizada.	Se excluye el bloque `bcScore` de los resultados del proceso.
`fullCreditData`	`Boolean`	Incluye la información crediticia granular.	Se incluye el nodo completo `buroInformation` (Cuentas, direcciones históricas, etc.).	Se omite la información crediticia detallada de las cuentas.

2. Guía de Registro (Payload de Entrada)

Para iniciar el proceso de consulta de buró de crédito de un candidato, se debe enviar una solicitud al endpoint de registro. A continuación, se detalla un payload de ejemplo en el que se destacan dos capacidades avanzadas de integración:

A) Objeto de Consentimiento (Obligatorio si `apiConsentRequired: true`)

Cuando la configuración de tu contrato requiere consentimiento por API, debes adjuntar el nodo consent. Esto permite certificar que el candidato autorizó la consulta desde tu propia aplicación.

Nota Importante de Desarrollo

El campo consentNIP debe ser estrictamente los 4 dígitos del año de nacimiento del candidato (ej: '1985'), verificado físicamente contra su documento de identidad oficial.

B) Pre-llenado de Direcciones (Opcional)

Puedes enviar los objetos homeAddress (Dirección particular) y workAddress (Dirección laboral) directamente en el registro. Si tu API envía estos datos estructurados, el candidato se saltará este paso en el formulario de la plataforma, lo que aumenta considerablemente el conversion rate y agiliza el flujo de reclutamiento.

Ejemplo de Payload (`POST /candidate-requests`)

{
  "byNationalId": true,
  "nationalId": "xxxxxxxxxxxxxx",
  "clientId": "xxxxxxxxxxxxxx",
  "package": "xxxxxxxxxxxxxx",
  "taxClassification": "xxxxxxxxxxxxxx",
  "rfc": "xxxxxxxxxxxxxx",
  // [Obligatorio solo si apiConsentRequired = true]
  "consent": {
    "consentNIP": "1985",
    "consentAccepted": true,
    "consentDate": "2026-06-17T09:38:18Z"
  },
  // [Opcional]
  "homeAddress": {
    "street": "Avenida Insurgentes Sur",
    "externalNumber": "1234",
    "internalNumber": "5B",
    "neighborhood": "Del Valle",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  // [Opcional]
  "workAddress": {
    "street": "Paseo de la Reforma",
    "externalNumber": "505",
    "internalNumber": "Piso 12",
    "neighborhood": "Cuauhtémoc",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "06500",
    "country": "MX"
  }
}

3. Estructura de Respuesta Dinámica

La respuesta del proceso se adapta dinámicamente según la configuración de tu contrato comercial. A continuación se presentan los formatos de respuesta en función de las funcionalidades contratadas:

Vista Completa (Full Data)
Vista de Resumen (Summary View)

Detalle de Proceso Completo

Esta vista se obtiene al consultar el detalle del proceso cuando todos los flags de información extendida (fullCreditData, creditScore, y creditReportPdf) están activos.

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Success",
    "data": {
        "processId": "jbJ6ryPsJKqt60mA2bon",
        "processName": "Reporte de Crédito",
        "detail": {
            "candidateFinished": true, // Indica si el candidato ya completó todas las acciones requeridas en su flujo
            "consentAccepted": true,    // Confirma la existencia de una firma legal válida (vía API o plataforma)
            "creditConsultationDate": "10012025",
            
            // [Habilitado exclusivamente si fullCreditData = true contractualmente]
            "buroInformation": {
                "encabezado": { ... },
                "nombre": {
                    "apellidoPaterno": "GARCIA",
                    "apellidoMaterno": "RODRIGUEZ",
                    "primerNombre": "JUAN",
                    "fechaNacimiento": "15081985",
                    "rfc": "GARJ850815XX1", // Formato oficial mexicano
                    "nacionalidad": "MX",
                    "estadoCivil": "S",
                    "sexo": "M"
                },
                "domicilios": [ 
                    // Historial de domicilios fiscales y residenciales reportados ante el operador
                ],
                "cuentas": [ 
                    // Comportamiento de pago de créditos activos y cerrados (mecanismo R/CC)
                ],
                "resumenReporte": [ ... ],
                "scoreBuroCredito": [ ... ]
            },
            
            // [Habilitado solo si creditScore = true]
            "bcScore": [
                {
                    "nombreScore": "BC SCORE",
                    "codigoScore": "002",
                    "valorScore": "0680",
                    "score": "85.00", // Calificación estandarizada Blacktrust
                    "razon": [
                        "Antigüedad de la cuenta más antigua.",
                        "Nivel de endeudamiento."
                    ]
                }
            ],
            
            // [Habilitado solo si creditReportPdf = true]
            "creditReportFile": "https://storage.googleapis.com/btapp-bucket/reportes/ejemplo-anonimo.pdf?token=abc123token"
        },
        "allowClientView": true,
        "status": "Finalizado",
        "result": "Proceso completo"
    }
}

Vista de Resumen (Sin Flags Extendidos)

Esta estructura básica se presenta cuando no hay configurado ningún flag de visualización de datos extendidos (todos los flags configurados como false), devolviendo únicamente el estatus del flujo y la fecha de consulta.

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Success",
    "data": {
        "processId": "jbJ6ryPsJKqt60mA2bon",
        "processName": "Reporte de Crédito",
        "detail": {
            "candidateFinished": true, // Indica si el candidato ya completó todas las acciones requeridas en su flujo
            "consentAccepted": true,    // Confirma la existencia de una firma legal válida (vía API o plataforma)
            "creditConsultationDate": "10012025"
        },
        "allowClientView": true,
        "status": "Finalizado",
        "result": "Proceso completo"
    }
}

Flujos de Consentimiento Legal​

Opción A: Recolección por Blacktrust (Plataforma btapp)​

Opción B: Recolección por el Cliente (Firma vía API)​

1. Modos de Configuración (Flujo Comercial)​

2. Guía de Registro (Payload de Entrada)​

A) Objeto de Consentimiento (Obligatorio si apiConsentRequired: true)​

B) Pre-llenado de Direcciones (Opcional)​

Ejemplo de Payload (POST /candidate-requests)​

3. Estructura de Respuesta Dinámica​

Detalle de Proceso Completo​

Vista de Resumen (Sin Flags Extendidos)​