Guía de Credit Check: Síncrono, Asíncrono y Modo Raw

Introducción

ℹ️ Modos de ejecución disponibles:

Modo Síncrono Estándar: No envíes callback_url; el Credit Check responde inmediatamente con HTTP 200 y el resultado simplificado.
Modo Asíncrono: Envía callback_url; se responde 202 Accepted inmediatamente y el resultado final se envía después mediante POST a tu webhook con firma de seguridad HMAC.
Modo Raw Nativo (/creditcheck/raw/electricidad y /creditcheck/raw/gas): Es estrictamente síncrono; recibe la estructura de admisión nativa de Experian/Yndika y devuelve la respuesta JSON exacta sin modificaciones.

Campos y comportamiento efectivo

Campo o caso	Comportamiento
`identificador`, `tipo_identificador`	Obligatorios en endpoints estándar y sin SIPS.
`amount`	Obligatorio y mayor que 0 sólo en `/creditcheck_no_sips` y `/creditcheck_no_sips_gas`. En modo Raw se extrae de `internalTotalAmt`.
`callback_url`	Opcional en endpoints estándar y no SIPS. No permitido en `/creditcheck/raw/electricidad`.
`company_name`, `postal_code`, `cups`, `tipo_persona`, `autonomo`	Opcionales en endpoints estándar. `autonomo` ausente equivale a `false`.
`town`, `address`, `province`	Se pueden omitir los tres. Para Residencial o Autónomo, si se informa uno se deben informar los tres.
`tipo_identificador`	Se reconocen NIF, NIE, CIF y 4, 1, 5. Otro valor se trata como NIF. Un identificador con prefijo de CIF se clasifica como CIF.
`tipo_persona`	`Jurídica` convierte un NIF declarado en CIF/Empresa. `Física` no altera la clasificación. CIF con `autonomo: true` se rechaza.
Endpoints estándar	Primero consultan SIPS. Si falla, usan `cae` si se envió y, si no, una estimación. Un CUPS ausente o inválido no bloquea el uso de fallbacks.
`tarifa`	Opcional y relevante sólo en gas: se usa como fallback si SIPS no proporciona tarifa o si es necesario estimar el CAE.
Caché Inteligente (30 días)	Todos los endpoints verifican si existe una consulta previa en los últimos 30 días con importe compatible, reutilizando el scoring previo para ahorrar tiempo y costes.

Para integrar correctamente el scoring, dispones de tres modalidades principales:

Modalidad	Descripción	Endpoints	Modo
Estándar con SIPS	Calcula el importe automáticamente consultando consumos históricos en SIPS.	`/creditcheck` `/creditcheck_gas`	Síncrono (200) / Asíncrono (202)
Sin SIPS (Amount Directo)	Recibe el importe calculado directamente (sin consultar SIPS). Requiere `amount`.	`/creditcheck_no_sips` `/creditcheck_no_sips_gas`	Síncrono (200) / Asíncrono (202)
Raw Nativo	Recibe estructura `admissionRequest` y devuelve la respuesta JSON exacta de Yndika.	`/creditcheck/raw/electricidad`	Solo Síncrono (200)

⚡ Escenarios de Electricidad

Utiliza el endpoint /creditcheck. Primero consulta SIPS Electricidad; si falla, usa el CAE recibido o una estimación.

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

Para NIF/NIE. tipo_persona: "Física" es opcional y no altera la clasificación; autonomo decide entre Residencial y Autónomo.

Ejemplo de campos completos

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 (sin efecto en electricidad)
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. El prefijo del identificador se detecta como CIF. También, tipo_persona: "Jurídica" convierte un NIF declarado en CIF/Empresa.

Ejemplo de campos completos

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. Primero consulta SIPS Gas; cae sólo se usa como fallback si SIPS falla. Sin CAE se estima el consumo.

👤 Particular (Persona Física)

Para NIF/NIE. tipo_persona: "Física" es opcional y no altera la clasificación; autonomo decide entre Residencial y Autónomo.

Ejemplo de campos completos

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 (fallback de tarifa/CAE, 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. El prefijo del identificador se detecta como CIF. También, tipo_persona: "Jurídica" convierte un NIF declarado en CIF/Empresa.

Ejemplo de campos completos

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 (fallback de tarifa/CAE)
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": {"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`
Integración avanzada enviando estructura nativa y requiriendo el árbol completo de Yndika	`/creditcheck/raw/electricidad`

⚡ Modo Raw Nativo: `/creditcheck/raw/electricidad`

Este endpoint permite enviar directamente la estructura nativa de admisión (admissionRequest) y recibir como respuesta el JSON exacto y completo devuelto por Yndika (con RequestForAdmissionResult, GetAdmissionReportResult, EvaluationResult, etc.).

✨ Características clave del Modo Raw:

Estrictamente Síncrono: Responde inmediatamente HTTP 200. No admite callback_url (enviarlo provocará un error 400).
Respuesta Idéntica a Yndika: Devuelve la estructura nativa completa sin transformaciones ni envolturas adicionales.
Caché Transparente (30 días): Si existe una consulta previa en los últimos 30 días para el mismo NIF/CIF con importe compatible, se devuelve el JSON exacto previo almacenado en base de datos.

👤 Ejemplo: Persona Física (Residencial)

Debe incluir BirthDate (formato DD/MM/AAAA), RequestChannel y PostalCode en GeneralData.

POST /creditcheck/raw/electricidad
{
  "ServiceOperationParam": 3,
  "admissionRequest": {
    "OperationSpecificData": [
      {
        "VarValue": 850.40,
        "VarName": "internalTotalAmt",
        "VarFormat": 3,
        "VarDescription": "Importe total de la operación"
      },
      {
        "VarValue": "B2c",
        "VarName": "TipoEvaluacion",
        "VarFormat": 5,
        "VarDescription": "Tipo Evaluación"
      }
    ],
    "GeneralData": {
      "AdmissionPolicyId": 74384,
      "UsernameToken": "WSHanwhaAdmision",
      "Type": "Residencial",
      "FiscalId": "12345678Z",
      "DocumentType": "NIF",
      "CountryISO": "ES",
      "AdmissionType": 3,
      "ApplyNewAdmission": true,
      "BirthDate": "15/03/1985",
      "RequestChannel": "003",
      "PostalCode": "28001"
    }
  }
}

🏢 Ejemplo: Persona Jurídica (Empresa)

Debe incluir BusinessName (razón social) en GeneralData.

POST /creditcheck/raw/electricidad
{
  "ServiceOperationParam": 3,
  "admissionRequest": {
    "OperationSpecificData": [
      {
        "VarValue": 1932.15,
        "VarName": "internalTotalAmt",
        "VarFormat": 3,
        "VarDescription": "Importe total de la operación"
      },
      {
        "VarValue": "Retail",
        "VarName": "TipoEvaluacion",
        "VarFormat": 5,
        "VarDescription": "Tipo Evaluación"
      }
    ],
    "GeneralData": {
      "AdmissionPolicyId": 74384,
      "UsernameToken": "WSHanwhaAdmision",
      "Type": "Empresa",
      "FiscalId": "B86520418",
      "DocumentType": "CIF",
      "CountryISO": "ES",
      "AdmissionType": 3,
      "ApplyNewAdmission": true,
      "BusinessName": "TEST SL"
    }
  }
}

📥 Ejemplo de Respuesta HTTP 200 (Yndika Nativo)

{
  "RequestForAdmissionResult": {
    "Amount": 850.40,
    "Message": null,
    "RequestId": 101526079,
    "AdmissionData": {
      "FiscalId": "12345678Z",
      "Integrated": true,
      "AdmissionType": 3,
      "EntityCountryISO": "ES"
    },
    "GetAdmissionReportResult": {
      "EvaluationResult": {
        "Result": "Aprobar",
        "ResultCode": 1,
        "SuggestedCreditAmt": 850.40,
        "RequestedAmountAccepted": 850.40
      },
      "EvaluationFundation": {
        "ListResultFundaments": [
          {
            "FoundationIntSolvedText": "Se aprueba la operación por ser un cliente sin impagados en Bureau y con una calificación Delphi4 Medio"
          }
        ]
      }
    }
  }
}

📍 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 (200 o 202 Accepted)

Sin callback_url, recibes el resultado en el 200. Con callback_url, recibes un request_id en el 202.

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"
  },
  "_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.3 - Agosto 2026

🆕 Nuevo endpoint Raw nativo: Añadido /creditcheck/raw/electricidad para recibir la estructura de admisión nativa de Yndika (admissionRequest) y devolver su respuesta JSON exacta.
⚡ Modo estrictamente síncrono: El endpoint Raw responde de inmediato con HTTP 200 sin requerir ni admitir callbacks.
♻️ Unificación de Caché (30 días): Todos los endpoints de creditcheck verifican primero la existencia de consultas previas vigentes con importe compatible antes de invocar a proveedores externos.

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
📦 Resultado simplificado: La respuesta pública contiene el importe evaluado, el código y el texto del resultado.
🛡️ Manejo de errores mejorado: Códigos 4 con mensajes descriptivos en caso de timeout o errores de scoring

v1.0 - Formato Legacy (deprecado)

La estructura pública actual usa request_id, referencia_externa y result.codigo/result.texto.

Introducción

Campos y comportamiento efectivo

⚖️ Selecciona tu Escenario

Luz: Particular / Autónomo

Luz: Empresa (CIF)

Gas: Particular / Autónomo

Gas: Empresa (CIF)

Luz: Amount Directo

Gas: Amount Directo

Luz: Modo Raw Nativo

⚡ Escenarios de Electricidad

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

Ejemplo de campos completos

🟢 Aceptados (Opcionales)

🏢 Empresa / Sociedad (Persona Jurídica)

Ejemplo de campos completos

🟢 Aceptados (Opcionales)

🔥 Escenarios de Gas

👤 Particular (Persona Física)

Ejemplo de campos completos

🟢 Aceptados (Opcionales)

🏢 Empresa (Persona Jurídica)

Ejemplo de campos completos

🟢 Aceptados (Opcionales)

⚡ Endpoints SIN SIPS (Amount Directo)

⚡ Electricidad sin SIPS - /creditcheck_no_sips

👤 Ejemplo: Particular / Autónomo

🔴 Obligatorios

🟡 Recomendados

❌ NO Permitidos

🟢 Opcionales

🏢 Ejemplo: Empresa (Persona Jurídica)

🔴 Obligatorios

🟡 Recomendados

❌ NO Permitidos

🟢 Opcionales

🔥 Gas sin SIPS - /creditcheck_no_sips_gas

👤 Ejemplo: Particular

🏢 Ejemplo: Empresa

✅ Casos de Uso Recomendados

⚡ Modo Raw Nativo: /creditcheck/raw/electricidad

👤 Ejemplo: Persona Física (Residencial)

🏢 Ejemplo: Persona Jurídica (Empresa)

📥 Ejemplo de Respuesta HTTP 200 (Yndika Nativo)

📍 Referencia de Provincias

⚙️ Flujo Técnico

Solicitud (200 o 202 Accepted)

Procesamiento en Background

Callback

📬 Estructura del Resultado (Callback)

✅ Resultado Exitoso

📊 Posibles Valores de Resultado

⚠️ Ejemplo con Error

🔐 Seguridad del Callback - IMPORTANTE

💡 Campos del Resultado

📋 Changelog

v2.3 - Agosto 2026

v2.1 - Junio 2026

v2.0 - Mayo 2026

v1.0 - Formato Legacy (deprecado)

⚡ Electricidad sin SIPS - `/creditcheck_no_sips`

🔥 Gas sin SIPS - `/creditcheck_no_sips_gas`

⚡ Modo Raw Nativo: `/creditcheck/raw/electricidad`