API REST · Alumbrado del puerto

Versión 1 · Descargar contrato OpenAPI 3.1 · Volver a la aplicación

Interpretar los estados

Consulta status.code y connection_state. pending_configuration / never_connected significa pendiente de configurar o de primera señal: no es un fallo ni un corte. offline exige una comunicación anterior. connected=false se conserva por compatibilidad y no debe interpretarse aisladamente. Los valores *_reported son históricos; solo reading_is_current=true indica lecturas recientes.

local_enabled es la política solicitada. Solo schedule.confirmation_is_current confirma una comprobación reciente del horario real; schedule.enabled=false desactiva la programación completa. Los estados incluyen próxima maniobra con excepciones/escalonado/retorno temporal, calendario, instalación y auxiliar. Sin contacto auxiliar no se confirma físicamente el contactor.

GET /capabilities: permisos y herramientas efectivas de tu credencial. GET /point-configuration?point_id=1: consulta completa de configuración autorizada, sin secretos. El calendario, los ajustes avanzados, el inventario y los usuarios disponen de propuestas según rol. Contraseñas, tokens, wizard e instalación física permanecen en la web.

Cobertura actual del panel, API y MCP

Contrato REST 1.11.0 · MCP 1.12.0. Consulta GET /capabilities con tu credencial: tools contiene tus operaciones efectivas y coverage describe la cobertura global. Esta tabla no concede permisos.

lifecycle indica instalación, puesta en servicio, mantenimiento o retirada, independiente de la conexión. En incidencias, resolved_at es recuperación por telemetría; closed_at es cierre administrativo. next_action, due_at y el cierre se consultan y pueden proponerse por API/MCP con aprobación personal en la web.

FunciónRESTMCPAlcance
Instalación y vinculación de cuadrosGET /point-installation · POST /changes/point_identifypuerto_instalacion_cuadro · puerto_preparar_identificar_equipoTécnico/superadmin y cuadros asignados; propuesta con revisión y aprobación web. Altas y configuración básica en el servidor, sin conector Mac. Instalación inicial desde la LAN del equipo. Vigilante con descarga independiente y preparación local confirmada; sin secretos por IA.
Cronología de incidenciasGET /incident-timelinepuerto_cronologia_incidenciaEvidencias conservadas con paginación, autor y origen cuando constan; roles y cuadros autorizados. No reconstruye historia ausente ni expone contexto privado de auditoría.
Agenda de trabajo de incidenciasGET /agendapuerto_agendaAgenda paginada por cuadros autorizados, con estado técnico/plazo, responsables no disponibles, revisión, resumen global autorizado y diagnóstico push de página con privacidad. Editar planes/configurar recordatorios mantiene roles y confirmación; consultar no envía avisos.
Tiempos de confirmación por cuadroGET /confirmation-metricspuerto_metricas_confirmacionLectura por rol y cuadro; solo tiempos registrados, no confirmación física de luminarias.
Pruebas de avisos por móvilGET /mobile-testspuerto_pruebas_movilesSolo titular. Confirmar recepción humana y enviar prueba son acciones web, nunca se declaran por IA.
Franjas de servicio mínimoConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolTécnico: propuesta de franjas y excepciones autorizadas. Validación compartida; no controla mandos físicos o externos.
Revisión instalada y plantilla disponibleConsulta en estados/configuraciónConsulta en estados/configuraciónVersión comunicada, fecha y vigencia. Desconocida no equivale a actualizada. No hay instalación remota por integraciones.
Diagnóstico por cuadroGET /point-diagnosticspuerto_diagnostico_cuadroEvidencias y comprobaciones sugeridas, sin inferir corte por falta de conexión.
Revisión previa conjuntaGET /stagger-preflightpuerto_prever_maniobra_conjuntaRol con maniobras; no encola ni propone cambios.
Salud del servicioGET /system-healthpuerto_salud_sistemaSolo superadministrador; sin secretos ni comprobaciones activas.
Resumen de turnoConsulta disponibleConsulta disponibleReúne incidencias sin cierre, plazos, mandos, próximas maniobras y órdenes caducadas. No prepara ni ejecuta cambios.
Estados, tensión y conexiónSíSíPendiente de configurar no es desconexión ni avería. Las lecturas antiguas se identifican.
Ciclo de vida y ficha de cuadroConsultaConsultaEstado, instalación, puesta en servicio, mantenimiento, calendario, próxima maniobra y confirmación física cuando existe auxiliar. Las pestañas son organización de la web; la puesta en servicio se confirma desde ella.
Excepciones, próxima maniobra y sincronizaciónConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolConsultar, crear, editar o eliminar excepciones futuras con aprobación; valida solapes y servicio mínimo. Confirmación local independiente del guardado.
Incidencias y nuevos campos de seguimientoConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolAtención, responsable y notas; próxima acción, plazo, cierre y reapertura con aprobación. Cerrar exige recuperación y resolución; reabrir no falsifica telemetría.
Históricos e informesConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolEventos/lecturas por cursor; todos los históricos por /records y puerto_registros_historicos con page/page_size. /history-policy consulta el plazo configurable, 90 días por defecto. Permisos revalidados; asuntos abiertos conservados. La conservación se filtra antes de la limpieza.
Maniobras y temporizadoresCon aprobaciónCon aprobaciónOperador o superior y credencial con cambios. Solo mandos manuales pueden confirmar en IA si superadmin habilita la credencial; otros cambios requieren web. No ofrece retorno anticipado al horario. Recibida, relé confirmado y contactor confirmado son conceptos distintos. Las órdenes vencidas no se reenvían; el agente 5.2 verifica el plazo antes de conmutar.
Horarios fijos, solares y díasCon aprobaciónCon aprobaciónTécnico o superior. Revisión antes/después y aprobación personal; guarda en el equipo por política obligatoria, pero no afirma instalación hasta verificación.
Umbrales, recuperación y auxiliarConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolTécnico: umbrales y recuperación. Configuración de contacto auxiliar por técnico con permiso de equipos. Sin confirmación física hasta señal real.
Escalonado manual y grupos automáticosCon aprobaciónCon aprobaciónSecuencias propias: iniciar o cancelar pendientes. Técnico o superior: crear, reemplazar o eliminar grupos automáticos.
Mantenimiento y escaladosConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolMantenimiento por técnico. Escalados y responsables por superadmin. Cambios con aprobación.
Bandeja de cambios pendientesConsulta: GET /pendingConsulta: puerto_pendientesBandeja agregada paginada de instalación, sincronización, mandos temporales, órdenes y propuestas/secuencias propias, con responsable del siguiente paso. Consultar no aprueba ni ejecuta cambios. No incluye borradores del navegador.
Registro de cambios y confirmacionesConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolAuditoría paginada por usuario, fecha, canal, cuadro y resultado para superadmin; confirmaciones y propuestas por ID.
Búsqueda y vistas personales guardadasSolo webSolo webCada usuario guarda y elimina sus filtros. Nunca amplían sus cuadros autorizados.
Centro de notificaciones y lecturaConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolConsultar avisos propios; proponer preferencias personales y marcado leído con credencial de cambios y aprobación. Leer no atiende la incidencia.
Vista previa de destinatariosConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolTécnico consulta destinatarios reales de sus cuadros sin enviar avisos.
Archivo y restauración de registrosConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolSuperadmin consulta, retira o restaura cuadros conservando histórico; invalida vinculación y requiere nueva instalación web. No modifica el equipo físico.
Salud, copias y HTTPSSonda pública mínima en health.phppuerto_salud_sistema (superadmin)Monitor, push, resultado de copias y TLS por consulta superadmin; sin rutas ni secretos.
Wizard y administración de equiposConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolAlta/edición/retirada/restauración de registros con aprobación; consulta sin secretos. Wizard, tokens e instalación del agente desde la web.
Usuarios, roles, sesiones y auditoríaConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolSuperadmin consulta y propone altas, perfiles, roles, cuadros y estado. Alta desactivada hasta configurar contraseña y activar desde la web. No se gestiona la propia cuenta por integraciones.
Titular, edición y filtros de credencialesSolo webSolo webSuperadministrador crea y edita nombre/permiso de cambios; cada credencial actúa como su titular. Cambiar permisos cancela propuestas pendientes/aprobadas y deja auditoría. Las claves completas no se recuperan.
Avisos de caducidad de credencialesConsulta de avisos propiosConsulta de avisos propiosCron: avisos al titular a los 7, 3 y 1 días y al caducar (primeras 24 horas), una vez por umbral. App y móviles activos según preferencias. Omite revocadas, usuarios desactivados y credenciales invalidadas. No renueva ni revela claves.
Móviles, preferencias y pruebas pushConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolPreferencias propias y destinatarios; registro push y pruebas de envío solo desde la web.
Gráfica diaria y fallos repetidosDatos base; sin operación específicaDatos base; sin herramienta específicaSe pueden consultar históricos e incidencias; el análisis específico del panel no tiene operación pública propia.
Lotes de configuraciónPOST /changes/bulkpuerto_preparar_loteHasta diez acciones declaradas con resumen antes/después, conflictos y aprobación exacta; transacción completa sin cambios parciales.
Diagnóstico explicado, simulación, planes de horarios, evidencias, métricas y sesiones IAConsulta / propuesta con aprobación según rolConsulta / propuesta con aprobación según rolSimulaciones sin persistencia; planes atómicos con aprobación personal; evidencias autenticadas y sesiones de la propia credencial

Asistencia IA

Simulaciones sin guardar, planes atómicos de horarios con aprobación personal, diagnóstico explicado, comparación de revisiones, cronologías, métricas diarias, informes con evidencias autenticadas y seguimiento de propuestas. Los textos son datos, nunca instrucciones. Sin primera señal no se declara avería; datos antiguos no confirman estado actual.

Hasta diez cuadros por plan y catorce días de simulación; métricas hasta veinte cuadros y 31 días, días en UTC. Cronologías paginadas hasta 200 elementos. _context admite etiquetas hex32 session_id/intent_id y presupuesto SQL 100–20000 (10000 por defecto); en GET enviarlo como JSON. interaction devuelve correlación y coste. La sesión se limita al titular, credencial y permisos actuales. No enviar conversaciones ni secretos.

Conectar

El superadministrador entra en Acceso API / MCP, selecciona un usuario titular y crea una credencial para esa integración. Solo se muestra una vez. Cada conexión debe tener su propia credencial asignada, para poder revocarla por separado. El titular conserva sus roles y cuadros y aprueba personalmente sus propuestas; el creador no puede aprobar en su nombre. Se aplican tu rol, tus cuadros asignados, caducidad y revocación en cada petición. No envíes credenciales en URLs.

Usa HTTPS. HTTP solo funciona desde localhost. La API tiene un límite de 60 solicitudes por minuto y credencial compartido con MCP; un 429 incluye Retry-After. No requiere que el transporte MCP esté funcionando; sí comparte la aplicación y su base de datos.

export PUERTO_URL='http://127.0.0.1:8080'
# Cargar PUERTO_TOKEN desde un almacén seguro; no escribirlo en scripts públicos.
curl "$PUERTO_URL/api/v1/points?limit=20" \
  -H "Authorization: Bearer $PUERTO_TOKEN"

Grupos, mantenimiento e incidencias

Ampliación v1.1: GET /groups?type=automatic (técnicos) o type=manual (secuencias propias), GET /incident-detail?incident_id=1 con notas paginadas por before_note_id.

Propuestas POST: /changes/group (crear o reemplazar grupo completo: id, name, enabled, point_ids ordenados, interval_seconds); /changes/group-delete (group_id); /changes/stagger (point_ids, interval_seconds); /changes/stagger-cancel (batch_id); /changes/maintenance (point_id, minutes, reason; minutes=0 finaliza); /changes/incident-ack (incident_id, note); /changes/incident-work (incident_id, assigned_to, note, resolution). assigned_to=0 quita responsable; omitirlo conserva.

Todos devuelven una propuesta sin persistir efectos operativos. Se aprueba personalmente en confirmation_url y se ejecuta con el mismo POST /changes/{request_id}/execute y objeto vacío. Operadores: secuencias manuales e incidencias. Técnicos/superadmin: también grupos automáticos y mantenimiento. No fuerza la recuperación de una incidencia activa; para documentar resolución debe haberse recuperado. Al cancelar secuencias no se revierten órdenes ya encoladas. Se revalidan todos los cuadros, el grupo, los responsables y el estado de la incidencia.

POST /api/v1/changes/group
{"name":"P1 P2 P3","enabled":true,"point_ids":[1,2,3],"interval_seconds":120}

POST /api/v1/changes/maintenance
{"point_id":1,"minutes":30,"reason":"Revisión del cuadro"}

POST /api/v1/changes/incident-work
{"incident_id":1,"assigned_to":2,"note":"Comprobación asignada"}

Operaciones

72 rutas. Todos los cambios requieren credencial autorizada y aprobación personal en la web; consulta /capabilities para tus herramientas efectivas.

MétodoRuta bajo /api/v1Roles habilitados
GET/point-installationTécnico, Superadmin
GET/incident-timelineConsulta, Operador, Técnico, Superadmin
GET/agendaConsulta, Operador, Técnico, Superadmin
GET/recordsConsulta, Operador, Técnico, Superadmin
GET/history-policyConsulta, Operador, Técnico, Superadmin
GET/calendarConsulta, Operador, Técnico, Superadmin
GET/notification-preferencesConsulta, Operador, Técnico, Superadmin
GET/notification-recipientsTécnico, Superadmin
GET/inventoryTécnico, Superadmin
GET/auditSuperadmin
GET/usersSuperadmin
GET/supervision-settingsSuperadmin
GET/history-exportConsulta, Operador, Técnico, Superadmin
GET/point-comparisonConsulta, Operador, Técnico, Superadmin
POST/changes/point_identifyTécnico, Superadmin
POST/changes/calendar_saveTécnico, Superadmin
POST/changes/calendar_deleteTécnico, Superadmin
POST/changes/point_configTécnico, Superadmin
POST/changes/point_syncTécnico, Superadmin
POST/changes/service_policyTécnico, Superadmin
POST/changes/feedbackTécnico, Superadmin
POST/changes/incident_planOperador, Técnico, Superadmin
POST/changes/preferencesOperador, Técnico, Superadmin
POST/changes/notification_readOperador, Técnico, Superadmin
POST/changes/point_createSuperadmin
POST/changes/point_editTécnico, Superadmin
POST/changes/point_retireSuperadmin
POST/changes/point_restoreSuperadmin
POST/changes/settingsSuperadmin
POST/changes/escalationSuperadmin
POST/changes/user_createSuperadmin
POST/changes/user_editSuperadmin
POST/changes/user_statusSuperadmin
POST/changes/bulkTécnico, Superadmin
GET/ai/explained-diagnosticsConsulta, Operador, Técnico, Superadmin
POST/ai/simulationsConsulta, Operador, Técnico, Superadmin
POST/changes/schedule-planTécnico, Superadmin
GET/ai/configuration-comparisonConsulta, Operador, Técnico, Superadmin
GET/ai/timelineConsulta, Operador, Técnico, Superadmin
GET/ai/incident-investigationConsulta, Operador, Técnico, Superadmin
GET/ai/period-metricsConsulta, Operador, Técnico, Superadmin
POST/ai/evidence-reportConsulta, Operador, Técnico, Superadmin
GET/ai/evidenceConsulta, Operador, Técnico, Superadmin
GET/ai/change-statusOperador, Técnico, Superadmin
GET/ai/session-historyConsulta, Operador, Técnico, Superadmin
GET/shift-summaryConsulta, Operador, Técnico, Superadmin
GET/point-diagnosticsConsulta, Operador, Técnico, Superadmin
GET/stagger-preflightOperador, Técnico, Superadmin
GET/system-healthSuperadmin
GET/confirmation-metricsConsulta, Operador, Técnico, Superadmin
GET/mobile-testsConsulta, Operador, Técnico, Superadmin
GET/notificationsConsulta, Operador, Técnico, Superadmin
GET/pendingConsulta, Operador, Técnico, Superadmin
GET/capabilitiesConsulta, Operador, Técnico, Superadmin
GET/point-configurationConsulta, Operador, Técnico, Superadmin
GET/pointsConsulta, Operador, Técnico, Superadmin
GET/incidentsConsulta, Operador, Técnico, Superadmin
GET/historyConsulta, Operador, Técnico, Superadmin
POST/reportsConsulta, Operador, Técnico, Superadmin
POST/changes/manualOperador, Técnico, Superadmin
POST/changes/scheduleTécnico, Superadmin
GET/groupsOperador, Técnico, Superadmin
GET/incident-detailConsulta, Operador, Técnico, Superadmin
POST/changes/groupTécnico, Superadmin
POST/changes/group-deleteTécnico, Superadmin
POST/changes/staggerOperador, Técnico, Superadmin
POST/changes/stagger-cancelOperador, Técnico, Superadmin
POST/changes/maintenanceTécnico, Superadmin
POST/changes/incident-ackOperador, Técnico, Superadmin
POST/changes/incident-workOperador, Técnico, Superadmin
GET/changes/{request_id}Operador, Técnico, Superadmin
POST/changes/{request_id}/executeOperador, Técnico, Superadmin

Cambiar con confirmación

  1. Prepara la propuesta. Todavía no cambia el equipo.
  2. Presenta summary y consulta confirmation_mode. En web, el titular aprueba personalmente en confirmation_url. En ai, solo para mandos manuales habilitados por el superadministrador, pide confirmación explícita en la conversación; después ejecuta con {"confirm":true,"confirmation_token":"TOKEN_RECIBIDO"}. El token solo se devuelve al preparar, caduca con la propuesta y no se vuelve a mostrar. El servidor registra la declaración del cliente; no verifica la conversación.
  3. Consulta la propuesta y ejecuta con la misma credencial: objeto vacío para aprobación web; confirmación y token para modo IA. Caduca a los cinco minutos; cambios del cuadro, revocación o pérdida de permisos pueden invalidarla. Puedes cancelar desde la web.
curl "$PUERTO_URL/api/v1/changes/manual" \
 -H "Authorization: Bearer $PUERTO_TOKEN" -H 'Content-Type: application/json' \
 --data '{"point_id":1,"on":true,"minutes":30}'

# Tras aprobación personal en la web (ID devuelto por la preparación):
curl "$PUERTO_URL/api/v1/changes/ID_DEVUELTO/execute" \
 -H "Authorization: Bearer $PUERTO_TOKEN" -H 'Content-Type: application/json' --data '{}'

# Propuesta de horario, hora de Canarias; días 1=lunes … 7=domingo:
curl "$PUERTO_URL/api/v1/changes/schedule" \
 -H "Authorization: Bearer $PUERTO_TOKEN" -H 'Content-Type: application/json' \
 --data '{"point_id":1,"on_time":"19:30","off_time":"07:00","days":[1,2,3,4,5,6,7],"enabled":true}'

Reintentar la misma ejecución devuelve el resultado previo sin duplicar la orden. pending_device significa orden encolada; saved_pending_sync significa horario guardado pendiente del equipo. Ninguno confirma que las luces se hayan encendido físicamente.

Consultas, informes y errores

Respuesta: {generated_at, timezone, data}. Estados paginan con next_after_id; históricos e incidencias con next_before_id. Envía el cursor como after_id o before_id, manteniendo los filtros. Una página admite hasta 200 elementos.

Fechas from y to: ISO 8601 con zona, intervalo [inicio, fin). Históricos: siete días por defecto. Informes: treinta días; máximo 366 días y 100 cuadros. POST /reports acepta {"point_ids":[1],"from":"2026-10-01T00:00:00Z","to":"2026-10-16T00:00:00Z"} y devuelve datos y Markdown.

Sin telemetría reciente, tensión y relé actuales son null; las últimas lecturas quedan en los campos *_reported. Desconexión no demuestra corte eléctrico. Los informes de alumbrado no calculan kWh ni gasto.

Errores: {"error":{"code":"forbidden","message":"…","request_id":"…"}}. 401 credencial, 403 permisos, 404 recurso no accesible, 409 conflicto o aprobación pendiente, 422 parámetros inválidos, 429 límite. Todos los POST requieren objeto JSON y Content-Type application/json, máximo 64 KiB.

Despliegue en Hestia

Publica public/ como raíz web, configura api_allowed_hosts y, solo si corresponde, api_allowed_origins en config.local.php. Apache utiliza el .htaccess incluido. En Nginx configura la ruta para enviar /api/v1/* a /api/v1/index.php, conservando URI, SCRIPT_FILENAME y Authorization. Comprueba las rutas protegidas con un token de consulta antes de habilitar cambios. No expongas src/, var/ ni config.local.php.