🔔 Notificaciones de Cambios en Contratos

¿Cómo funciona?

El sistema de notificaciones de cambios te permite recibir automáticamente webhooks cuando se producen cambios en contratos. Esto te evita tener que hacer polling constante y mantiene tus sistemas sincronizados en tiempo real.

📊 Estados y Subestados del Contrato

Los contratos pasan por diferentes estados durante su ciclo de vida. A continuación se describen todos los posibles estados y subestados que puede tener un contrato en Imagina Energía:

Estados del Contrato

🟡 Estado: Pendiente (ID: 1)

🔵 Estado: Activable (ID: 2)

🟢 Estado: Activo (ID: 3)

🔴 Estado: Cancelado (ID: 4)

⚫ Estado: Finalizado (ID: 5)

{
  "cambios": [
    {
      "campo": "Estado",
      "campo_tecnico": "id_estado",
      "valor_anterior": 2,
      "valor_nuevo": 3,
      "descripcion_anterior": "Pendiente",
      "descripcion_nueva": "Activable"
    },
    {
      "campo": "Subestado",
      "campo_tecnico": "id_subestado",
      "valor_anterior": 5,
      "valor_nuevo": 12,
      "descripcion_anterior": "Pendiente sin revisar",
      "descripcion_nueva": "Solicitado"
    }
  ]
}

📝 Paso 1: Suscribirse a Cambios

Cuando creas un contrato, puedes proporcionar tu endpoint para recibir notificaciones de cambios en las columnas monitorizadas por el sistema.

Ejemplo de petición de alta de contrato:

{
  "contrato": {
    "nombre": "Juan Pérez",
    "email": "juan@example.com",
    ...resto de campos del contrato...
  },
  "url_notificaciones_cambios_contrato": "https://tu-sistema.com/webhooks/contratos"
}

📬 Paso 2: Recibir Notificaciones

Cuando una columna monitorizada cambia, recibirás un POST en tu endpoint con el siguiente formato:

{
  "tabla": "contratos_suministro",
  "tipo_evento": "UPDATE",
  "timestamp": "2025-11-26T16:21:54.298664Z",
  "contrato": {
    "id": 543911,
    "codigo": "543911555"
  },
  "cambios": [
    {
      "campo": "Estado",
      "campo_tecnico": "id_estado",
      "valor_anterior": 2,
      "valor_nuevo": 3,
      "descripcion_anterior": "Pendiente",
      "descripcion_nueva": "Activable"
    },
    {
      "campo": "Subestado",
      "campo_tecnico": "id_subestado",
      "valor_anterior": 5,
      "valor_nuevo": 12,
      "descripcion_anterior": "Pendiente sin revisar",
      "descripcion_nueva": "Solicitado"
    }
  ],
  "_metadata": {
    "notification_id": 5,
    "attempt_number": 1
  },
  "_callback_signature": {
    "version": "v1",
    "algorithm": "HS256",
    "signature": "I85mBPGW1PQ92Upe6qrFnY-dzzw7_7wljgYURIGjcTw",
    "timestamp": "1764174114"
  }
}

⚙️ Paso 3: Implementar tu Endpoint

Tu endpoint debe:

• ✅ Aceptar peticiones POST
• ✅ Validar la firma HMAC-SHA256 (ver guía de seguridad)
• ✅ Responder con código 200-299 para confirmar recepción
• ✅ Procesar las notificaciones de forma idempotente (pueden llegar duplicadas)
• ✅ Responder rápidamente (<30s) para evitar timeouts

Ejemplo de implementación (Python/Flask):

from flask import Flask, request, jsonify

app = Flask(__name__)

# Cache para evitar procesar notificaciones duplicadas
notificaciones_procesadas = set()

@app.route('/webhooks/contratos', methods=['POST'])
def webhook_cambios_contratos():
    # 1. Validar firma HMAC-SHA256
    payload = request.get_json()
    signature = request.headers.get('X-Signature')
    timestamp = request.headers.get('X-Signature-Timestamp')
    
    if not validar_firma_callback(request.url, payload, signature, timestamp):
        print("❌ Firma inválida - Rechazando notificación")
        return jsonify({"error": "Firma inválida"}), 401
    
    # 2. Extraer metadata
    notification_id = payload.get('_metadata', {}).get('notification_id')
    attempt_number = payload.get('_metadata', {}).get('attempt_number')
    
    print(f"📥 Notificación recibida: ID={notification_id}, intento={attempt_number}")
    
    # 3. Evitar duplicados (idempotencia)
    if notification_id in notificaciones_procesadas:
        print(f"⚠️ Notificación {notification_id} ya procesada - Ignorando")
        return jsonify({"status": "ok", "message": "Duplicado"}), 200
    
    # 4. Procesar cambios
    contrato_id = payload['contrato']['id']
    contrato_codigo = payload['contrato']['codigo']
    cambios = payload['cambios']
    
    for cambio in cambios:
        campo = cambio['campo']  # Nombre legible: "Estado", "Subestado"
        campo_tecnico = cambio['campo_tecnico']  # Nombre técnico: "id_estado", "id_subestado"
        valor_nuevo = cambio['valor_nuevo']
        descripcion_nueva = cambio.get('descripcion_nueva')  # Descripción legible (si aplica)
        
        print(f"🔄 Contrato {contrato_codigo}: {campo} cambió a {valor_nuevo} ({descripcion_nueva})")
        
        # Aquí va tu lógica de negocio
        # Puedes usar tanto el ID numérico como la descripción
        if campo == 'Estado' and descripcion_nueva == 'Activo':
            activar_servicios_internos(contrato_codigo)
        elif campo == 'Subestado' and descripcion_nueva == 'Solicitado':
            notificar_switching_solicitado(contrato_codigo)
    
    # 5. Marcar como procesada
    notificaciones_procesadas.add(notification_id)
    
    # 6. Responder con éxito
    return jsonify({"status": "ok"}), 200

🔒 Seguridad

🔄 Sistema de Reintentos

Nuestro sistema garantiza la entrega de notificaciones mediante reintentos automáticos:

Ejemplo de flujo de reintentos:

💡 Mejores Prácticas

❓ Preguntas Frecuentes

if notification_id in notificaciones_procesadas:
    return {"status": "ok"}, 200  # Ya procesada, ignorar
notificaciones_procesadas.add(notification_id)