{ "openapi": "3.0.0", "info": { "title": "API Sistema de Mantenimiento de Peajes - MACROGRAM", "description": "API REST para el Sistema de Gestión de Mantenimiento de Equipos de Peajes en Ecuador.\n\n## Descripción General\nEste sistema permite la digitalización completa del flujo de mantenimientos de equipos en estaciones de peaje,\ncon capacidades offline-first para la aplicación móvil Flutter y tracking GPS en tiempo real.\n\n## Flujo de Estados de Mantenimiento\n1. PROGRAMADO - Mantenimiento agendado en calendario\n2. CAMINO_PEAJE - Técnico en ruta hacia el peaje\n3. LLEGADA_PEAJE - Técnico llegó al peaje (verificado GPS)\n4. EN_MANTENIMIENTO - Trabajo en progreso\n5. MANT_FINALIZADO - Trabajo técnico completado\n6. PEND_APROBACION - Esperando aprobación del Jefe Operativo\n7. APROBADO - Aprobado con QR+PIN\n8. RETORNO_INICIADO - Técnico regresando\n9. COMPLETADO - Mantenimiento finalizado\n\n## Autenticación\nTodos los endpoints (excepto login) requieren autenticación Bearer Token (Laravel Sanctum).\n\n## Roles del Sistema\n- SISTEMAS: Administrador total\n- GERENTE: Dashboard gerencial\n- ADMIN: Gestión operativa\n- PROGRAMADORES: Calendario de mantenimientos\n- MESA_AYUDA: Soporte y seguimiento\n- TECNICOS: Ejecución de mantenimientos\n- JEFE_OPERATIVO: Aprobación QR+PIN", "contact": { "name": "MACROGRAM Developer System", "email": "desarrollo@macrogram.ec" }, "license": { "name": "Propietario", "url": "https://macrogram.ec" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000", "description": "Servidor de Desarrollo Local" }, { "url": "https://api.macrogram.ec", "description": "Servidor de Producción" } ], "paths": { "/api/v1/alertas": { "get": { "tags": [ "Alertas" ], "summary": "Listar alertas", "description": "Obtiene alertas con filtros. Por defecto muestra activas y en proceso, ordenadas por prioridad", "operationId": "a08cdfe1c0a6e9762d04093ac5527010", "parameters": [ { "name": "estado", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVA", "EN_PROCESO", "RESUELTA", "IGNORADA" ] } }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "prioridad", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALTA", "MEDIA", "BAJA" ] } }, { "name": "fecha_desde", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "fecha_hasta", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "tecnico_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 5 } } ], "responses": { "200": { "description": "Lista de alertas", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "alertas": { "type": "array", "items": { "$ref": "#/components/schemas/Alerta" } }, "pagination": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/alertas/resumen": { "get": { "tags": [ "Alertas" ], "summary": "Resumen de alertas", "description": "Obtiene un resumen con contadores de alertas activas por prioridad, tipo y las 5 alertas más críticas", "operationId": "fb7292dcedac1aea79f5e34046316538", "responses": { "200": { "description": "Resumen de alertas", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "activas": { "properties": { "total": { "type": "integer" }, "alta": { "type": "integer" }, "media": { "type": "integer" }, "baja": { "type": "integer" } }, "type": "object" }, "en_proceso": { "type": "integer" }, "resueltas_hoy": { "type": "integer" }, "por_tipo": { "type": "object" }, "criticas": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/alertas/{id}": { "get": { "tags": [ "Alertas" ], "summary": "Ver detalle de alerta", "description": "Obtiene el detalle completo de una alerta incluyendo todas sus gestiones", "operationId": "5f23798fcfca12cb135b0758deac0a63", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalle de alerta", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "alerta": { "$ref": "#/components/schemas/Alerta" }, "mantenimiento": { "type": "object", "nullable": true }, "tecnico": { "type": "object", "nullable": true }, "resuelto_por": { "type": "object", "nullable": true }, "gestiones": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Alerta no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/alertas/{id}/gestionar": { "post": { "tags": [ "Alertas" ], "summary": "Gestionar alerta", "description": "Registra una acción de gestión sobre una alerta (llamada, mensaje, escalamiento, etc). Cambia automáticamente el estado a EN_PROCESO si estaba ACTIVA", "operationId": "e2087ad7e98e89c8d0e967be7c484013", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GestionarAlertaRequest" } } } }, "responses": { "201": { "description": "Gestión registrada exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "gestion_id": { "type": "integer" }, "alerta_estado": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "No se puede gestionar una alerta resuelta" }, "404": { "description": "Alerta no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/alertas/{id}/resolver": { "post": { "tags": [ "Alertas" ], "summary": "Resolver alerta", "description": "Marca una alerta como resuelta indicando la descripción de la resolución", "operationId": "3f60338aeb987122fd590b04b5476b3c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolverAlertaRequest" } } } }, "responses": { "200": { "description": "Alerta resuelta exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "alerta_id": { "type": "integer" }, "estado": { "type": "string" }, "fecha_resolucion": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "La alerta ya está resuelta" }, "404": { "description": "Alerta no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/pendientes": { "get": { "tags": [ "Aprobaciones" ], "summary": "Listar mantenimientos pendientes de aprobación", "description": "Obtiene todos los mantenimientos en estado PEND_APROBACION. Los Jefes Operativos solo ven los de sus peajes asignados", "operationId": "ceefa7898c0c2970599b6be1385ea29a", "parameters": [ { "name": "peaje_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "concesion_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista de pendientes de aprobación", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total": { "type": "integer" }, "pendientes": { "type": "array", "items": { "properties": { "prog_id": { "type": "integer" }, "fecha_programada": { "type": "string", "format": "date" }, "qr_code": { "type": "string" }, "qr_expira": { "type": "string", "format": "date-time" }, "qr_vigente": { "type": "boolean" }, "minutos_esperando": { "type": "integer" }, "tecnico": { "type": "object" }, "peaje": { "type": "object" }, "total_evidencias": { "type": "integer" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/{progId}/aprobar": { "post": { "tags": [ "Aprobaciones" ], "summary": "Aprobar mantenimiento con QR + PIN", "description": "Aprueba un mantenimiento validando el código QR del técnico y el PIN del Jefe Operativo. Usa el SP sp_aprobar_mantenimiento_qr", "operationId": "3f3b1a9d9c8f20451c84efa54684bc40", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AprobarMantenimientoRequest" } } } }, "responses": { "200": { "description": "Mantenimiento aprobado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "prog_id": { "type": "integer" }, "tipo": { "type": "string", "example": "APROBADO" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Error de validación QR/PIN", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" }, "data": { "properties": { "code": { "type": "string", "enum": [ "QR_INVALIDO", "QR_EXPIRADO", "PIN_INCORRECTO", "PIN_BLOQUEADO", "NO_AUTORIZADO", "ESTADO_INVALIDO" ] } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/{progId}/rechazar": { "post": { "tags": [ "Aprobaciones" ], "summary": "Rechazar mantenimiento", "description": "Rechaza un mantenimiento indicando el motivo. Solo Jefes Operativos del peaje o usuarios SISTEMAS/ADMINISTRACION", "operationId": "357627ebc993dc4d9cbfee0c018c62eb", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechazarMantenimientoRequest" } } } }, "responses": { "200": { "description": "Mantenimiento rechazado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "prog_id": { "type": "integer" }, "tipo": { "type": "string", "example": "RECHAZADO" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Estado no válido para rechazar" }, "403": { "description": "No autorizado para rechazar en este peaje" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/historial": { "get": { "tags": [ "Aprobaciones" ], "summary": "Historial de aprobaciones", "description": "Obtiene el historial de aprobaciones y rechazos con filtros. Jefes Operativos solo ven sus propias aprobaciones", "operationId": "08c2ed7a675ed74e0a4a5d9378790e7d", "parameters": [ { "name": "fecha_desde", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "fecha_hasta", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "APROBADO", "RECHAZADO" ] } }, { "name": "peaje_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 5 } } ], "responses": { "200": { "description": "Historial de aprobaciones", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "historial": { "type": "array", "items": { "$ref": "#/components/schemas/Aprobacion" } }, "pagination": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/{id}": { "get": { "tags": [ "Aprobaciones" ], "summary": "Ver detalle de aprobación", "description": "Obtiene el detalle completo de una aprobación incluyendo mantenimiento, técnico y evidencias", "operationId": "031a016ddae0e29bbf9285087b399649", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalle de aprobación", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "aprobacion": { "$ref": "#/components/schemas/Aprobacion" }, "mantenimiento": { "type": "object" }, "tecnico": { "type": "object" }, "jefe_operativo": { "type": "object" }, "evidencias": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Aprobación no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/jefes": { "get": { "tags": [ "Jefes Operativos" ], "summary": "Listar jefes operativos y asignaciones", "description": "Obtiene todas las asignaciones de Jefes Operativos a peajes", "operationId": "2001f74c08769966680c332d69d2289c", "parameters": [ { "name": "peaje_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista de asignaciones", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total": { "type": "integer" }, "asignaciones": { "type": "array", "items": { "properties": { "asignacion_id": { "type": "integer" }, "jefe": { "type": "object" }, "peaje": { "type": "object" }, "tiene_pin": { "type": "boolean" }, "pin_bloqueado": { "type": "boolean" }, "fecha_asignacion": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Jefes Operativos" ], "summary": "Asignar jefe operativo a peaje", "description": "Asigna un usuario con perfil JEFE_OPERATIVO a un peaje y configura su PIN", "operationId": "f5b1b46faa759e185a9122d42e971079", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsignarJefeRequest" } } } }, "responses": { "201": { "description": "Jefe operativo asignado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "asignacion_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Usuario ya asignado a este peaje" }, "422": { "description": "El usuario no tiene perfil JEFE_OPERATIVO" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/jefes/{id}/pin": { "put": { "tags": [ "Jefes Operativos" ], "summary": "Cambiar PIN de jefe operativo", "description": "Actualiza el PIN de una asignación de Jefe Operativo", "operationId": "d65657e143ae74d6dd57bac900d8b3c4", "parameters": [ { "name": "id", "in": "path", "description": "ID de la asignación", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "pin" ], "properties": { "pin": { "type": "string", "maxLength": 6, "minLength": 6, "pattern": "^[0-9]+$" } }, "type": "object" } } } }, "responses": { "200": { "description": "PIN actualizado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "asignacion_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Asignación no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/aprobaciones/jefes/{id}": { "delete": { "tags": [ "Jefes Operativos" ], "summary": "Desasignar jefe operativo de peaje", "description": "Elimina (soft delete) la asignación de un Jefe Operativo a un peaje", "operationId": "ae2892ca557bd85b7e435f2fa04b8422", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Jefe operativo desasignado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "asignacion_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Asignación no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/login": { "post": { "tags": [ "Autenticación" ], "summary": "Iniciar sesión", "description": "Autentica un usuario por cédula y devuelve un token Bearer", "operationId": "authLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login exitoso" }, "401": { "description": "Credenciales inválidas" } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Autenticación" ], "summary": "Cerrar sesión", "operationId": "authLogout", "responses": { "200": { "description": "Sesión cerrada" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/logout-all": { "post": { "tags": [ "Autenticación" ], "summary": "Cerrar todas las sesiones", "operationId": "authLogoutAll", "responses": { "200": { "description": "Todas las sesiones cerradas" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/me": { "get": { "tags": [ "Autenticación" ], "summary": "Obtener perfil del usuario autenticado", "operationId": "authMe", "responses": { "200": { "description": "Datos del usuario" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "Autenticación" ], "summary": "Solicitar recuperación de contraseña", "operationId": "authForgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "cedula": { "type": "string", "example": "1234567890" } }, "type": "object" } } } }, "responses": { "200": { "description": "Solicitud procesada" } } } }, "/api/v1/auth/reset-password": { "post": { "tags": [ "Autenticación" ], "summary": "Resetear contraseña con token", "operationId": "authResetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Contraseña actualizada" }, "400": { "description": "Token inválido" } } } }, "/api/v1/auth/change-password": { "post": { "tags": [ "Autenticación" ], "summary": "Cambiar contraseña", "operationId": "authChangePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Contraseña actualizada" }, "400": { "description": "Contraseña actual incorrecta" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/refresh": { "post": { "tags": [ "Autenticación" ], "summary": "Refrescar token", "operationId": "authRefresh", "responses": { "200": { "description": "Token renovado" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{progId}/evidencias": { "get": { "tags": [ "Evidencias" ], "summary": "Listar evidencias de un mantenimiento", "description": "Obtiene todas las evidencias activas asociadas a un mantenimiento específico", "operationId": "f08192149b4a8b2e07e9228c0cd36ad9", "parameters": [ { "name": "progId", "in": "path", "description": "ID del mantenimiento", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista de evidencias obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "prog_id": { "type": "integer" }, "total": { "type": "integer" }, "minimo_requerido": { "type": "integer", "example": 3 }, "cumple_minimo": { "type": "boolean" }, "evidencias": { "type": "array", "items": { "$ref": "#/components/schemas/Evidencia" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Evidencias" ], "summary": "Subir evidencia (archivo)", "description": "Sube una evidencia (foto, video o documento) para un mantenimiento. Solo permitido en estados: EN_MANTENIMIENTO, MANT_FINALIZADO, PEND_APROBACION", "operationId": "066e8e2c57813b5c3e35e353707bdaf9", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EvidenciaUploadRequest" } } } }, "responses": { "201": { "description": "Evidencia subida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "evidencia_id": { "type": "integer" }, "nombre_archivo": { "type": "string" }, "url": { "type": "string" }, "tipo": { "type": "string" }, "tamanio": { "type": "string" }, "total_evidencias": { "type": "integer" }, "cumple_minimo": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Estado no permitido para subir evidencias" }, "404": { "description": "Mantenimiento no encontrado" }, "422": { "description": "Error de validación" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{progId}/evidencias/base64": { "post": { "tags": [ "Evidencias" ], "summary": "Subir evidencia en Base64 (offline)", "description": "Sube una evidencia codificada en Base64. Ideal para sincronización desde la APP móvil cuando trabaja offline", "operationId": "52e10e118138cb6a04215ba7165253f7", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenciaBase64Request" } } } }, "responses": { "201": { "description": "Evidencia sincronizada exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "evidencia_id": { "type": "integer" }, "nombre_archivo": { "type": "string" }, "url": { "type": "string" }, "tipo": { "type": "string" }, "total_evidencias": { "type": "integer" }, "cumple_minimo": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Mantenimiento no encontrado" }, "422": { "description": "Archivo base64 inválido" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{progId}/evidencias/batch": { "post": { "tags": [ "Evidencias" ], "summary": "Subir múltiples evidencias en lote (batch)", "description": "Permite subir hasta 10 evidencias en una sola petición. Ideal para sincronización masiva desde la APP offline", "operationId": "60428b38718db7abc62bc253473fe9b9", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenciaBatchRequest" } } } }, "responses": { "200": { "description": "Procesamiento batch completado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "prog_id": { "type": "integer" }, "procesados": { "type": "integer" }, "exitosos": { "type": "integer" }, "fallidos": { "type": "integer" }, "resultados": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "local_id": { "type": "string" }, "success": { "type": "boolean" }, "evidencia_id": { "type": "integer" }, "url": { "type": "string" }, "error": { "type": "string" } }, "type": "object" } }, "total_evidencias": { "type": "integer" }, "cumple_minimo": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{progId}/evidencias/{evidenciaId}": { "get": { "tags": [ "Evidencias" ], "summary": "Ver detalle de evidencia", "description": "Obtiene los detalles completos de una evidencia específica", "operationId": "37a2da647954f0c713015d3f447cf82e", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "evidenciaId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalle de evidencia", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "evidencia": { "$ref": "#/components/schemas/Evidencia" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Evidencia no encontrada" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Evidencias" ], "summary": "Eliminar evidencia", "description": "Elimina (soft delete) una evidencia. No permitido para mantenimientos ya aprobados", "operationId": "ce16c6c0dfa17b3f402ccf8d5abbc018", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "evidenciaId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Evidencia eliminada exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "evidencia_id": { "type": "integer" }, "total_evidencias": { "type": "integer" }, "cumple_minimo": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "No se puede eliminar de mantenimientos aprobados" }, "404": { "description": "Evidencia no encontrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/gps/tracking": { "post": { "tags": [ "GPS Tracking" ], "summary": "Registrar posiciones GPS (batch)", "description": "Registra múltiples posiciones GPS del técnico. Ideal para sincronización desde la APP móvil. Usa el SP sp_registrar_posicion_gps", "operationId": "1656d1f93545005ba7e9bc44ec9921c4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrarGpsRequest" } } } }, "responses": { "200": { "description": "Posiciones registradas", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "recibidas": { "type": "integer" }, "registradas": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Error de validación" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/gps/tecnicos-activos": { "get": { "tags": [ "GPS Tracking" ], "summary": "Obtener técnicos activos (mapa tiempo real)", "description": "Obtiene la última posición conocida de todos los técnicos activos (última hora). Usa el SP sp_tracking_tecnicos_activos", "operationId": "74163948e4f991097440fe547e15953a", "responses": { "200": { "description": "Lista de técnicos activos con posición", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "tecnicos": { "type": "array", "items": { "$ref": "#/components/schemas/TecnicoActivo" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/gps/ruta/{progId}": { "get": { "tags": [ "GPS Tracking" ], "summary": "Obtener ruta GPS de un mantenimiento", "description": "Obtiene todos los puntos GPS registrados durante un mantenimiento, incluyendo cambios de estado y tracking continuo", "operationId": "8548a654936fcec7b1c8052bd5d63f01", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ruta del mantenimiento", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "mantenimiento": { "properties": { "prog_id": { "type": "integer" }, "fecha": { "type": "string", "format": "date" }, "tecnico": { "type": "string" } }, "type": "object" }, "peaje": { "properties": { "nombre": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "type": "object" }, "ruta": { "properties": { "total_puntos": { "type": "integer" }, "distancia_metros": { "type": "number" }, "distancia_km": { "type": "number" }, "puntos_estados": { "type": "array", "items": { "type": "object" } }, "puntos_tracking": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/gps/tecnico/{usuarioId}": { "get": { "tags": [ "GPS Tracking" ], "summary": "Obtener última posición de un técnico", "description": "Obtiene la última posición GPS conocida de un técnico específico junto con su mantenimiento activo si existe", "operationId": "1f5d0d2587a0f23cfd56cc351a952f85", "parameters": [ { "name": "usuarioId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Última posición del técnico", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "tecnico": { "properties": { "id": { "type": "integer" }, "nombre": { "type": "string" } }, "type": "object" }, "posicion": { "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "precision": { "type": "number" }, "altitud": { "type": "number" }, "velocidad": { "type": "number" }, "bateria": { "type": "integer" }, "fecha": { "type": "string", "format": "date-time" }, "minutos_desde_actualizacion": { "type": "integer" }, "es_reciente": { "type": "boolean" }, "bateria_baja": { "type": "boolean" } }, "type": "object" }, "mantenimiento_activo": { "properties": { "prog_id": { "type": "integer" }, "peaje": { "type": "string" }, "estado": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No hay posiciones registradas para este técnico" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos": { "get": { "tags": [ "Mantenimientos" ], "summary": "Listar mantenimientos", "description": "Lista mantenimientos asignados. Los técnicos solo ven sus mantenimientos asignados. Admins ven todos.", "operationId": "listarMantenimientos", "parameters": [ { "name": "fecha", "in": "query", "description": "Filtrar por fecha (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "estado_id", "in": "query", "description": "Filtrar por ID de estado", "schema": { "type": "integer" } }, { "name": "tecnico_id", "in": "query", "description": "Filtrar por técnico", "schema": { "type": "integer" } }, { "name": "concesion_id", "in": "query", "description": "Filtrar por concesión", "schema": { "type": "integer" } }, { "name": "peaje_id", "in": "query", "description": "Filtrar por peaje", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Registros por página (5-100)", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Lista de mantenimientos" }, "401": { "description": "No autenticado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/estados": { "get": { "tags": [ "Mantenimientos" ], "summary": "Listar estados de mantenimiento", "description": "Retorna todos los estados posibles del flujo de mantenimiento", "operationId": "listarEstadosMantenimiento", "responses": { "200": { "description": "Lista de estados" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/hoy": { "get": { "tags": [ "Mantenimientos" ], "summary": "Mantenimientos del día para el técnico", "description": "Retorna los mantenimientos programados para hoy del técnico autenticado", "operationId": "mantenimientosHoy", "responses": { "200": { "description": "Mantenimientos del día" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}": { "get": { "tags": [ "Mantenimientos" ], "summary": "Ver detalle de mantenimiento", "description": "Obtiene información completa del mantenimiento incluyendo historial, checklist, evidencias y aprobación", "operationId": "verMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalle del mantenimiento" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}/estado": { "put": { "tags": [ "Mantenimientos" ], "summary": "Cambiar estado del mantenimiento", "description": "Cambia el estado del mantenimiento. Usa el SP sp_cambiar_estado_mant. Requiere GPS para ciertos estados.", "operationId": "cambiarEstadoMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CambiarEstadoRequest" } } } }, "responses": { "200": { "description": "Estado actualizado" }, "400": { "description": "Error de validación o transición inválida" }, "403": { "description": "Sin permisos" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}/historial": { "get": { "tags": [ "Mantenimientos" ], "summary": "Obtener historial de estados", "description": "Retorna el historial de cambios de estado del mantenimiento con coordenadas GPS", "operationId": "historialMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Historial de estados" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}/checklist": { "get": { "tags": [ "Mantenimientos" ], "summary": "Obtener checklist del mantenimiento", "description": "Retorna el checklist de items a revisar por equipo con respuestas existentes", "operationId": "getChecklistMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist del mantenimiento" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Mantenimientos" ], "summary": "Guardar respuesta de checklist", "description": "Guarda una respuesta individual del checklist. Solo disponible en estado EN_MANTENIMIENTO.", "operationId": "guardarChecklistMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardarChecklistRequest" } } } }, "responses": { "200": { "description": "Checklist guardado" }, "400": { "description": "Estado incorrecto o error de validación" }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}/checklist/batch": { "post": { "tags": [ "Mantenimientos" ], "summary": "Guardar múltiples respuestas de checklist", "description": "Guarda múltiples respuestas del checklist en lote. Ideal para sincronización offline.", "operationId": "guardarChecklistBatch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Respuestas procesadas" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/mantenimientos/{id}/finalizar": { "post": { "tags": [ "Mantenimientos" ], "summary": "Finalizar mantenimiento", "description": "Finaliza el mantenimiento y genera código QR para aprobación. Requiere checklist 100% y mínimo 3 evidencias.", "operationId": "finalizarMantenimiento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "latitud", "longitud" ], "properties": { "latitud": { "type": "number", "format": "float", "example": -0.1807 }, "longitud": { "type": "number", "format": "float", "example": -78.4678 } }, "type": "object" } } } }, "responses": { "200": { "description": "Mantenimiento finalizado y QR generado" }, "400": { "description": "Requisitos no cumplidos" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/reportes/dashboard/gerencia": { "get": { "tags": [ "Reportes" ], "summary": "Dashboard Gerencia", "description": "Obtiene KPIs y métricas para el dashboard de gerencia: cumplimiento mensual, por concesión y evolución de últimos 6 meses. Usa el SP sp_dashboard_gerencia", "operationId": "86bcfebe87a918a020308ee5aed8a7aa", "parameters": [ { "name": "anio", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2030, "minimum": 2020 } }, { "name": "mes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 1 } }, { "name": "concesion_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Dashboard de gerencia", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "periodo": { "properties": { "anio": { "type": "integer" }, "mes": { "type": "integer" }, "nombre_mes": { "type": "string" } }, "type": "object" }, "kpis": { "properties": { "total_programados": { "type": "integer" }, "total_completados": { "type": "integer" }, "porcentaje_cumplimiento": { "type": "number" }, "alertas_activas": { "type": "integer" } }, "type": "object" }, "por_concesion": { "type": "array", "items": { "properties": { "concesion_id": { "type": "integer" }, "nombre": { "type": "string" }, "total": { "type": "integer" }, "completados": { "type": "integer" }, "porcentaje": { "type": "number" } }, "type": "object" } }, "evolucion_mensual": { "type": "array", "items": { "properties": { "mes": { "type": "string" }, "total": { "type": "integer" }, "completados": { "type": "integer" }, "porcentaje": { "type": "number" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/reportes/dashboard/admin": { "get": { "tags": [ "Reportes" ], "summary": "Dashboard Admin", "description": "Dashboard operativo para administradores: estado del día, técnicos activos, alertas críticas y QRs próximos a vencer. Usa el SP sp_dashboard_admin", "operationId": "a4026cc8b0b3a37bb35cbaadcbfcf4e1", "responses": { "200": { "description": "Dashboard de admin", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "fecha": { "type": "string", "format": "date" }, "hora": { "type": "string" }, "hoy": { "properties": { "programados": { "type": "integer" }, "por_estado": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "tecnicos_activos": { "type": "array", "items": { "type": "object" } }, "alertas": { "properties": { "total_activas": { "type": "integer" }, "criticas": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "proximos_vencer_qr": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/reportes/mantenimiento/{progId}/pdf": { "get": { "tags": [ "Reportes" ], "summary": "Datos para reporte PDF de mantenimiento", "description": "Obtiene todos los datos necesarios para generar el reporte PDF de un mantenimiento: historial, checklist, evidencias, tiempos y aprobación", "operationId": "121f7242f76e206cb364e70d558dfc54", "parameters": [ { "name": "progId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Datos del reporte", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "reporte": { "properties": { "generado_en": { "type": "string", "format": "date-time" }, "generado_por": { "type": "string" } }, "type": "object" }, "mantenimiento": { "type": "object" }, "ubicacion": { "type": "object" }, "tecnico": { "type": "object" }, "historial": { "type": "array", "items": { "type": "object" } }, "tiempos": { "properties": { "traslado_minutos": { "type": "integer" }, "espera_minutos": { "type": "integer" }, "ejecucion_minutos": { "type": "integer" }, "aprobacion_minutos": { "type": "integer" }, "total_minutos": { "type": "integer" } }, "type": "object" }, "checklist": { "type": "array", "items": { "type": "object" } }, "evidencias": { "type": "array", "items": { "type": "object" } }, "aprobacion": { "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Mantenimiento no encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/reportes/consolidado": { "get": { "tags": [ "Reportes" ], "summary": "Reporte consolidado", "description": "Genera un reporte consolidado con totales por estado, técnico y peaje para un período de fechas", "operationId": "58a2feb381ece375040cdc218b24f6e5", "parameters": [ { "name": "fecha_desde", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "fecha_hasta", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "concesion_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "peaje_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "tecnico_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reporte consolidado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "periodo": { "properties": { "desde": { "type": "string", "format": "date" }, "hasta": { "type": "string", "format": "date" } }, "type": "object" }, "resumen": { "properties": { "total": { "type": "integer" }, "completados": { "type": "integer" }, "porcentaje": { "type": "number" } }, "type": "object" }, "por_estado": { "type": "array", "items": { "type": "object" } }, "por_tecnico": { "type": "array", "items": { "type": "object" } }, "por_peaje": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Error de validación" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/reportes/equipo/{inventarioId}": { "get": { "tags": [ "Reportes" ], "summary": "Historial de un equipo", "description": "Obtiene el historial de mantenimientos realizados sobre un equipo específico (últimos 50 registros). Usa el SP sp_historial_equipo", "operationId": "dba170108c250c001c2ee6ce573619fb", "parameters": [ { "name": "inventarioId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Historial del equipo", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "equipo": { "type": "object", "nullable": true }, "estadisticas": { "properties": { "total_mantenimientos": { "type": "integer" }, "total_movimientos": { "type": "integer" } }, "type": "object" }, "historial": { "type": "array", "items": { "properties": { "prog_id": { "type": "integer" }, "fecha": { "type": "string", "format": "date" }, "mant_estado": { "type": "string" }, "estado_equipo": { "type": "string" }, "color": { "type": "string" }, "observacion": { "type": "string" }, "peaje": { "type": "string" }, "tecnico": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/sync/catalogos": { "get": { "tags": [ "Sincronización" ], "summary": "Descargar catálogos para APP offline", "description": "Descarga todos los catálogos necesarios para trabajar offline: estados, equipos, items de revisión, peajes, vías, inventario y mantenimientos asignados (próximos 7 días)", "operationId": "be2689794295648bccfedba69ee2d520", "parameters": [ { "name": "desde", "in": "query", "description": "Para sincronización incremental", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Catálogos descargados", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "timestamp": { "type": "string", "format": "date-time" }, "usuario": { "type": "object" }, "catalogos": { "properties": { "estados": { "type": "array", "items": { "type": "object" } }, "estados_equipos": { "type": "array", "items": { "type": "object" } }, "items_revision": { "type": "array", "items": { "type": "object" } }, "hardware_tipos": { "type": "array", "items": { "type": "object" } }, "hardware_marcas": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "estructura": { "properties": { "peajes": { "type": "array", "items": { "type": "object" } }, "vias": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "mantenimientos": { "type": "array", "items": { "type": "object" } }, "inventario": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/sync/upload": { "post": { "tags": [ "Sincronización" ], "summary": "Subir datos offline", "description": "Sincroniza operaciones realizadas offline. Procesa cambios de estado, checklists y tracking GPS", "operationId": "e5682811634f5a73cd41db179207c661", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncUploadRequest" } } } }, "responses": { "200": { "description": "Sincronización completada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "recibidas": { "type": "integer" }, "procesadas": { "type": "integer" }, "errores": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "local_id": { "type": "string" }, "error": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Error de validación" } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/sync/pendientes": { "get": { "tags": [ "Sincronización" ], "summary": "Verificar operaciones pendientes", "description": "Verifica si hay operaciones de sincronización pendientes o con error para el usuario", "operationId": "ccea3f266ef64f4c382431cc01ad0163", "responses": { "200": { "description": "Estado de sincronización", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "pendientes": { "type": "integer" }, "con_error": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/sync/dispositivo": { "post": { "tags": [ "Sincronización" ], "summary": "Registrar dispositivo móvil", "description": "Registra o actualiza un dispositivo móvil para notificaciones push. Desactiva otros dispositivos del usuario", "operationId": "b41dd9ee474ad465f24c842be5864279", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrarDispositivoRequest" } } } }, "responses": { "200": { "description": "Dispositivo registrado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "dispositivo_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/sync/dispositivo/token": { "put": { "tags": [ "Sincronización" ], "summary": "Actualizar token FCM", "description": "Actualiza el token Firebase Cloud Messaging de un dispositivo registrado", "operationId": "cea781e517947232d92ac65fe4fcd7c1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "device_id", "fcm_token" ], "properties": { "device_id": { "type": "string" }, "fcm_token": { "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Token actualizado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "dispositivo_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Dispositivo no encontrado" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "schemas": { "Alerta": { "properties": { "alerta_id": { "type": "integer", "example": 1 }, "tipo": { "type": "string", "example": "RETRASO_LLEGADA" }, "titulo": { "type": "string", "example": "Técnico con retraso" }, "mensaje": { "type": "string" }, "prioridad": { "type": "string", "enum": [ "ALTA", "MEDIA", "BAJA" ] }, "estado": { "type": "string", "enum": [ "ACTIVA", "EN_PROCESO", "RESUELTA", "IGNORADA" ] }, "icono": { "type": "string" }, "badge_prioridad": { "type": "string" }, "badge_estado": { "type": "string" }, "minutos_activa": { "type": "integer" }, "fecha_genera": { "type": "string", "format": "date-time" }, "mantenimiento": { "type": "object", "nullable": true }, "tecnico": { "type": "object", "nullable": true } }, "type": "object" }, "GestionarAlertaRequest": { "required": [ "tipo_accion", "descripcion" ], "properties": { "tipo_accion": { "type": "string", "enum": [ "LLAMADA", "MENSAJE", "EMAIL", "NOTIFICACION", "ESCALAMIENTO", "COMENTARIO" ] }, "descripcion": { "type": "string", "maxLength": 1000, "minLength": 5 }, "destinatario": { "type": "string", "maxLength": 200 }, "resultado": { "type": "string", "maxLength": 100 } }, "type": "object" }, "ResolverAlertaRequest": { "required": [ "descripcion" ], "properties": { "descripcion": { "description": "Descripción de cómo se resolvió la alerta", "type": "string", "maxLength": 1000, "minLength": 5 } }, "type": "object" }, "Aprobacion": { "properties": { "aprobacion_id": { "type": "integer", "example": 1 }, "prog_id": { "type": "integer", "example": 100 }, "tipo": { "type": "string", "enum": [ "APROBADO", "RECHAZADO" ] }, "fecha": { "type": "string", "format": "date-time" }, "pin_validado": { "type": "boolean" }, "observaciones": { "type": "string", "nullable": true }, "motivo_rechazo": { "type": "string", "nullable": true }, "gps": { "properties": { "latitud": { "type": "number", "format": "float" }, "longitud": { "type": "number", "format": "float" } }, "type": "object", "nullable": true } }, "type": "object" }, "AprobarMantenimientoRequest": { "required": [ "qr_code", "pin" ], "properties": { "qr_code": { "description": "Código QR escaneado del técnico", "type": "string" }, "pin": { "description": "PIN de 6 dígitos del Jefe Operativo", "type": "string", "maxLength": 6, "minLength": 6 }, "latitud": { "type": "number", "format": "float", "maximum": 90, "minimum": -90 }, "longitud": { "type": "number", "format": "float", "maximum": 180, "minimum": -180 }, "observaciones": { "type": "string", "maxLength": 500 } }, "type": "object" }, "RechazarMantenimientoRequest": { "required": [ "motivo" ], "properties": { "motivo": { "description": "Motivo del rechazo (mínimo 10 caracteres)", "type": "string", "maxLength": 500, "minLength": 10 }, "latitud": { "type": "number", "format": "float" }, "longitud": { "type": "number", "format": "float" } }, "type": "object" }, "AsignarJefeRequest": { "required": [ "jefe_id", "peaje_id", "pin" ], "properties": { "jefe_id": { "description": "ID del usuario con perfil JEFE_OPERATIVO", "type": "integer" }, "peaje_id": { "description": "ID del centro/peaje", "type": "integer" }, "pin": { "description": "PIN numérico de 6 dígitos", "type": "string", "maxLength": 6, "minLength": 6, "pattern": "^[0-9]+$" } }, "type": "object" }, "LoginRequest": { "required": [ "cedula", "password" ], "properties": { "cedula": { "type": "string", "example": "1234567890" }, "password": { "type": "string", "format": "password", "example": "Admin123!" } }, "type": "object" }, "LoginResponse": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Inicio de sesión exitoso" }, "data": { "type": "object" } }, "type": "object" }, "Evidencia": { "properties": { "evidencia_id": { "type": "integer", "example": 1 }, "prog_id": { "type": "integer", "example": 100 }, "tipo": { "type": "string", "enum": [ "FOTO", "VIDEO", "DOCUMENTO" ], "example": "FOTO" }, "nombre_archivo": { "type": "string", "example": "mant_100_20240115_123456_abc123.jpg" }, "url": { "type": "string", "example": "https://api.macrogram.ec/storage/evidencias/100/mant_100.jpg" }, "extension": { "type": "string", "example": "jpg" }, "tamanio": { "type": "string", "example": "2.5 MB" }, "descripcion": { "type": "string", "nullable": true }, "gps": { "properties": { "latitud": { "type": "number", "format": "float" }, "longitud": { "type": "number", "format": "float" } }, "type": "object", "nullable": true }, "sync_status": { "type": "string", "example": "SINCRONIZADO" }, "fecha_crea": { "type": "string", "format": "date-time" } }, "type": "object" }, "EvidenciaUploadRequest": { "required": [ "archivo" ], "properties": { "archivo": { "description": "Archivo a subir (jpg,jpeg,png,gif,webp,mp4,pdf) max 10MB", "type": "string", "format": "binary" }, "tipo": { "type": "string", "enum": [ "FOTO", "VIDEO", "DOCUMENTO" ] }, "descripcion": { "type": "string", "maxLength": 500 }, "latitud": { "type": "number", "format": "float", "maximum": 90, "minimum": -90 }, "longitud": { "type": "number", "format": "float", "maximum": 180, "minimum": -180 } }, "type": "object" }, "EvidenciaBase64Request": { "required": [ "archivo_base64", "nombre_original" ], "properties": { "archivo_base64": { "description": "Archivo codificado en Base64", "type": "string" }, "nombre_original": { "type": "string", "maxLength": 255, "example": "foto_evidencia.jpg" }, "tipo": { "type": "string", "enum": [ "FOTO", "VIDEO", "DOCUMENTO" ] }, "descripcion": { "type": "string", "maxLength": 500 }, "latitud": { "type": "number", "format": "float" }, "longitud": { "type": "number", "format": "float" }, "fecha_captura": { "type": "string", "format": "date-time" } }, "type": "object" }, "EvidenciaBatchRequest": { "required": [ "evidencias" ], "properties": { "evidencias": { "type": "array", "items": { "required": [ "archivo_base64", "nombre_original" ], "properties": { "archivo_base64": { "type": "string" }, "nombre_original": { "type": "string" }, "tipo": { "type": "string", "enum": [ "FOTO", "VIDEO", "DOCUMENTO" ] }, "descripcion": { "type": "string" }, "latitud": { "type": "number" }, "longitud": { "type": "number" }, "local_id": { "description": "ID local para mapeo offline", "type": "string" } }, "type": "object" }, "maxItems": 10 } }, "type": "object" }, "PosicionGps": { "required": [ "latitud", "longitud", "fecha_captura" ], "properties": { "latitud": { "type": "number", "format": "float", "maximum": 90, "minimum": -90, "example": -0.1807 }, "longitud": { "type": "number", "format": "float", "maximum": 180, "minimum": -180, "example": -78.4678 }, "precision": { "description": "Precisión en metros", "type": "number", "format": "float" }, "altitud": { "description": "Altitud en metros", "type": "number", "format": "float" }, "velocidad": { "description": "Velocidad en km/h", "type": "number", "format": "float" }, "bateria": { "description": "Porcentaje de batería", "type": "integer", "maximum": 100, "minimum": 0 }, "fecha_captura": { "type": "string", "format": "date-time" }, "prog_id": { "description": "ID del mantenimiento asociado", "type": "integer", "nullable": true } }, "type": "object" }, "RegistrarGpsRequest": { "required": [ "posiciones" ], "properties": { "posiciones": { "type": "array", "items": { "$ref": "#/components/schemas/PosicionGps" }, "maxItems": 50 } }, "type": "object" }, "TecnicoActivo": { "properties": { "tecnico_id": { "type": "integer" }, "nombre": { "type": "string" }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "fecha": { "type": "string", "format": "date-time" }, "minutos": { "description": "Minutos desde última actualización", "type": "integer" }, "bateria": { "type": "integer" }, "velocidad": { "type": "number" }, "activo": { "description": "true si actualización < 30 minutos", "type": "boolean" } }, "type": "object" }, "Mantenimiento": { "properties": { "prog_id": { "type": "integer", "example": 1 }, "fecha_programada": { "type": "string", "format": "date", "example": "2024-01-15" }, "observaciones": { "type": "string", "nullable": true }, "qr_code": { "type": "string", "nullable": true }, "qr_expira": { "type": "string", "format": "date-time", "nullable": true }, "qr_vigente": { "type": "boolean" }, "estado": { "type": "object" }, "tecnico": { "type": "object" }, "peaje": { "type": "object" } }, "type": "object" }, "EstadoMantenimiento": { "properties": { "id": { "type": "integer", "example": 1 }, "codigo": { "type": "string", "example": "EN_MANTENIMIENTO" }, "nombre": { "type": "string", "example": "En Mantenimiento" }, "color": { "type": "string", "example": "#FFC107" }, "requiere_gps": { "type": "boolean", "example": true } }, "type": "object" }, "CambiarEstadoRequest": { "required": [ "estado" ], "properties": { "estado": { "type": "string", "enum": [ "CAMINO_PEAJE", "LLEGADA_PEAJE", "EN_MANTENIMIENTO", "MANT_FINALIZADO", "RETORNO_INICIADO", "COMPLETADO" ], "example": "EN_MANTENIMIENTO" }, "latitud": { "type": "number", "format": "float", "example": -0.1807 }, "longitud": { "type": "number", "format": "float", "example": -78.4678 }, "precision": { "type": "number", "format": "float", "example": 10.5 }, "observaciones": { "type": "string", "example": "Iniciando mantenimiento preventivo" } }, "type": "object" }, "GuardarChecklistRequest": { "required": [ "inventario_id", "via_id", "id_item", "estado_equipo_id" ], "properties": { "inventario_id": { "description": "ID del equipo en hardware_inventario", "type": "integer", "example": 15 }, "via_id": { "description": "ID de la vía donde está instalado el equipo", "type": "integer", "example": 1 }, "id_item": { "description": "ID del item de revisión", "type": "integer", "example": 3 }, "estado_equipo_id": { "description": "1=Operativo, 2=Falla, 3=Requiere Cambio", "type": "integer", "example": 1 }, "valor_medicion": { "type": "string", "example": "120V", "nullable": true }, "observacion": { "type": "string", "example": "Funciona correctamente", "nullable": true } }, "type": "object" }, "OperacionSync": { "required": [ "tabla", "operacion", "local_id", "data", "fecha_creacion_local" ], "properties": { "tabla": { "description": "Tabla destino: mant_estado_historial, mant_checklist_respuestas, gps_tracking", "type": "string" }, "operacion": { "type": "string", "enum": [ "CREATE", "UPDATE", "DELETE" ] }, "local_id": { "description": "ID único local para tracking", "type": "string" }, "data": { "description": "Datos de la operación", "type": "object" }, "fecha_creacion_local": { "type": "string", "format": "date-time" }, "prioridad": { "type": "integer", "default": 5, "maximum": 10, "minimum": 1 } }, "type": "object" }, "SyncUploadRequest": { "required": [ "dispositivo_id", "operaciones" ], "properties": { "dispositivo_id": { "type": "integer" }, "operaciones": { "type": "array", "items": { "$ref": "#/components/schemas/OperacionSync" } } }, "type": "object" }, "RegistrarDispositivoRequest": { "required": [ "device_id", "plataforma" ], "properties": { "device_id": { "description": "ID único del dispositivo", "type": "string", "maxLength": 255 }, "fcm_token": { "description": "Token Firebase Cloud Messaging", "type": "string", "maxLength": 500 }, "plataforma": { "type": "string", "enum": [ "ANDROID", "IOS" ] }, "modelo": { "type": "string", "maxLength": 100 }, "version_os": { "type": "string", "maxLength": 50 }, "version_app": { "type": "string", "maxLength": 20 } }, "type": "object" } }, "securitySchemes": { "sanctum": { "type": "apiKey", "description": "Ingresa el token en formato: Bearer {token}", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Autenticación", "description": "Endpoints para autenticación y gestión de sesiones" }, { "name": "Mantenimientos", "description": "Gestión del ciclo de vida de mantenimientos" }, { "name": "Evidencias", "description": "Fotografías y documentos de respaldo" }, { "name": "Aprobaciones", "description": "Sistema de aprobación QR+PIN por Jefe Operativo" }, { "name": "Alertas", "description": "Sistema de alertas automáticas" }, { "name": "Reportes", "description": "Dashboards y reportes gerenciales" }, { "name": "Sincronización", "description": "Sincronización offline para app móvil" }, { "name": "Jefes Operativos", "description": "Jefes Operativos" }, { "name": "GPS Tracking", "description": "GPS Tracking" } ], "security": [ { "sanctum": [] } ] }