Versión 1 · Descargar contrato OpenAPI 3.1 · Volver a la aplicación
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.
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ón | REST | MCP | Alcance |
|---|---|---|---|
| Instalación y vinculación de cuadros | GET /point-installation · POST /changes/point_identify | puerto_instalacion_cuadro · puerto_preparar_identificar_equipo | Té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 incidencias | GET /incident-timeline | puerto_cronologia_incidencia | Evidencias 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 incidencias | GET /agenda | puerto_agenda | Agenda 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 cuadro | GET /confirmation-metrics | puerto_metricas_confirmacion | Lectura por rol y cuadro; solo tiempos registrados, no confirmación física de luminarias. |
| Pruebas de avisos por móvil | GET /mobile-tests | puerto_pruebas_moviles | Solo titular. Confirmar recepción humana y enviar prueba son acciones web, nunca se declaran por IA. |
| Franjas de servicio mínimo | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Técnico: propuesta de franjas y excepciones autorizadas. Validación compartida; no controla mandos físicos o externos. |
| Revisión instalada y plantilla disponible | Consulta en estados/configuración | Consulta en estados/configuración | Versión comunicada, fecha y vigencia. Desconocida no equivale a actualizada. No hay instalación remota por integraciones. |
| Diagnóstico por cuadro | GET /point-diagnostics | puerto_diagnostico_cuadro | Evidencias y comprobaciones sugeridas, sin inferir corte por falta de conexión. |
| Revisión previa conjunta | GET /stagger-preflight | puerto_prever_maniobra_conjunta | Rol con maniobras; no encola ni propone cambios. |
| Salud del servicio | GET /system-health | puerto_salud_sistema | Solo superadministrador; sin secretos ni comprobaciones activas. |
| Resumen de turno | Consulta disponible | Consulta disponible | Reúne incidencias sin cierre, plazos, mandos, próximas maniobras y órdenes caducadas. No prepara ni ejecuta cambios. |
| Estados, tensión y conexión | Sí | Sí | Pendiente de configurar no es desconexión ni avería. Las lecturas antiguas se identifican. |
| Ciclo de vida y ficha de cuadro | Consulta | Consulta | Estado, 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ón | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Consultar, 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 seguimiento | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Atenció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 informes | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Eventos/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 temporizadores | Con aprobación | Con aprobación | Operador 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ías | Con aprobación | Con aprobación | Té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 auxiliar | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Té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áticos | Con aprobación | Con aprobación | Secuencias propias: iniciar o cancelar pendientes. Técnico o superior: crear, reemplazar o eliminar grupos automáticos. |
| Mantenimiento y escalados | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Mantenimiento por técnico. Escalados y responsables por superadmin. Cambios con aprobación. |
| Bandeja de cambios pendientes | Consulta: GET /pending | Consulta: puerto_pendientes | Bandeja 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 confirmaciones | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Auditoría paginada por usuario, fecha, canal, cuadro y resultado para superadmin; confirmaciones y propuestas por ID. |
| Búsqueda y vistas personales guardadas | Solo web | Solo web | Cada usuario guarda y elimina sus filtros. Nunca amplían sus cuadros autorizados. |
| Centro de notificaciones y lectura | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Consultar avisos propios; proponer preferencias personales y marcado leído con credencial de cambios y aprobación. Leer no atiende la incidencia. |
| Vista previa de destinatarios | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Técnico consulta destinatarios reales de sus cuadros sin enviar avisos. |
| Archivo y restauración de registros | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Superadmin 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 HTTPS | Sonda pública mínima en health.php | puerto_salud_sistema (superadmin) | Monitor, push, resultado de copias y TLS por consulta superadmin; sin rutas ni secretos. |
| Wizard y administración de equipos | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Alta/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ía | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Superadmin 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 credenciales | Solo web | Solo web | Superadministrador 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 credenciales | Consulta de avisos propios | Consulta de avisos propios | Cron: 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 push | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Preferencias propias y destinatarios; registro push y pruebas de envío solo desde la web. |
| Gráfica diaria y fallos repetidos | Datos base; sin operación específica | Datos base; sin herramienta específica | Se pueden consultar históricos e incidencias; el análisis específico del panel no tiene operación pública propia. |
| Lotes de configuración | POST /changes/bulk | puerto_preparar_lote | Hasta 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 IA | Consulta / propuesta con aprobación según rol | Consulta / propuesta con aprobación según rol | Simulaciones sin persistencia; planes atómicos con aprobación personal; evidencias autenticadas y sesiones de la propia credencial |
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.
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"
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"}72 rutas. Todos los cambios requieren credencial autorizada y aprobación personal en la web; consulta /capabilities para tus herramientas efectivas.
| Método | Ruta bajo /api/v1 | Roles habilitados |
|---|---|---|
| GET | /point-installation | Técnico, Superadmin |
| GET | /incident-timeline | Consulta, Operador, Técnico, Superadmin |
| GET | /agenda | Consulta, Operador, Técnico, Superadmin |
| GET | /records | Consulta, Operador, Técnico, Superadmin |
| GET | /history-policy | Consulta, Operador, Técnico, Superadmin |
| GET | /calendar | Consulta, Operador, Técnico, Superadmin |
| GET | /notification-preferences | Consulta, Operador, Técnico, Superadmin |
| GET | /notification-recipients | Técnico, Superadmin |
| GET | /inventory | Técnico, Superadmin |
| GET | /audit | Superadmin |
| GET | /users | Superadmin |
| GET | /supervision-settings | Superadmin |
| GET | /history-export | Consulta, Operador, Técnico, Superadmin |
| GET | /point-comparison | Consulta, Operador, Técnico, Superadmin |
| POST | /changes/point_identify | Técnico, Superadmin |
| POST | /changes/calendar_save | Técnico, Superadmin |
| POST | /changes/calendar_delete | Técnico, Superadmin |
| POST | /changes/point_config | Técnico, Superadmin |
| POST | /changes/point_sync | Técnico, Superadmin |
| POST | /changes/service_policy | Técnico, Superadmin |
| POST | /changes/feedback | Técnico, Superadmin |
| POST | /changes/incident_plan | Operador, Técnico, Superadmin |
| POST | /changes/preferences | Operador, Técnico, Superadmin |
| POST | /changes/notification_read | Operador, Técnico, Superadmin |
| POST | /changes/point_create | Superadmin |
| POST | /changes/point_edit | Técnico, Superadmin |
| POST | /changes/point_retire | Superadmin |
| POST | /changes/point_restore | Superadmin |
| POST | /changes/settings | Superadmin |
| POST | /changes/escalation | Superadmin |
| POST | /changes/user_create | Superadmin |
| POST | /changes/user_edit | Superadmin |
| POST | /changes/user_status | Superadmin |
| POST | /changes/bulk | Técnico, Superadmin |
| GET | /ai/explained-diagnostics | Consulta, Operador, Técnico, Superadmin |
| POST | /ai/simulations | Consulta, Operador, Técnico, Superadmin |
| POST | /changes/schedule-plan | Técnico, Superadmin |
| GET | /ai/configuration-comparison | Consulta, Operador, Técnico, Superadmin |
| GET | /ai/timeline | Consulta, Operador, Técnico, Superadmin |
| GET | /ai/incident-investigation | Consulta, Operador, Técnico, Superadmin |
| GET | /ai/period-metrics | Consulta, Operador, Técnico, Superadmin |
| POST | /ai/evidence-report | Consulta, Operador, Técnico, Superadmin |
| GET | /ai/evidence | Consulta, Operador, Técnico, Superadmin |
| GET | /ai/change-status | Operador, Técnico, Superadmin |
| GET | /ai/session-history | Consulta, Operador, Técnico, Superadmin |
| GET | /shift-summary | Consulta, Operador, Técnico, Superadmin |
| GET | /point-diagnostics | Consulta, Operador, Técnico, Superadmin |
| GET | /stagger-preflight | Operador, Técnico, Superadmin |
| GET | /system-health | Superadmin |
| GET | /confirmation-metrics | Consulta, Operador, Técnico, Superadmin |
| GET | /mobile-tests | Consulta, Operador, Técnico, Superadmin |
| GET | /notifications | Consulta, Operador, Técnico, Superadmin |
| GET | /pending | Consulta, Operador, Técnico, Superadmin |
| GET | /capabilities | Consulta, Operador, Técnico, Superadmin |
| GET | /point-configuration | Consulta, Operador, Técnico, Superadmin |
| GET | /points | Consulta, Operador, Técnico, Superadmin |
| GET | /incidents | Consulta, Operador, Técnico, Superadmin |
| GET | /history | Consulta, Operador, Técnico, Superadmin |
| POST | /reports | Consulta, Operador, Técnico, Superadmin |
| POST | /changes/manual | Operador, Técnico, Superadmin |
| POST | /changes/schedule | Técnico, Superadmin |
| GET | /groups | Operador, Técnico, Superadmin |
| GET | /incident-detail | Consulta, Operador, Técnico, Superadmin |
| POST | /changes/group | Técnico, Superadmin |
| POST | /changes/group-delete | Técnico, Superadmin |
| POST | /changes/stagger | Operador, Técnico, Superadmin |
| POST | /changes/stagger-cancel | Operador, Técnico, Superadmin |
| POST | /changes/maintenance | Técnico, Superadmin |
| POST | /changes/incident-ack | Operador, Técnico, Superadmin |
| POST | /changes/incident-work | Operador, Técnico, Superadmin |
| GET | /changes/{request_id} | Operador, Técnico, Superadmin |
| POST | /changes/{request_id}/execute | Operador, Técnico, Superadmin |
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.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.
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.
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.