Introducción

⚠️ Cambio Importante: El proceso de Credit Check es ahora exclusivamente asíncrono. Es obligatorio proporcionar una callback_url en todas las peticiones.

El Credit Check permite validar la solvencia de un cliente (residencial o empresa) antes de iniciar un contrato. Debido a que esta validación puede consultar servicios externos, se realiza en segundo plano para garantizar la estabilidad de la API.

El Flujo Asíncrono

1

Solicitud (Request)

Envías un POST a /creditcheck con los datos del cliente y tu URL de callback. 

POST /creditcheck
{
  "company_name": "Juan Pérez",
  "identificador": "12345678Z",
  "tipo_identificador": "NIF",
  "postal_code": "28001",
  "callback_url": "https://tu-sistema.com/webhooks/scoring",
  "referencia_externa": "SOLICITUD-99"
}
2

Respuesta Inmediata

La API responde con un 202 y un ID de seguimiento.

HTTP 202 Accepted
{
  "message": "Request is being processed asynchronously",
  "request_id": 1542
}
3

Recibo del Resultado (Callback)

Una vez completado el análisis, nuestro sistema llamará a tu URL de callback.

Ejemplos por Tipo de Cliente

🏠 Cliente Residencial (NIF/NIE)

{
  "company_name": "Nombre Apellido",
  "identificador": "12345678Z",
  "tipo_identificador": "NIF",
  "autonomo": false,
  "postal_code": "28001",
  "callback_url": "https://tu-api.com/callback"
}

🏢 Cliente Empresa (CIF)

{
  "company_name": "EMPRESA SL",
  "identificador": "B12345678",
  "tipo_identificador": "CIF",
  "autonomo": false,
  "postal_code": "08001",
  "callback_url": "https://tu-api.com/callback"
}

Cómo montar tu Endpoint de Callback

Tu sistema debe estar preparado para recibir una petición POST con el resultado. Todas las llamadas van firmadas con HMAC-SHA256 (ver Guía de Seguridad).

Estructura del Resultado Recibido

El cuerpo del POST enviado a tu callback_url incluirá el resultado detallado de la operación, incluyendo la referencia_externa para que puedas identificar la solicitud en tu sistema, los datos técnicos del suministro (SIPS) si están disponibles, y metadatos de firma para verificación automática.

POST https://tu-api.com/callback
{
  "request_id": 1542,
  "referencia_externa": "SOLICITUD-99",
  "credit_result": {
    "raw": {
    "code": "1008",
    "sips": {
      "CUPS": "ES0021000005451399XXXX",
      "ConsumoAnualKwh": 10672470,
      "CNAE": "9820",
      "TarifaATR": "018",
      "POT1": 5196,
      "POT2": 5196,
      "POT3": 0,
      "POT4": 0,
      "POT5": 0,
      "POT6": 0,
      "CP_PS": "28861",
      "Provincia_PS": "28",
      "CAE_P1": 1768590,
      "CAE_P2": 2103130,
      "CAE_P3": 6800750,
      "CAE_EST": false,
      "Periodos": 13,
      "TipoAutoconsumo": "41"
    },
    "error": "Experian error: Formato incorrecto del DNI/NIF/CIF en la trama de entrada"
  },
  "status_code": 500,
  "result_operation": "ERROR(Experian error: Formato incorrecto del DNI/NIF/CIF en la trama de entrada)",
  "_callback_signature": {
    "version": "v1",
    "algorithm": "HS256",
    "signature": "F9qDjHkLt5lO_JjiPvbP7_eJZeb_KTjTki5gDDNMrEM",
    "timestamp": "1772552356"
  }
}
🛡️ Verificación de Seguridad: Todas las peticiones de callback deben ser validadas utilizando el mecanismo de firma HMAC-SHA256 explicado detalladamente en el apartado /seguridad_callbacks.html. Puedes usar tanto los headers X-Signature como el nodo _callback_signature del body para realizar esta validación.

Ejemplo de Implementación (Python/Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/scoring', methods=['POST'])
def handle_scoring_callback():
    data = request.json
    
    # IMPORTANTE: Validar la firma HMAC antes de procesar
    # (ver pestaña de Seguridad)
    
    request_id = data.get('request_id')
    referencia = data.get('referencia_externa')
    resultado = data.get('credit_result', {}).get('result_operation') # Aprobado, Rechazado, Revisión Manual
    
    print(f"Resultado para request {request_id} (Ref: {referencia}): {resultado}")
    
    return jsonify({"status": "received"}), 200

Posibles Resultados (nodo result_operation)

A continuación se detallan los posibles valores que puede recibir el nodo result_operation en la respuesta del callback_url:

Resultado Descripción
Aprobado El cliente es apto para contratación inmediata.
Rechazado El riesgo es demasiado elevado. No se puede proceder.
Revisión Manual Se requiere revisión por parte de un agente de riesgos de Imagina Energía.
ERROR(detalles) Se produjo un error técnico durante la validación (ej: error de formato en Experian).