El trabajador consulta cada 24 horas, revisa siete días y recupera fechas pendientes.
Reserva SINCorte reciente · 22 Sep 2026
EmbalsesCorte reciente · 22 Sep 2026
GeneraciónDatos desactualizados · 20 Sep 2026
Protocolo público · versión 2.1.0
Del dato original a la visualización
Este documento describe exactamente cómo se solicitan, conservan, limpian, transforman y publican los datos. El objetivo es que otra persona pueda repetir el proceso, verificar una respuesta original y obtener el mismo resultado.
Zona horaria
America/BogotaMetodología en JSON
America/BogotaMetodología en JSON
Envía solicitudes POST deterministas a la API de XM.
Guarda la respuesta gzip y calcula su huella SHA-256.
Convierte fechas y decimales; no imputa valores faltantes.
Aplica fórmulas explícitas de porcentaje y generación.
Comprueba rangos, unidades, unicidad y resultado de la carga.
Sirve vistas y API desde la misma base histórica.
Adquisición
Solicitud reproducible a XM
Cada petición conserva endpoint, cuerpo JSON, rango temporal y hora de recepción. Las consultas diarias se dividen en bloques de 30 días; la generación, en bloques de 7 días.
POST https://servapibi.xm.com.co/daily
{
"MetricId": "PorcVoluUtilDiar",
"StartDate": "2026-08-22",
"EndDate": "2026-08-29",
"Entity": "Sistema"
}Evidencia primaria
Original comprimido + SHA-256
Antes de transformar, los bytes exactos recibidos se comprimen con gzip. La huella SHA-256 permite comprobar que el archivo descargado no cambió.
respuesta_original.json.gzSHA-256(bytes originales)La descarga pública se descomprime como JSON y expone la misma huella en el encabezado
X-Content-SHA256.Diccionario de transformación
Métricas, unidades y fórmulas
| Conjunto | Endpoint | MetricId / entidad | Unidad de entrada | Unidad pública | Fórmula |
|---|---|---|---|---|---|
| Reserva agregada del SIN | /daily | PorcVoluUtilDiarSistema | razón respecto a la capacidad de referencia; puede superar 1 | % | porcentaje = Value × 100 |
| Volumen útil por embalse | /daily | PorcVoluUtilDiarEmbalse | razón respecto a la capacidad de referencia; puede superar 1 | % | porcentaje útil = Value × 100 |
| Generación por recurso | /hourly | GeneRecurso | kWh por hora | GWh por día | GWh observados = suma de horas numéricas válidas ÷ 1.000.000; cobertura = horas válidas / 24 |
| Catálogo de recursos | /lists | ListadoRecursos— | catálogo | catálogo | Code enlaza cada lectura con Name y Type |
| Participación por tecnología | derivado de /hourly + /lists | Gene agrupada por TypeTecnología | GWh por recurso y día | % y GWh por tecnología | % tecnología = Σ GWh de la tecnología ÷ Σ GWh de todas las tecnologías × 100 |
Limpieza determinista
Reglas aplicadas
- La fecha se interpreta desde los primeros 10 caracteres ISO (AAAA-MM-DD).
- Los números se convierten con Decimal finito; NaN, infinito y valores fuera de rango se marcan inválidos.
- Los porcentajes útiles de XM son finitos y no negativos; pueden superar 100%. Se limita solo la precisión representable (9999,999%). La generación debe ser no negativa.
- Los recursos usan su código XM. Los embalses usan el nombre normalizado; los originales conservan la grafía de fuente y los cambios de nombre requieren correspondencias verificadas.
- Las claves únicas evitan duplicados. Repeticiones idénticas se consolidan; valores contradictorios para la misma entidad y fecha quedan inválidos, sin seleccionar un ganador por orden.
- La API diaria se consulta en bloques máximos de 30 días y generación en bloques de 7 días.
- Una hora vacía permanece nula. Las sumas parciales se conservan y etiquetan; un cero numérico sí es observado.
- La mezcla y el top usan el último corte disponible; se publican cobertura y tecnologías sin registro. No se asegura cobertura nacional.
- Las lecturas nuevas conservan lote, ejecución y versión; el histórico legacy puede carecer de original. Antes de corregir se conserva la revisión previa.
- La oficialización de la serie no se verifica en esta API; no se deduce de tener 24 horas numéricas.
Control de calidad
Comprobaciones
- Restricciones únicas en la base de datos.
- Validadores de rango y unidad.
- Registro de inicio, fin, resultado y filas procesadas en cada sincronización.
- Respuesta original comprimida con gzip y huella SHA-256 calculada sobre los bytes recibidos.
- Estado del trabajador automático y reintento una hora después de un fallo.
Transparencia
Limitaciones conocidas
- La fecha de publicación de XM puede ser posterior a la fecha observada.
- Se recargan siete días inclusivos y se recuperan huecos o rechazos. Cada semana se revisa además una ventana rotativa de hasta siete días dentro de los últimos 90. Las correcciones más antiguas requieren una revisión explícita.
- El promedio simple de embalses no equivale a la reserva agregada ponderada del SIN.
- Los umbrales son académicos, sin calibración o eficacia predictiva demostrada; el percentil es un rango histórico, no una probabilidad de crisis. No sustituyen declaraciones oficiales.
- Los lotes anteriores a la versión metodológica 1.0.0 no conservan respuesta original ni huella.
Registro auditable
Últimos lotes preservados
| Recepción | Métrica | Rango | Ítems | SHA-256 | Original |
|---|---|---|---|---|---|
| 24 Sep 2026 · 00:46:06 | Gene hourly · Recurso | 1995-01-01 → 1995-01-30 | 0 | 60e262252c9e18f2… | Descargar JSON |
| 24 Sep 2026 · 00:46:04 | Gene hourly · Recurso | 1995-01-31 → 1995-03-01 | 0 | dd85fbfd9d9aac9b… | Descargar JSON |
| 24 Sep 2026 · 00:46:03 | Gene hourly · Recurso | 1995-03-02 → 1995-03-31 | 0 | 08c222fbe8e0bd16… | Descargar JSON |
| 24 Sep 2026 · 00:46:01 | Gene hourly · Recurso | 1995-04-01 → 1995-04-30 | 0 | bd763b4a3132d4cc… | Descargar JSON |
| 24 Sep 2026 · 00:45:59 | Gene hourly · Recurso | 1995-05-01 → 1995-05-30 | 0 | 4209cd896ce96119… | Descargar JSON |
| 24 Sep 2026 · 00:45:57 | Gene hourly · Recurso | 1995-05-31 → 1995-06-29 | 0 | 11e31ef68e60011a… | Descargar JSON |
| 24 Sep 2026 · 00:45:55 | Gene hourly · Recurso | 1995-06-30 → 1995-07-29 | 0 | 499f6d5f14dd94fe… | Descargar JSON |
| 24 Sep 2026 · 00:45:54 | Gene hourly · Recurso | 1995-07-30 → 1995-08-28 | 0 | 6e4d676846697c23… | Descargar JSON |
| 24 Sep 2026 · 00:45:52 | Gene hourly · Recurso | 1995-08-29 → 1995-09-27 | 0 | 7f454d8ffb5469c0… | Descargar JSON |
| 24 Sep 2026 · 00:45:50 | Gene hourly · Recurso | 1995-09-28 → 1995-10-27 | 0 | 11ebf0fc376c9ead… | Descargar JSON |
| 24 Sep 2026 · 00:45:48 | Gene hourly · Recurso | 1995-10-28 → 1995-11-26 | 0 | ea2f743919d3fe5b… | Descargar JSON |
| 24 Sep 2026 · 00:45:47 | Gene hourly · Recurso | 1995-11-27 → 1995-12-26 | 0 | f48530b429f88a41… | Descargar JSON |
Verificación independiente
Cómo comprobar una huella
Descarga un lote desde la tabla y calcula su SHA-256 en PowerShell. El resultado debe coincidir con la huella completa publicada en el JSON metodológico.
Get-FileHash .\xm-lote.json -Algorithm SHA256
# Debe coincidir con:
GET /api/v1/metodologia/ → recent_batches[].sha256Repetición del proceso
Cómo reproducir la carga
Con la misma versión del código, parámetros y respuesta original, las transformaciones son deterministas. Los tests verifican fórmulas, API, alertas, bloqueos y vistas.
python manage.py migrate
python manage.py replay_xm --batch 9
python manage.py testCitación sugerida
HidroCol. Metodología y reproducibilidad, versión 2.1.0.Incluya fecha de consulta, URL de la vista o API, fecha observada del dato, fuente XM/EPM y SHA-256 del lote cuando esté disponible.
La reserva debe tener como máximo 3 días de antigüedad. La comparación de 30 días admite 3 días de tolerancia; se muestra el intervalo real. El percentil necesita 30 observaciones de al menos 2 años anteriores.
La reproducción desde un lote no consulta internet. Use una copia de la base y esta versión del código. La huella verifica igualdad con el original guardado, no una firma externa de XM.
Consultar revisiones y trazabilidad por lectura