Especificación de API · EPC Cajicá
Requerimientos de integración — Panel de Usuario
Contexto general. Estamos construyendo un portal web (frontend) que debe conectarse a los sistemas de EPC/Integra para mostrar y gestionar la información de los usuarios. Toda la data de negocio (cuentas, facturas, consumos, pagos) vive en Integra. Nosotros gestionamos únicamente la sesión del usuario y sus preferencias en nuestra propia base de datos.
Autenticación: Necesitamos un endpoint de login que valide al usuario contra Integra y retorne un token (JWT o similar) que el frontend usará en cada request.
Referencia visual (maqueta): werockagencia.github.io/EPC/panel/perfil.html — GitHub Pages estático, solo de referencia visual. Los datos reales vendrán de Integra.
Pregunta para Integra: ¿Existe un endpoint en el cual podamos autenticarnos contra Integra para obtener un token de acceso y gestionar la información del usuario? De existir, necesitamos: URL, método HTTP, campos requeridos (usuario, contraseña u otros), formato del token retornado, tiempo de duración del token y si existe mecanismo de refresh token.
Autenticación: Necesitamos un endpoint de login que valide al usuario contra Integra y retorne un token (JWT o similar) que el frontend usará en cada request.
Authorization: Bearer {token} en todos los endpoints del panel.Referencia visual (maqueta): werockagencia.github.io/EPC/panel/perfil.html — GitHub Pages estático, solo de referencia visual. Los datos reales vendrán de Integra.
Pregunta para Integra: ¿Existe un endpoint en el cual podamos autenticarnos contra Integra para obtener un token de acceso y gestionar la información del usuario? De existir, necesitamos: URL, método HTTP, campos requeridos (usuario, contraseña u otros), formato del token retornado, tiempo de duración del token y si existe mecanismo de refresh token.
01 · Perfil del usuario
Necesitamos consultar los datos básicos del cliente autenticado desde Integra. El campo canal de contacto (WhatsApp, Email, SMS, Llamada) es un campo adicional que, si no existe en Integra, lo manejaremos nosotros desde nuestra propia base de datos — no es bloqueante.
GET
/clientes/{clienteId}
Consulta datos del cliente autenticado
Campos que necesitamos
tipo_documentostringCC, CE, NIT…
numero_documentostring
nombrestring
apellidostring
emailstring
celularstring
Response esperado
"tipo_documento": "CC",
"numero_documento": "79512830",
"nombre": "David",
"apellido": "Higuera",
"email": "david@email.com",
"celular": "3001234567"
POST
/auth/cambiar-contrasena
Cambio de contraseña desde el perfil
contrasena_actualstringREQ
nueva_contrasenastringREQ
02 · Mis cuentas
Un usuario puede tener uno o más predios. El panel permite vincular nuevas cuentas, ver el detalle de cada una (titular, dirección, estrato, tipo de uso, medidores) y gestionar preferencias de notificación.
GET
/cuentas/{numeroCuenta}/verificar
Valida que la cuenta exista en Integra antes de vincularla
Query params
dvintegerREQDígito de verificación
numero_medidorstringOpcional si el usuario no lo tiene a la mano
Response 200 — cuenta encontrada
"cuenta_id": 1608353,
"titular": "Mercedes de Higuera",
"direccion": "DG 2 Sur No 12-150",
"estrato": 4,
"tipo_uso": "Residencial"
El frontend muestra una vista previa de la cuenta antes de confirmar la vinculación. Si no existe, retorna
404 con mensaje claro.
GET
/cuentas/{cuentaId}
Detalle completo de una cuenta
Datos que muestra el panel
titularstring
direccionstring
estratostring/int
tipo_usostringResidencial, Comercial, Agropecuario
medidoresarrayid + tipo (Principal / Secundario / Riego)
email_facturastringPara factura electrónica
direccion_notificacionstring
Response 200
"cuenta_id": 1608353,
"titular": "Mercedes de Higuera",
"direccion": "DG 2 Sur No 12-150",
"estrato": 4,
"tipo_uso": "Residencial",
"email_factura": "david@email.com",
"direccion_notif": "DG 2 Sur No 12-150",
"medidores": [
{"id": "MED-04471", "tipo": "Principal"},
{"id": "MED-04832", "tipo": "Secundario"}
]
POST
/cuentas/{cuentaId}/medidores
Agregar un medidor a una cuenta existente
numero_medidorstringREQ
tipostringREQPrincipal | Secundario | Riego
PUT
/cuentas/{cuentaId}/preferencias
Actualizar email de factura y dirección de notificación
email_facturastring
direccion_notificacionstring
Confirmar: ¿Estas preferencias se guardan en Integra o en nuestra base de datos? Si es en la nuestra, no necesitamos este endpoint del lado de Integra.
03 · Historial de facturación
Lista de facturas por cuenta con resumen de KPIs (última factura, próximo vencimiento, pendientes). Incluye descarga de PDF.
GET
/cuentas/{cuentaId}/facturas
Query params opcionales
aniointegerFiltrar por año
pageinteger
limitintegerDefault 20
Response 200
"resumen": {
"ultima_factura": 69320,
"proximo_vencimiento": "2026-08-13",
"pendientes": 1,
"total_anio": 789150
},
"facturas": [{
"factura_id": "403723943-5",
"fecha_expedicion": "2026-08-03",
"valor": 69320,
"fecha_vencimiento": "2026-08-13",
"estado": "emitida"
// emitida | pagada | vencida
}]
GET
/facturas/{facturaId}/pdf
Descarga del documento PDF
Debe retornar
Content-Type: application/pdf. El frontend hace fetch y dispara la descarga directamente.
Confirmar: ¿El PDF se genera en tiempo real o existe una URL de archivo por factura en Integra?
04 · Historial de consumo
Lecturas de los últimos 12 meses por medidor. El panel muestra un gráfico de barras con consumo actual, promedio y pico.
GET
/cuentas/{cuentaId}/consumo
Query params
medidor_idstringOpcional — filtra por medidor
mesesintegerDefault 12
Response 200
"medidor_id": "MED-04471",
"consumo_actual_m3": 9,
"promedio_12m": 13.5,
"pico": {"m3":22, "periodo":"2026-06"},
"lecturas": [
{"periodo":"2025-09", "m3":14},
// ... 11 registros más
]
05 · Historial de pagos
Registro de pagos realizados: número de documento, fecha, entidad (PSE, Bancolombia, Corresponsal), y monto.
GET
/cuentas/{cuentaId}/pagos
"pagos": [{
"numero_documento": "400189297",
"fecha": "2026-07-15",
"entidad": "PSE",
"valor": 114110,
"factura_id": "400189297-7"
}],
"total": 7
06 · Pagar factura
El pago lo gestiona Integra con sus propios métodos configurados (PSE, Bancolombia, etc.). Nosotros no manejamos la pasarela directamente: solo necesitamos una URL de redirección para enviar al usuario al flujo de pago de Integra.
GET
/facturas/{facturaId}/url-pago
Obtener el enlace de pago de Integra para esta factura
Lo que necesitamos en el response
url_pagostringURL a la que redirigimos al usuario
valorintegerMonto a pagar (para confirmar antes de redirigir)
vencimientodate
Response 200
"factura_id": "403723943-5",
"valor": 69320,
"vencimiento": "2026-08-13",
"url_pago": "https://integra.epc.gov.co/pagar/..."
El frontend muestra el monto y un botón "Pagar". Al confirmar, redirige al usuario a
url_pago. El flujo de pago completo (selección de banco, confirmación, recibo) lo maneja Integra.
07 · Radicar y consultar PQRS
El usuario puede radicar Peticiones, Quejas, Reclamos, Sugerencias y Denuncias, adjuntar soporte y hacer seguimiento del estado.
Pregunta para Integra:
¿Existe actualmente un endpoint disponible para consultar o radicar un PQR desde el portal hacia Integra? O ¿actualmente ese proceso se está gestionando por correo electrónico?
De existir un endpoint, necesitamos saber:
· URL del endpoint y método HTTP
· Campos requeridos (tipo, cuenta, asunto, descripción, adjunto)
· Formato del número de radicado que retorna
· Endpoint para consultar el estado de un radicado por su número
¿Existe actualmente un endpoint disponible para consultar o radicar un PQR desde el portal hacia Integra? O ¿actualmente ese proceso se está gestionando por correo electrónico?
De existir un endpoint, necesitamos saber:
· URL del endpoint y método HTTP
· Campos requeridos (tipo, cuenta, asunto, descripción, adjunto)
· Formato del número de radicado que retorna
· Endpoint para consultar el estado de un radicado por su número
| Tipo | Descripción |
|---|---|
| Petición | Solicitud de información o servicios |
| Queja | Inconformidad con la prestación del servicio |
| Reclamo | Inconformidad con cobros o facturación |
| Sugerencia | Propuesta de mejora |
| Denuncia | Reporte de irregularidades |
08 · Trámites en línea
El usuario puede radicar 5 tipos de trámite, cada uno con documentos específicos. Necesitamos que EPC/Integra confirme si existen endpoints para recibir estas solicitudes.
Pregunta para Integra: ¿Existen endpoints disponibles para radicar cada uno de estos trámites? Por cada uno necesitamos URL, método HTTP, parámetros requeridos y formato de respuesta (número de radicado). A continuación se detalla la información que el portal enviaría por cada tipo de solicitud.
POST
/tramites/reconexion
Solicitud de reconexión del servicio
Parámetros esperados
cuenta_idnumberREQ
numero_cedulastringREQ
numero_recibostringREQ
carta_solicitudfile (PDF)REQ
fotocopia_cedulafileREQ
fotocopia_recibofileREQ
Response esperado
"radicado": "TRM-2026-00421",
"estado": "recibido",
"fecha": "2026-09-03",
"tiempo_estimado": "5 días hábiles"
POST
/tramites/cambio-suscriptor
Transferencia de titularidad de la cuenta
cuenta_idnumberREQ
numero_cedulastringREQ
certificado_libertadfile (PDF)REQ
copia_recibo_aguafileREQ
fotocopia_cedulafileREQ
impuesto_predialfileREQ
POST
/tramites/suspension-temporal
Suspensión voluntaria del servicio
cuenta_idnumberREQ
numero_cedulastringREQ
carta_solicitudfile (PDF)REQ
fotocopia_cedulafileREQ
ultimo_recibo_canceladofileREQ
POST
/tramites/actualizacion-estrato
Cambio de estrato por reclasificación oficial
cuenta_idnumberREQ
numero_cedulastringREQ
certificacion_estratificacionfile (PDF)REQ
copia_factura_serviciosfileREQ
impuesto_predialfileREQ
fotocopia_cedulafileREQ
POST
/tramites/actualizacion-nomenclatura
Actualización de dirección por cambio oficial
cuenta_idnumberREQ
numero_cedulastringREQ
certificacion_nomenclaturafile (PDF)REQ
copia_factura_serviciosfileREQ
Todos los trámites envían archivos como
multipart/form-data. El response debe incluir al menos el número de radicado y el estado inicial. Si Integra tiene una URL de seguimiento por radicado, incluirla también.
Preguntas abiertas para EPC / Integra
Necesitamos que Integra confirme, por cada punto, si cuentan con el endpoint disponible o si requiere desarrollo nuevo.
| # | Pregunta | Módulo |
|---|---|---|
| 1 | ¿Existe un endpoint de autenticación en Integra para obtener un token de acceso? ¿Cuánto tiempo dura el token? ¿Hay refresh token? | Auth |
| 2 | ¿El DV en "Agregar cuenta" es el dígito verificador del número de cuenta o un PIN separado? | Mis cuentas |
| 3 | ¿Las preferencias de notificación (email factura, dirección) se guardan en Integra o en nuestra BD? | Mis cuentas |
| 4 | ¿El PDF de factura se genera en tiempo real o hay una URL de archivo por factura? | Facturación |
| 5 | ¿Integra provee una URL de redirección al flujo de pago por factura? ¿Cómo confirmamos que el pago fue exitoso? | Pagar factura |
| 6 | ¿Existe un endpoint disponible para consultar o radicar PQRs? ¿O actualmente ese proceso se gestiona por correo electrónico? | PQRS |
| 7 | ¿Existen endpoints para radicar los 5 tipos de trámite (reconexión, cambio suscriptor, suspensión, estrato, nomenclatura)? ¿O requieren desarrollo nuevo? | Trámites |
| 8 | ¿Cuál es la base URL del API en staging y producción? ¿Hay restricciones de CORS o se requiere IP fija? | General |