Bienvenido a la Documentación

Encuentra toda la información necesaria para integrar con las APIs de Imagina Energía. Potencia tu integración con nuestro enfoque asíncrono basado en eventos, diseñado para proporcionar la máxima estabilidad y escalabilidad en procesos de contratación y scoring.

¿Qué puedes hacer con nuestras APIs?

  • Consultar información detallada de contratos de suministro
  • Consultar tarifas disponibles por canal para uso en contratación
  • Crear nuevos contratos residenciales (C1, C2, A3) con validaciones completas
  • Crear nuevos contratos de empresa (C1, C2, A3) para personas jurídicas
  • Cargar y gestionar documentos asociados a contratos
  • Implementar autenticación segura con tokens JWT
  • Utilizar impersonación de canales para operaciones administrativas
  • Integrar webhooks para notificaciones asíncronas

📋 Changelog - Historial de Cambios

NUEVO v2.1 3 de Marzo, 2026

Credit Check Asíncrono Obligatorio

  • ⚖️ Cambio a modo asíncrono: El endpoint /creditcheck ahora procesa las peticiones en segundo plano para mayor estabilidad.
  • 🔗 Callback obligatorio: El campo callback_url es ahora obligatorio para recibir el resultado del scoring.
  • 📖 Nueva Guía: Se ha publicado una guía detallada con ejemplos de implementación del callback.
NUEVO v2.0 25 de Febrero, 2026

Endpoints de Contratación Universales (C1, C2, A3)

  • 🚀 Nuevos endpoints universales: /contrato/residencial y /contrato/empresa.
  • 💡 Soporte para C2 y A3: Añadidos campos es_alta_nueva, mismo_titular y misma_potencia para manejar cambios de titular, potencia y altas nuevas.
  • 🔄 Compatibilidad Backwards: Los endpoints que contienen /c1 en la URL se mantienen por compatibilidad, mapeando automáticamente a la nueva lógica universal.
NUEVO v1.9 25 de Febrero, 2026

Opciones de Inicio de Contrato

  • 🚀 Nuevo campo inicio_contrato: Permite elegir entre cuanto_antes o fecha_fija.
  • 📅 Nuevo campo fecha_inicio: Obligatorio cuando inicio_contrato es fecha_fija para indicar la fecha de comienzo del suministro.
NUEVO v1.8 24 de Febrero, 2026

Opciones de Firma en Contratos

  • 🔏 Nuevo campo no_enviar_firma: Si se indica como true, se elude el proceso de firma electrónica.
  • 📅 Requerimiento de fecha_firma_datos: Cuando no_enviar_firma es true, es obligatorio proporcionar la fecha de firma.
NUEVO v1.7 24 de Febrero, 2026

Endpoint de Credit Check

  • ⚖️ Nuevo endpoint POST /creditcheck: Realiza validaciones de scoring de forma independiente al flujo de contratación.
  • 🎯 Validación Síncrona: Obtén el resultado del scoring (ACCEPT, REJECT, MANUAL_REVIEW) de forma inmediata.
  • 📚 Documentación Interactiva: Disponible en Swagger UI con ejemplos de petición y respuesta.
NUEVO v1.6 29 de Enero, 2026

Mejoras en API de Contratos

  • 📝 Nuevo campo fecha_firma_datos: Permite indicar la fecha en la que el cliente ha firmado el contrato (formato YYYY-MM-DD). Campo opcional disponible en contratos residenciales y empresa
  • ⏰ Nuevo campo years_vigencia: Años de vigencia del contrato expresado en años enteros. Si no se especifica, se establece 1 año por defecto. Campo opcional disponible en contratos residenciales y empresa
  • 📋 Nuevo endpoint GET /contratos: Obtén un listado paginado de todos los contratos del canal con parámetros pagina y por_pagina
  • 🔄 Cambio en GET /contrato: El ID del contrato ahora se pasa como path parameter en la URL: /contrato/{id_contrato} en lugar de query parameter
v1.5 7 de Enero, 2026

Endpoint de Consulta de Tarifas

  • 💰 Nuevo endpoint GET /tarifas: Consulta el listado de tarifas disponibles para tu canal
  • ⚡ Respuesta síncrona: Obtén las tarifas inmediatamente sin callbacks ni esperas
  • 🔐 Soporte de impersonación: Consulta tarifas de otros canales con el header X-Canal
  • 📊 Auditoría completa: Cada petición se registra con request_id único para seguimiento
  • 🎯 Integración con contratos: Usa el id_tarifa en la creación de contratos residenciales y empresariales
  • 📚 Documentación completa: Guía detallada con ejemplos en curl y Python
  • 📖 Especificación OpenAPI: Archivo YAML disponible para generación de clientes
v1.4 25 de Noviembre, 2025

Sistema de Notificaciones de Cambios en Contratos

  • ✨ Notificaciones automáticas: Recibe webhooks cuando un contrato cambia de estado, subestado u otros campos monitorizados
  • 🔒 Sistema de firma unificado: Callbacks de contratación y notificaciones de cambios usan el mismo sistema HMAC-SHA256
  • 📚 Documentación de seguridad centralizada: Una única implementación de validación de firma para todos los webhooks
  • 🎯 Suscripción automática: Incluye url_notificaciones_cambios_contrato al crear un contrato
  • 📊 Auditoría completa: Todas las notificaciones enviadas se registran para trazabilidad
  • 🔄 Sistema de reintentos inteligente: Hasta 10 intentos automáticos cada 30 minutos si tu endpoint falla
  • 🏷️ Metadatos de seguimiento: Cada notificación incluye notification_id y attempt_number para trazabilidad
  • ♻️ Idempotencia facilitada: Los metadatos permiten detectar fácilmente notificaciones duplicadas
  • 📈 Visibilidad total: Sabes en qué intento estás y puedes implementar lógica diferenciada por número de reintento
v1.3 24 de Noviembre, 2025

Contratos Empresa C1

  • 🏢 Nuevo endpoint de contratos empresa C1: Ahora puedes dar de alta contratos para clientes empresariales
  • 📋 Validaciones específicas: Campos adaptados a las necesidades de clientes empresa (CIF, razón social, etc.)
  • 📚 Documentación actualizada: Ejemplos y casos de uso para contratación empresarial
v1.2 Noviembre, 2025

Mejoras en Documentación y API

  • 📚 Documentación completa de proceso de contratación con callbacks
  • 🔑 Guía mejorada de autenticación con ejemplos de impersonación
  • ⚡ Optimizaciones en el flujo asíncrono de alta de contratos
  • 🐛 Correcciones menores en validaciones de datos
v1.0 Octubre, 2025

Lanzamiento API Unificada

  • 🚀 Lanzamiento de la API unificada de contratación
  • 🏠 Endpoint de contratos residenciales C1
  • 📄 Sistema de gestión de documentos
  • 🔐 Autenticación JWT con impersonación de canales
  • 📚 Documentación interactiva OpenAPI