API de Validación de Ingresos (Open Banking)

Descripción General

Esta API permite validar los ingresos de una persona consultando directamente sus datos bancarios mediante Open Banking. El sistema se conecta con los bancos chilenos para obtener información de pagos recurrentes y patrones de ingresos, sin necesidad de identificar al empleador específico.

Endpoint Principal

POST {{HOST}}/cl/income/detalle_empleador

Autenticación

La API requiere autenticación mediante token Bearer y cookie de sesión:

• Authorization: Bearer token

Parámetros de Entrada

Modo Sandbox

Para desarrollo y testing, la API incluye un modo sandbox que genera respuestas ficticias sin realizar consultas reales a los bancos.

Activación del Sandbox

Agregar el parámetro sandbox: true en la solicitud:

{
    "sandbox": true,
    "banco": "bice",
    "id": "11111111",
    "password": "1234",
    "salary_min": "2000000",
    "salary_max": "3000000",
    "employer_name": "Floid spa"
}

Credenciales de Prueba

Datos Ficticios del Sandbox

• RUT del Cliente: Usa el RUT del request
• Nombre del Cliente: Juan Carlos Pérez González
• Banco Analizado: Basado en el parámetro banco
• Continuidad: 7 meses consecutivos
• Antigüedad: 7 meses totales
• Pagos: Calculados dinámicamente según el rango de salarios

Casos de Prueba del Sandbox

1. Request exitosa con empleador:

   JSON

    {
        "sandbox": true,
        "banco": "bice",
        "id": "11111111",
        "password": "1234",
        "salary_min": "2000000",
        "salary_max": "3000000",
        "employer_name": "Floid spa"
    }
   
   

2. Request sin empleador (no match):

   JSON

    {
        "sandbox": true,
        "banco": "bice",
        "id": "11111111",
        "password": "1234",
        "salary_min": "2000000",
        "salary_max": "3000000"
    }
   
   

3. Credenciales inválidas:

   JSON

    {
        "sandbox": true,
        "banco": "bice",
        "id": "99999999",
        "password": "wrong_password",
        "salary_min": "2000000",
        "salary_max": "3000000"
    }
   
   

Ejemplo de Solicitud

curl --location '{{HOST}}/cl/income/detalle_empleador' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer tu_token_aqui' \
--header 'Cookie: PHPSESSID=tu_sesion_id_aqui' \
--data '{
    "banco": "santander",
    "id": "{{id}}",
    "password": "{{password}}",
    "salary_min": "2000000",
    "salary_max": "3000000",
    "employer_name": "{{employer}}"
}'

Respuesta Exitosa

{
    "code": "200",
    "msg": "OK",
    "caseid": "xxxxx",
    "data": {
        "rut_cliente": "11.111.111-1",
        "banco_analizado": "Banco de Chile",
        "glosa_original": "PAGO REMUNERACIONES FLOID SPA",
        "periodo_analizado": {
            "desde": "2024-01",
            "hasta": "2024-09"
        },
        "continuidad_remuneraciones_meses": 7,
        "antiguedad_remuneraciones_meses": 7,
        "pagos_identificados": [
            {
                "periodo": "2024-09",
                "fecha_abono": "26/09/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-08",
                "fecha_abono": "29/08/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-07",
                "fecha_abono": "29/07/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-06",
                "fecha_abono": "27/06/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-05",
                "fecha_abono": "30/05/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-04",
                "fecha_abono": "29/04/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            },
            {
                "periodo": "2024-01",
                "fecha_abono": "30/01/2024",
                "monto": 2500000,
                "glosa_original": "PAGO REMUNERACIONES FLOID SPA"
            }
        ]
    },
    "pdf_report": {
        "available": true,
        "download_url": "https://storage.googleapis.com/floid_files_dev/employment_reports/income_report_xxxxx_2024-12-19_10-30-00.pdf?GoogleAccessId=mock-access-id@mock-project.iam.gserviceaccount.com&Expires=1791463194&Signature=mock-signature",
        "filename": "income_report_xxxxx_2024-12-19_10-30-00.pdf",
        "generated_at": "2024-12-19 10:30:00"
    }
}

Estructura de Campos de Respuesta

Campos Principales

Objeto de Pago (pagos_identificados[])

Métricas Clave

Continuidad de Remuneraciones

Número de meses consecutivos con pagos identificados, contados desde el pago más reciente hacia atrás. Se detiene al encontrar el primer mes sin pago.

Ejemplo:

2024-09 ✓
2024-08 ✓  → Continuidad = 3 meses
2024-07 ✓
2024-06 ✗ (gap)
2024-05 ✓

Antigüedad de Remuneraciones

Cantidad total de meses con pagos identificados, sin importar si son consecutivos o tienen gaps entre ellos.

Ejemplo:

2024-09 ✓
2024-08 ✓
2024-07 ✓  → Antigüedad = 5 meses (cuenta todos los pagos)
2024-06 ✗ (gap no afecta)
2024-05 ✓
2024-04 ✓

Respuesta Sin Pagos Identificados

{
    "code": "200",
    "msg": "OK",
    "caseid": "xxxxx",
    "data": {
        "rut_cliente": "11.111.111-1",
        "banco_analizado": "Banco de Chile",
        "glosa_original": "",
        "periodo_analizado": {
            "desde": "",
            "hasta": ""
        },
        "continuidad_remuneraciones_meses": 0,
        "antiguedad_remuneraciones_meses": 0,
        "pagos_identificados": []
    }
}

Códigos de Error Comunes

Bancos Soportados

• santander: Banco Santander
• bci: Banco de Crédito e Inversiones
• chile: Banco de Chile
• estado: Banco del Estado
• scotiabank: Scotiabank Chile
• itau: Itaú Chile
• bice: Bice Chile
• security: Security Chile

Consideraciones Importantes

Seguridad

• Las credenciales bancarias se procesan de forma segura
• No se almacenan contraseñas en nuestros sistemas
• Cada consulta genera un ID único de caso para trazabilidad
• Modo Sandbox: Usa solo datos ficticios, no realiza consultas reales

Límites y Restricciones

• Tiempo máximo de respuesta: 2 minutos
• Máximo 3 intentos por consulta
• Modo Sandbox: Respuesta inmediata sin límites de tiempo

Validaciones

• El RUT debe tener formato válido chileno
• Las credenciales deben ser correctas para el banco especificado
• Los rangos de salario ayudan a filtrar transacciones relevantes
• El sistema identifica pagos por palabras clave (SUELDO, REMUNERACION, PAGO HABERES, etc.)
• Modo Sandbox: Acepta credenciales de prueba predefinidas

Diferencias con Employment Validation (Sistema Anterior)

Reporte PDF

Cada validación exitosa genera automáticamente un reporte PDF profesional que incluye:

• Encabezado: Fecha de generación y logo de Floid
• Título: "REPORTE DE VALIDACIÓN DE INGRESOS (Open Banking)"
• ID del Caso: Identificador único para verificación
• Resumen General: Tabla con los 6 campos principales
• Detalle de Pagos: Tabla con todos los pagos identificados
• Definiciones: Explicación de cada campo del reporte
• Elementos de Seguridad: QR code y sello de autenticidad

Acceso al PDF

El PDF se almacena en Google Cloud Storage y se proporciona una URL firmada con 7 días de vigencia en el campo pdf_report.download_url.

Flujo de Integración

1. Autenticación: Obtener token Bearer
2. Solicitud: Enviar datos del usuario y parámetros de validación
3. Procesamiento:
   • Modo Normal: El sistema consulta el banco del usuario y analiza transacciones
   • Modo Sandbox: El sistema genera datos ficticios de prueba
4. Análisis: El sistema identifica pagos recurrentes y calcula métricas
5. Respuesta: Recibir resultado de validación con detalles de ingresos y PDF

Soporte Técnico

Para soporte técnico o consultas sobre la integración, contactar al equipo de desarrollo con:

• ID del caso (caseid) si hay errores
• Logs de la aplicación
• Detalles del banco y tipo de error
• Indicar si se usó modo sandbox
• Rango de fechas analizado

Changelog

• v1.0: Versión inicial con soporte para bancos principales de Chile
• v1.1: Agregado soporte para validación de empleador y rangos de salario
• v1.2: Implementado modo sandbox para desarrollo y testing
• v2.0: Migración a Income Validation (Open Banking) - Enfoque en patrones de pago
• v2.1: Actualizado sandbox para nuevo formato de respuesta con métricas de continuidad

Mapeo de Campos

Documentación actualizada: Noviembre 2025
Versión API: 2.1
Sistema: Income Validation (Open Banking)