Introducción

ℹ️ Operación Asíncrona: El Credit Check es un proceso estrictamente asíncrono. Es obligatorio indicar un callback_url donde recibirás el resultado final una vez completado el análisis en segundo plano.

Para integrar correctamente el scoring, debes distinguir entre dos dimensiones:

Dimensión Opciones disponibles Endpoint / Campo Clave
Producto Electricidad vs Gas /creditcheck o /creditcheck_gas
También: /creditcheck_no_sips o /creditcheck_no_sips_gas (sin SIPS)
Tipo de Persona Física vs Jurídica Campo tipo_persona y tipo de ID
Modalidad SIPS Con SIPS vs Sin SIPS Con SIPS usa CUPS, Sin SIPS usa amount directo

⚖️ Selecciona tu Escenario

⚡👤

Luz: Particular / Autónomo

NIF/NIE y autónomos en baja tensión.

Ver Guía
⚡🏢

Luz: Empresa (CIF)

Sociedades mercantiles y entidades con CIF.

Ver Guía
🔥👤

Gas: Particular / Autónomo

Clientes domésticos y pequeños negocios.

Ver Guía
🔥🏢

Gas: Empresa (CIF)

Grandes cuentas e industrias de gas.

Ver Guía
⚡💰

Luz: Amount Directo

Sin SIPS. Ya tienes el amount calculado.

🆕 Nuevo

Ver Guía
🔥💰

Gas: Amount Directo

Sin SIPS. Ya tienes el amount calculado.

🆕 Nuevo

Ver Guía

⚡ Escenarios de Electricidad

Utiliza el endpoint /creditcheck. Se integra con SIPS Electricidad para recuperar consumos históricos si no se proporciona el CAE.

👤 Particular / Autónomo (Persona Física)

Para NIF/NIE. Es obligatorio indicar tipo_persona: "Física".

🔴 Obligatorios

  • company_name (Nombre completo)
  • identificador (NIF/NIE)
  • tipo_identificador (NIF)
  • tipo_persona ("Física")
  • autonomo (true/false)
  • postal_code
  • town
  • address
  • province
  • cups (CUPS Electricidad)
  • callback_url

🟢 Aceptados (Opcionales)

  • cae (Consumo estimado)
  • tarifa_json (Datos fallback)
  • referencia_externa
POST /creditcheck
{
  "company_name": "Juan Pérez García",
  "identificador": "12345678Z",
  "tipo_identificador": "NIF",
  "tipo_persona": "Física",
  "autonomo": false,
  "postal_code": "28001",
  "town": "Madrid",
  "address": "Calle Alcalá 1",
  "province": "Madrid",
  "cups": "ES0021000005451399XXXX",
  "callback_url": "https://tu-api.com/callback"
}

🏢 Empresa / Sociedad (Persona Jurídica)

Para CIFs. Se recomienda usar "tipo_identificador": "NIF" para asegurar compatibilidad con validadores internos.

🔴 Obligatorios

  • company_name (Razón Social)
  • identificador (CIF)
  • tipo_identificador ("NIF")
  • tipo_persona ("Jurídica")
  • autonomo (false)
  • postal_code
  • cups (CUPS Electricidad)
  • callback_url

🟢 Aceptados (Opcionales)

  • town, address, province
  • referencia_externa
POST /creditcheck
{
  "company_name": "IMAGINA ENERGIA S.L.",
  "identificador": "B12345678",
  "tipo_identificador": "NIF",
  "tipo_persona": "Jurídica",
  "autonomo": false,
  "postal_code": "08001",
  "town": "Barcelona",
  "address": "Calle Diagonal 100",
  "province": "Barcelona",
  "cups": "ES0021000005451399XXXX",
  "callback_url": "https://tu-api.com/callback"
}

🔥 Escenarios de Gas

Utiliza el endpoint /creditcheck_gas. Permite el paso opcional del cae (Consumo Anual Estimado) para scoring directo sin depender de SIPS.

👤 Particular (Persona Física)

Para NIF/NIE. Es obligatorio indicar tipo_persona: "Física".

🔴 Obligatorios

  • company_name (Nombre completo)
  • identificador (NIF/NIE)
  • tipo_identificador (NIF)
  • tipo_persona ("Física")
  • autonomo (true/false)
  • postal_code
  • town
  • address
  • province
  • cups (CUPS Gas)
  • callback_url

🟢 Aceptados (Opcionales)

  • cae (Consumo estimado - Recomendado)
  • tarifa_json (ej: RL.2)
  • referencia_externa
POST /creditcheck_gas
{
  "company_name": "María García",
  "identificador": "87654321X",
  "tipo_identificador": "NIF",
  "tipo_persona": "Física",
  "autonomo": false,
  "postal_code": "46001",
  "town": "Valencia",
  "address": "Plaza del Ayuntamiento 5",
  "province": "Valencia",
  "cups": "ES0231101733548006XXXX",
  "cae": 3500.0,
  "callback_url": "https://tu-api.com/callback"
}

🏢 Empresa (Persona Jurídica)

Para CIFs. Se recomienda usar "tipo_identificador": "NIF" para asegurar compatibilidad con validadores internos.

🔴 Obligatorios

  • company_name (Razón Social)
  • identificador (CIF)
  • tipo_identificador ("NIF")
  • tipo_persona ("Jurídica")
  • autonomo (false)
  • postal_code
  • cups (CUPS Gas)
  • callback_url

🟢 Aceptados (Opcionales)

  • town, address, province
  • cae (Consumo estimado)
  • tarifa_json
  • referencia_externa
POST /creditcheck_gas
{
  "company_name": "INDUSTRIA GAS S.A.",
  "identificador": "A98765432",
  "tipo_identificador": "NIF",
  "tipo_persona": "Jurídica",
  "autonomo": false,
  "postal_code": "48001",
  "town": "Bilbao",
  "address": "Gran Vía 12",
  "province": "Vizcaya",
  "cups": "ES0231101733548006XXXX",
  "tarifa_json": {"nombre": "RL.3"},
  "callback_url": "https://tu-api.com/callback"
}

⚡ Endpoints SIN SIPS (Amount Directo)

🆕 Nuevos Endpoints: Estos endpoints permiten realizar Credit Check proporcionando el amount directamente, sin consultar SIPS ni requerir CUPS/CAE. Ideal para escenarios donde ya tienes el importe calculado.

Existen dos variantes para electricidad y gas que funcionan igual que los endpoints estándar, pero con estas diferencias clave:

Característica Endpoints Estándar Endpoints NO_SIPS
Endpoint Luz /creditcheck /creditcheck_no_sips
Endpoint Gas /creditcheck_gas /creditcheck_no_sips_gas
Parámetro CUPS ✅ Obligatorio ❌ Rechazado (error 400)
Parámetro CAE 🟢 Opcional (fallback) ❌ Rechazado (error 400)
Parámetro amount 🔵 Calculado por SIPS ✅ Obligatorio en request
Consulta SIPS ✅ Sí (con fallbacks) ❌ No (skip total)

⚡ Electricidad sin SIPS - /creditcheck_no_sips

Úsalo cuando ya tengas el amount calculado y no necesites consultar SIPS.

👤 Ejemplo: Particular / Autónomo

🔴 Obligatorios
  • identificador (NIF/NIE)
  • tipo_identificador (NIF/NIE)
  • amount (EUR)
🟡 Recomendados
  • company_name (nombre completo)
  • postal_code
  • town
  • address
  • province
  • autonomo (true/false)
❌ NO Permitidos
  • cups - Se rechaza con error
  • cae - Se rechaza con error
🟢 Opcionales
  • tipo_persona (auto-detectado)
  • callback_url (para async)
  • referencia_externa
POST /creditcheck_no_sips
{
  "identificador": "12345678Z",
  "tipo_identificador": "NIF",
  "amount": 1500.50,
  "company_name": "Juan Pérez García",
  "autonomo": false,
  "postal_code": "28001",
  "town": "Madrid",
  "address": "Calle Alcalá 1",
  "province": "Madrid",
  "amount": 1500.50,
  "callback_url": "https://tu-api.com/callback"
}

🏢 Ejemplo: Empresa (Persona Jurídica)

🔴 Obligatorios
  • identificador (CIF)
  • tipo_identificador (NIF)
  • amount (EUR)
🟡 Recomendados
  • company_name (razón social)
  • postal_code
  • town
  • address
  • province
❌ NO Permitidos
  • cups - Se rechaza con error
  • cae - Se rechaza con error
🟢 Opcionales
  • tipo_persona (auto-detectado)
  • autonomo (false por defecto)
  • callback_url (para async)
  • referencia_externa
POST /creditcheck_no_sips
{
  "identificador": "B12345678",
  "tipo_identificador": "NIF",
  "amount": 2500.00,
  "company_name": "IMAGINA ENERGIA S.L.",
  "postal_code": "08001",
  "town": "Barcelona",
  "address": "Calle Diagonal 100",
  "province": "Barcelona",
  "callback_url": "https://tu-api.com/callback"
}

🔥 Gas sin SIPS - /creditcheck_no_sips_gas

Versión para gas con las mismas características: requiere amount, rechaza CUPS y CAE.

👤 Ejemplo: Particular

POST /creditcheck_no_sips_gas
{
  "company_name": "María García",
  "identificador": "87654321X",
  "tipo_identificador": "NIF",
  "tipo_persona": "Física",
  "autonomo": false,
  "postal_code": "46001",
  "town": "Valencia",
  "address": "Plaza del Ayuntamiento 5",
  "province": "Valencia",
  "amount": 2000.75,
  "callback_url": "https://tu-api.com/callback"
}

🏢 Ejemplo: Empresa

POST /creditcheck_no_sips_gas
{
  "company_name": "INDUSTRIA GAS S.A.",
  "identificador": "A98765432",
  "tipo_identificador": "NIF",
  "tipo_persona": "Jurídica",
  "autonomo": false,
  "postal_code": "48001",
  "town": "Bilbao",
  "address": "Gran Vía 12",
  "province": "Vizcaya",
  "amount": 3500.00,
  "callback_url": "https://tu-api.com/callback"
}
⚠️ Errores Comunes:
  • Si envías cups → Error 400: "El parámetro 'cups' no está permitido en /creditcheck_no_sips"
  • Si envías cae → Error 400: "El parámetro 'cae' no está permitido en /creditcheck_no_sips"
  • Si falta amount → Error 400: "El parámetro 'amount' es requerido para /creditcheck_no_sips"
  • Si amount ≤ 0 → Error 400: "El parámetro 'amount' debe ser un número válido mayor que 0"

✅ Casos de Uso Recomendados

Escenario Endpoint Recomendado
Tienes CUPS y quieres que calculemos el amount desde consumos históricos /creditcheck o /creditcheck_gas
Ya calculaste el amount y no necesitas SIPS /creditcheck_no_sips o /creditcheck_no_sips_gas
Cliente nuevo sin CUPS previo pero con estimación de consumo /creditcheck_no_sips o /creditcheck_no_sips_gas
Necesitas velocidad máxima (sin consultas a SIPS) /creditcheck_no_sips o /creditcheck_no_sips_gas

📍 Referencia de Provincias

El campo province acepta tanto el nombre de la provincia como su ID numérico. A continuación se listan los nombres aceptados:

Albacete, Alicante, Almería, Araba/Álava, Asturias, Ávila, Badajoz, Barcelona, Bizkaia, Burgos, Cáceres, Cádiz, Cantabria, Castellón, Ceuta, Ciudad Real, Córdoba, Cuenca, Gipuzkoa, Girona, Granada, Guadalajara, Huelva, Huesca, Illes Balears, Jaén, La Coruña, La Rioja, Las Palmas, León, Lleida, Lugo, Madrid, Málaga, Melilla, Murcia, Navarra, Ourense, Palencia, Pontevedra, Salamanca, Santa Cruz de Tenerife, Segovia, Sevilla, Soria, Tarragona, Teruel, Toledo, Valencia, Valladolid, Zamora, Zaragoza.

⚙️ Flujo Técnico

1

Solicitud (202 Accepted)

Envías el JSON. Recibes un request_id.

2

Procesamiento en Background

Consultamos SIPS, verificamos Experian y aplicamos reglas de negocio.

3

Callback

Enviamos el resultado final (ACEPTADO/DENEGADO/REVISION MANUAL) a tu callback_url.

📬 Estructura del Resultado (Callback)

Una vez completado el análisis, el sistema enviará una petición POST a tu callback_url con la siguiente estructura simplificada:

✅ Resultado Exitoso

POST https://tu-api.com/callback
{
  "request_id": 1542,
  "referencia_externa": "SOLICITUD-99",
  "result": {
    "amount": 2500.50,
    "codigo": 1,
    "texto": "Aprobado",
    "raw": {
      "RequestForAdmissionResult": {
        "GetAdmissionReportResult": {
          "EvaluationResult": {
            "ResultCode": 1,
            "Description": "APTO"
          }
        }
      }
    }
  },
  "_callback_signature": {
    "version": "v1",
    "signature": "F9qDjHkLt5lO_JjiPvbP7wX4zK...",
    "timestamp": "1772552356"
  }
}

📊 Posibles Valores de Resultado

Código Texto Descripción Acción Recomendada
1 Aprobado El cliente ha pasado todas las validaciones crediticias ✅ Continuar con el proceso de contratación
2 Revisión Manual Se requiere análisis manual del caso ⚠️ Revisión por equipo de riesgos
3 Denegado El cliente no cumple los requisitos crediticios ❌ No proceder con la contratación
4 Revisión Manual Error en el proceso de scoring ⚠️ Contactar con soporte si persiste

⚠️ Ejemplo con Error

Si ocurre un error durante el proceso, el resultado incluirá un campo error:

{
  "request_id": 1543,
  "referencia_externa": "SOLICITUD-100",
  "result": {
    "amount": 1500.00,
    "codigo": 4,
    "texto": "Revisión Manual",
    "error": "No se ha podido verificar el scoring, se hace por revisión manual, puede continuar con la contratación."
  },
  "_callback_signature": {
    "version": "v1",
    "signature": "...",
    "timestamp": "1772552400"
  }
}

🔐 Seguridad del Callback - IMPORTANTE

Valida siempre la firma HMAC-SHA256 para asegurar que la petición proviene de Imagina Energía. Consulta la guía de seguridad de callbacks para detalles completos.

⚠️ CRÍTICO: Campos que forman parte de la firma

  • ✅ request_id - SÍ está en la firma
  • ✅ referencia_externa - SÍ está en la firma
  • ✅ result (o error) - SÍ está en la firma
  • ❌ _callback_signature - NO está en la firma (eliminar antes de validar)

✅ Correcto: 

payload = request.get_json()
payload.pop('_callback_signature')
validar_firma(url, payload, ...)

❌ Incorrecto: 

payload = request.get_json()
validar_firma(url, payload, ...)  # 💥 Incluye _callback_signature

💡 Campos del Resultado

Campo Tipo Descripción
request_id integer Identificador único de la petición devuelto en el 202
referencia_externa string Tu referencia opcional para trazabilidad
result.amount number Cantidad evaluada en euros (calculada desde consumo)
result.codigo integer Código numérico del resultado (1, 2, 3 o 4)
result.texto string Descripción legible del resultado
result.error string (Opcional) Mensaje de error si aplica

📋 Changelog

v2.1 - Junio 2026

  • 🆕 Nuevos endpoints sin SIPS: Añadidos /creditcheck_no_sips y /creditcheck_no_sips_gas para realizar scoring con amount directo sin consultar SIPS
  • ⚡ Flexibilidad mejorada: Ahora puedes proporcionar el amount directamente si ya lo tienes calculado, evitando consultas a SIPS
  • 🔒 Validación estricta: Los nuevos endpoints rechazan explícitamente cups y cae para evitar confusiones
  • 📝 Tracking mejorado: Los requests se almacenan con tipos específicos (CREDITCHECK_NO_SIPS, CREDITCHECK_NO_SIPS_GAS) para auditoría

v2.0 - Mayo 2026

  • ✨ Respuesta simplificada: El callback ahora devuelve una estructura más limpia con result.amount, result.codigo y result.texto
  • 🔧 Integración Scoring Module v1: Migración completa al módulo de scoring con proveedores múltiples (Experian + Indika)
  • 📊 Campo amount incluido: Ya no es necesario recalcular la cantidad evaluada
  • 📦 Campo raw incluido: Respuesta completa del proveedor de scoring para auditoría y análisis detallado (marcado en amarillo en el ejemplo)
  • 🛡️ Manejo de errores mejorado: Códigos 4 con mensajes descriptivos en caso de timeout o errores de scoring

v1.0 - Formato Legacy (deprecado)

El formato anterior incluía result_operation y status_code en lugar de result.codigo y result.texto. Esta estructura ha sido reemplazada por el formato simplificado actual.