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
Tipo de Persona Física vs Jurídica Campo tipo_persona y tipo de ID

⚖️ 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

⚡ 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"
}

📍 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: Valida siempre la firma en _callback_signature para asegurar que la petición proviene de Imagina Energía. Consulta la guía de seguridad de callbacks para más detalles.

💡 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.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.