{ "openapi": "3.0.0", "info": { "title": "UGPS Atlas API", "version": "1.0.0", "description": "Documentación de la API REST principal de UGPS Atlas (plataforma de rastreo GPS)" }, "servers": [ { "url": "https://api.ugps.io", "description": "Servidor de producción" } ], "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "paths": { "/health": { "get": { "summary": "Liveness probe", "description": "Siempre responde 200 mientras el proceso viva. Es el health probe de Azure\nApp Service. El estado real de las dependencias (Mongo, Redis) va en el payload,\npero no afecta el código de respuesta. Público, sin autenticación.\n", "tags": [ "Sistema" ], "security": [], "responses": { "200": { "description": "El proceso está vivo", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "number", "description": "Segundos que lleva vivo el proceso" }, "environment": { "type": "string", "example": "production" }, "dependencies": { "type": "object", "properties": { "mongo": { "type": "string", "enum": [ "connected", "connecting", "disconnecting", "disconnected", "unknown" ] }, "redis": { "type": "string", "description": "Estado del cliente Redis (ioredis)" } } } } } } } } } } }, "/ready": { "get": { "summary": "Readiness probe", "description": "Responde 200 solo si todas las dependencias duras están listas (Mongo\n`connected` y Redis `ready`); 503 en caso contrario. Se usa como gate\npost-deploy en CI. Público, sin autenticación.\n", "tags": [ "Sistema" ], "security": [], "responses": { "200": { "description": "El servicio está listo para recibir tráfico", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" }, "dependencies": { "type": "object", "properties": { "mongo": { "type": "string", "example": "connected" }, "redis": { "type": "string", "example": "ready" } } } } } } } }, "503": { "description": "El servicio no está listo (alguna dependencia dura no disponible)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "code": { "type": "string", "example": "NOT_READY" }, "message": { "type": "string" }, "requestId": { "type": "string", "nullable": true }, "dependencies": { "type": "object", "properties": { "mongo": { "type": "string", "example": "disconnected" }, "redis": { "type": "string", "example": "connecting" } } } } } } } } } } }, "/api/assets": { "get": { "summary": "Obtener todos los activos", "description": "Obtiene todos los activos del cliente autenticado.\n\n**Filtrado automático:**\n- Solo retorna activos del `clientId` del usuario autenticado\n- Los activos inactivos se excluyen automáticamente\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de activos", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo activo", "description": "Crea un nuevo activo en el sistema.\n\n**Datos requeridos:**\n- `name` (string): Nombre del activo\n- `icon` (object): Objeto con `id` (string) y `color` (string, formato hexadecimal #RRGGBB o #RGB)\n- `mainTrackerId` (number): ID del tracker principal\n- `trackers` (array): Array de objetos con `id` (number) y `platform` (string)\n- `plate` (string): Placa del activo (debe ser única dentro del cliente)\n- `assetTypeId` (string): ID del tipo de activo\n\n**Datos opcionales:**\n- `vehicleTypeId` (string): ID del tipo de vehículo\n- `model` (string): Modelo del activo\n- `year` (number): Año del activo\n- `color` (string): Color del activo\n- `make` (string): Marca del activo\n- `chassis` (string): Número de chasis\n- `motor` (string): Número de motor\n- `fuel` (string): Tipo de combustible\n- `kilometer` (number): Kilometraje\n- `description` (string): Descripción adicional\n- `state` (string): Estado del activo\n\n**Comportamiento automático:**\n- El `clientId` se asigna automáticamente desde el token del usuario\n- Se valida que la placa y el nombre sean únicos dentro del cliente\n- Si se proporciona un `trackerId`, se valida que el tracker pertenezca al mismo cliente\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } }, "responses": { "201": { "description": "Activo creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/filter/{alertTriggerId}": { "get": { "summary": "Obtener activos disponibles para una alerta", "description": "Obtiene los activos que pueden asignarse a una alerta según el trigger, respetando los límites por tipo (velocidad, geocerca, etc.).\n\n**Parámetro opcional `alertId`:** Si se envía (por ejemplo al editar una alerta), la respuesta incluye también los activos ya asignados a esa alerta, con `alreadyInAlert: true`, para que el front pueda mostrarlos como seleccionados sin errores.\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "alertTriggerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del trigger de alerta" }, { "name": "alertId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ID de la alerta (opcional). Si se envía, se incluyen en la respuesta los activos ya asignados a esa alerta, útiles al editar" } ], "responses": { "200": { "description": "Lista de activos disponibles (y, si se pasó alertId, los ya asignados a esa alerta)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "68ed563b12a66729a9194215" }, "name": { "type": "string", "example": "Camión 01" }, "icon": { "type": "object", "properties": { "id": { "type": "string", "example": "truck" }, "color": { "type": "string", "example": "#000000" } } }, "alreadyInAlert": { "type": "boolean", "description": "true si el activo ya está asignado a la alerta (solo cuando se envió alertId)", "example": false } }, "required": [ "id", "name", "icon" ] } } }, "required": [ "status", "data" ] }, "examples": { "ok": { "summary": "Ejemplo exitoso", "value": { "status": "success", "data": [ { "id": "68ed563b12a66729a9194215", "name": "Camión 01", "icon": { "id": "truck", "color": "#000000" }, "alreadyInAlert": false } ] } } } } } }, "400": { "description": "Error de validación (alertTriggerId o alertId inválido)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "alertTriggerId es requerido y debe ser un ObjectId válido" } }, "required": [ "status", "message" ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/{id}": { "get": { "summary": "Obtener un activo por ID", "description": "Obtiene los detalles de un activo específico por su ID.\n\n**Filtrado automático:**\n- Solo retorna el activo si pertenece al `clientId` del usuario autenticado\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Activo encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un activo por ID", "description": "Actualiza un activo existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `name` (string): Nombre del activo\n- `icon` (object): Objeto con `id` (string) y `color` (string, formato hexadecimal #RRGGBB o #RGB)\n- `mainTrackerId` (number): ID del tracker principal\n- `trackers` (array): Array de objetos con `id` (number) y `platform` (string)\n- `plate` (string): Placa del activo (debe ser única dentro del cliente)\n- `assetTypeId` (string): ID del tipo de activo\n- `vehicleTypeId` (string): ID del tipo de vehículo\n- `model` (string): Modelo del activo\n- `year` (number): Año del activo\n- `color` (string): Color del activo\n- `make` (string): Marca del activo\n- `chassis` (string): Número de chasis\n- `motor` (string): Número de motor\n- `fuel` (string): Tipo de combustible\n- `kilometer` (number): Kilometraje\n- `description` (string): Descripción adicional\n- `state` (string): Estado del activo\n\n**Comportamiento automático:**\n- Se valida que la placa y el nombre sean únicos dentro del cliente (si se actualizan)\n- Si se proporciona un `trackerId`, se valida que el tracker pertenezca al mismo cliente\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } }, "responses": { "200": { "description": "Activo actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "Familia canonica del activo. Se rellena de forma compatible con tipos antiguos." }, "name": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string", "description": "Formato hexadecimal (#RRGGBB o #RGB)", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } }, "mainTrackerId": { "type": "number" }, "trackers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "platform": { "type": "string" } } } }, "plate": { "type": "string" }, "vehicleTypeId": { "type": "string", "description": "ID del tipo de vehículo asociado al activo (opcional)" }, "assetTypeId": { "type": "string" }, "model": { "type": "string", "description": "Modelo del activo (opcional)" }, "year": { "type": "number" }, "color": { "type": "string", "description": "Color del activo (opcional)" }, "make": { "type": "string" }, "chassis": { "type": "string", "description": "Número de chasis del activo (opcional)" }, "motor": { "type": "string", "description": "Número de motor del activo (opcional)" }, "fuel": { "type": "string", "description": "Tipo de combustible del activo (opcional)" }, "kilometer": { "type": "number", "description": "Kilometraje del activo (opcional)" }, "technicalInspection": { "type": "object", "description": "Revisión técnica del vehículo (opcional). La puebla la consulta vehicular\npor patente y también se puede editar a mano. Solo aplica a activos de\nkind `vehicle`: en los `generic` se limpia.\n", "properties": { "date": { "type": "string", "format": "date", "description": "Fecha en que se realizó la revisión, no su vencimiento" }, "result": { "type": "string", "description": "Código de resultado del proveedor, sin interpretar" }, "resultGas": { "type": "string", "description": "Código de resultado del control de gases, sin interpretar" }, "month": { "type": "string", "description": "Mes que le corresponde según el último dígito de la patente" }, "station": { "type": "object", "description": "Planta revisora donde se realizó", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "commune": { "type": "string" }, "concession": { "type": "string" }, "address": { "type": "string" } } } } }, "description": { "type": "string", "description": "Descripción adicional del activo (opcional)" }, "clientId": { "type": "string" }, "state": { "type": "string", "description": "Estado del activo (opcional)" } }, "required": [ "name", "icon", "mainTrackerId", "trackers", "plate", "assetTypeId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un activo por ID", "description": "Elimina un activo del sistema.\n\n**Permisos requeridos:** `access_assets`\n\n**Nota:** Esta acción no se puede deshacer.\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Activo eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Activo eliminado exitosamente" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/trackers-by-platform": { "get": { "summary": "Obtener trackers agrupados por plataforma", "description": "Obtiene los trackers agrupados por plataforma (navixy, atlas, etc.) para los activos del cliente autenticado.\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de trackers agrupados por plataforma obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "number" } }, "example": { "navixy": [ 123, 456 ], "atlas": [] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/{id}/icon": { "patch": { "summary": "Actualizar el icono de un activo", "description": "Actualiza el icono de un activo específico.\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "icon" ], "properties": { "icon": { "type": "object", "required": [ "id", "color" ], "properties": { "id": { "type": "string", "description": "ID del icono" }, "color": { "type": "string", "description": "Color del icono en formato hexadecimal", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } } } } } } }, "responses": { "200": { "description": "Icono actualizado correctamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/asset-types": { "get": { "summary": "Obtener todos los tipos de activos", "description": "Obtiene todos los tipos de activos disponibles en el sistema.\n", "tags": [ "Activos - Tipos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de tipos de activos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo tipo de activo", "description": "Crea un nuevo tipo de activo en el sistema.\n\n**Datos requeridos:**\n- `name` (string): Nombre del tipo de activo\n\n**Datos opcionales:**\n- `description` (string): Descripción del tipo de activo\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Tipos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Tipo de activo creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/asset-types/{id}": { "get": { "summary": "Obtener un tipo de activo por ID", "description": "Obtiene los detalles de un tipo de activo específico por su ID.\n", "tags": [ "Activos - Tipos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tipo de activo encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un tipo de activo por ID", "description": "Actualiza un tipo de activo existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `name` (string): Nombre del tipo de activo\n- `description` (string): Descripción del tipo de activo\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Tipos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Tipo de activo actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "description": "(opcional)" }, "kind": { "type": "string", "enum": [ "vehicle", "generic" ], "description": "(opcional, recomendado para nuevos tipos)" } }, "required": [ "name" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un tipo de activo por ID", "description": "Elimina un tipo de activo del sistema.\n\n**Permisos requeridos:** `access_assets`\n\n**Nota:** Esta acción no se puede deshacer.\n", "tags": [ "Activos - Tipos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tipo de activo eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Tipo de activo eliminado exitosamente" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/asset-groups": { "get": { "summary": "Obtener todos los grupos de activos", "description": "Obtiene todos los grupos de activos del cliente autenticado.\n\n**Filtrado automático:**\n- Solo retorna grupos de activos del `clientId` del usuario autenticado\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de grupos de activos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo grupo de activos", "description": "Crea un nuevo grupo de activos en el sistema.\n\n**Datos requeridos:**\n- `name` (string): Nombre del grupo de activos\n- `color` (string): Color asociado al grupo\n- `client` (string): ID del cliente asociado\n\n**Datos opcionales:**\n- `assetIds` (array): Array de IDs de activos asociados al grupo\n\n**Comportamiento automático:**\n- El `clientId` se asigna automáticamente desde el token del usuario\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } }, "responses": { "201": { "description": "Grupo de activos creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/asset-groups/asset-ids": { "get": { "summary": "Obtener todos los IDs de activos", "description": "Obtiene todos los IDs de activos del cliente autenticado.\n\n**Filtrado automático:**\n- Solo retorna IDs de activos del `clientId` del usuario autenticado\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de IDs de activos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "645a1b2c3d4e5f6789012345" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/asset-groups/{id}": { "get": { "summary": "Obtener un grupo de activos por ID", "description": "Obtiene los detalles de un grupo de activos específico por su ID.\n\n**Filtrado automático:**\n- Solo retorna el grupo si pertenece al `clientId` del usuario autenticado\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Grupo de activos encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un grupo de activos por ID", "description": "Actualiza un grupo de activos existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `name` (string): Nombre del grupo de activos\n- `color` (string): Color asociado al grupo\n- `client` (string): ID del cliente asociado\n- `assetIds` (array): Array de IDs de activos asociados al grupo\n\n**Permisos requeridos:** `access_assets`\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } }, "responses": { "200": { "description": "Grupo de activos actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "client": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "color", "client" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un grupo de activos por ID", "description": "Elimina un grupo de activos del sistema.\n\n**Permisos requeridos:** `access_assets`\n\n**Nota:** Esta acción no se puede deshacer.\n", "tags": [ "Activos - Grupos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Grupo de activos eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Grupo de activos eliminado exitosamente" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/vehicle-types": { "get": { "summary": "Obtener todos los tipos de vehículos", "description": "Obtiene todos los tipos de vehículos disponibles en el sistema.\n", "tags": [ "Activos - Vehículos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de tipos de vehículos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "group": { "type": "string", "description": "Grupo al que pertenece (ej: Vehículo, Transporte, Carga, Maquinaria)" } }, "required": [ "id", "name", "group" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/auth/verify-token": { "get": { "summary": "Verificar la validez de un token", "description": "Verifica si el token de acceso actual es válido y no ha expirado.\n\n**Comportamiento:**\n- Valida el token JWT del header Authorization\n- Retorna información del usuario si el token es válido\n- Útil para verificar el estado de autenticación en el frontend\n", "tags": [ "Auth - Autenticación" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Token válido", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "isValid": { "type": "boolean", "example": true }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "ID del usuario" }, "email": { "type": "string", "description": "Email del usuario" }, "role": { "type": "string", "description": "Rol del usuario" } } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/auth/me": { "get": { "summary": "Obtener el usuario de la sesión actual", "description": "Retorna los datos del usuario autenticado actualmente (sesión web).\n\n**Comportamiento:**\n- Requiere un access token de sesión válido (no acepta API tokens)\n- Devuelve el usuario sin la contraseña, con `client` y `role` poblados\n- Los permisos del rol llegan como objetos `{ _id, name }`\n- Útil para inicializar el estado de la sesión en el frontend\n", "tags": [ "Auth - Autenticación" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usuario de la sesión actual", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Usuario autenticado devuelto por GET /api/auth/me (sin contraseña, con client y role poblados).", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "description": "(opcional)" }, "isActive": { "type": "boolean" }, "protected": { "type": "boolean" }, "hasUnrestrictedAccess": { "type": "boolean", "description": "Agregado por el middleware de auth desde el JWT." }, "creator": { "type": "string", "description": "ObjectId del usuario creador (sin poblar)." }, "client": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "fantasyName": { "type": "string" }, "rut": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "example": "navixy" }, "id": { "type": "string" } } } } }, "required": [ "_id", "name" ] }, "role": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "protected": { "type": "boolean" }, "accessPermissions": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } } }, "actionPermissions": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } } } }, "required": [ "_id", "name" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "firstName", "lastName", "email", "isActive", "protected", "hasUnrestrictedAccess" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/users": { "get": { "summary": "Obtener usuarios del cliente actual", "description": "Obtiene todos los usuarios que pertenecen al `clientId` del usuario autenticado.\n\n**Permisos requeridos:** `access_user`\n\n**Filtrado automático:**\n- Solo retorna usuarios del `clientId` del usuario autenticado\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de usuarios del cliente obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo usuario", "description": "Crea un nuevo usuario en el sistema.\n\n**Datos requeridos:**\n- `firstName` (string): Nombre del usuario\n- `lastName` (string): Apellido del usuario\n- `email` (string, formato email): Correo electrónico del usuario (debe ser único dentro del cliente)\n- `password` (string): Contraseña del usuario\n- `roleId` (string): ID del rol asociado al usuario\n\n**Datos opcionales:**\n- `middleName` (string): Segundo nombre del usuario\n- `phone` (string): Número de teléfono del usuario\n- `isActive` (boolean): Estado del usuario (true = activo, false = inactivo, por defecto: true)\n- `protected` (boolean): Protegido contra eliminación (por defecto: false)\n\n**Comportamiento automático:**\n- El `clientId` se asigna automáticamente desde el token del usuario\n- Se valida que el email sea único dentro del cliente\n\n**Permisos requeridos:** `access_user`\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } }, "responses": { "201": { "description": "Usuario creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/users/by-creator/{creatorId}": { "get": { "summary": "Obtener usuarios creados por un usuario específico", "description": "Obtiene todos los usuarios que han sido creados por un usuario específico usando su ID.\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "creatorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del creador" } ], "responses": { "200": { "description": "Lista de usuarios creados por el usuario especificado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Usuarios creados por usuario@ejemplo.com (5 usuarios encontrados)" }, "creator": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID del usuario creador" }, "name": { "type": "string", "description": "Nombre del usuario creador" }, "email": { "type": "string", "description": "Email del usuario creador" } } }, "users": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/users/{id}": { "get": { "summary": "Obtener un usuario por ID", "description": "Obtiene los detalles de un usuario específico por su ID.\n\n**Filtrado automático:**\n- Solo retorna el usuario si pertenece al `clientId` del usuario autenticado\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Usuario encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un usuario por ID", "description": "Actualiza un usuario existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `firstName` (string): Nombre del usuario\n- `lastName` (string): Apellido del usuario\n- `middleName` (string): Segundo nombre del usuario\n- `email` (string, formato email): Correo electrónico del usuario\n- `password` (string): Contraseña del usuario\n- `phone` (string): Número de teléfono del usuario\n- `roleId` (string): ID del rol asociado al usuario\n- `isActive` (boolean): Estado del usuario (true = activo, false = inactivo)\n- `protected` (boolean): Protegido contra eliminación\n\n**Comportamiento automático:**\n- Se valida que el email sea único dentro del cliente (si se actualiza)\n\n**Permisos requeridos:** `access_user`\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } }, "responses": { "200": { "description": "Usuario actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un usuario por ID", "description": "Elimina un usuario del sistema.\n\n**Permisos requeridos:** `access_user`\n\n**Nota:** Esta acción no se puede deshacer.\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Usuario eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Usuario eliminado exitosamente" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/users/{id}/status": { "patch": { "summary": "Actualizar estado de un usuario", "description": "Actualiza el estado activo/inactivo de un usuario. Solo actualiza el campo `isActive`.\n\n**Permisos requeridos:** `access_user`\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "isActive" ], "properties": { "isActive": { "type": "boolean", "description": "Estado del usuario (true para activo, false para inactivo)" } } } } } }, "responses": { "200": { "description": "Estado del usuario actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Usuario activado exitosamente" }, "user": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string", "description": "(opcional)" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "roleId": { "type": "string" }, "clientId": { "type": "string" }, "creatorId": { "type": "string" }, "isActive": { "type": "boolean", "description": "true = activo, false = inactivo", "default": true }, "protected": { "type": "boolean", "description": "Protegido contra eliminación", "default": false } }, "required": [ "firstName", "lastName", "email", "password", "roleId" ] } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/users/{id}/change-password": { "patch": { "summary": "Cambiar la contraseña de un usuario", "description": "Cambia la contraseña de un usuario específico.\n\n**Permisos requeridos:** `access_user`\n\n**Restricciones:**\n- Solo los usuarios con roles protegidos pueden cambiar contraseñas de usuarios que pertenezcan al mismo cliente\n", "tags": [ "Usuarios - Usuarios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "description": "Nueva contraseña" } } } } } }, "responses": { "200": { "description": "Contraseña actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Contraseña actualizada exitosamente" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers": { "get": { "summary": "Obtener trackers", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de trackers obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo tracker", "description": "Crea un nuevo tracker en el sistema.\n\n**Datos requeridos:**\n- `name` (string): Nombre del dispositivo\n- `model_id` (number): ID del modelo/tipo de dispositivo\n- `imei` (string): IMEI del dispositivo\n- `clientId` (string): ID del cliente asociado al tracker\n\n**Datos opcionales:**\n- `phone` (string): Número de teléfono asociado al tracker\n- `trip_config` (string, enum: ignition|no_config|motion): Configuración de calculadores\n - `ignition`: Usa calculadores de ignición (Trips_Ignition)\n - `no_config`: Usa calculadores normales (Trips)\n - `motion`: Usa calculador por movimiento (Trips_Motion_0-3391167)\n - Por defecto: `no_config`\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "model_id": { "type": "number" }, "imei": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "default": "no_config" } }, "required": [ "name", "model_id", "imei", "clientId" ] } } } }, "responses": { "201": { "description": "Tracker creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "flespiDevice": { "type": "object", "description": "Datos del dispositivo creado en Flespi", "properties": { "id": { "type": "number", "description": "ID del dispositivo creado" }, "name": { "type": "string", "description": "Nombre del dispositivo" }, "device_type_id": { "type": "number", "description": "ID del tipo de dispositivo" }, "configuration": { "type": "object", "properties": { "ident": { "type": "string", "description": "IMEI del dispositivo" } } } } }, "tracker": { "type": "object", "description": "Datos del tracker almacenado en la base de datos", "properties": { "flespiId": { "type": "number", "description": "ID del dispositivo en Flespi" }, "imei": { "type": "string", "description": "IMEI del dispositivo" }, "name": { "type": "string", "description": "Nombre del dispositivo" }, "clientId": { "type": "string", "description": "ID del cliente asociado" }, "phone": { "type": "string", "description": "Número de teléfono asociado al tracker" }, "hardware": { "type": "string", "description": "Hardware del dispositivo" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "Configuración de calculadores" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/client/{clientId}": { "get": { "summary": "Obtener todos los trackers de un cliente específico", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene todos los trackers de un cliente específico. Requiere el permiso\n`access_tracking` o `access_fleet_assets`. Solo se puede consultar el cliente\nde la propia sesión; consultar otro cliente requiere además `access_admin_panel`.\n", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del cliente" } ], "responses": { "200": { "description": "Lista de trackers del cliente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/{flespiId}/odometer": { "get": { "summary": "Obtener datos de odometro de un tracker", "description": "Obtiene el estado del counter de odometro (`tracker.counters.odometer`) para un tracker identificado por su `flespiId`.\n\nDevuelve `currentKm`, el valor DEVICE exacto o el valor calculado. La fuente y el\nparametro son configuración operativa y solo se exponen en las rutas admin.\n\nLa respuesta incluye ademas los alias snake_case legacy (`initial_odometer`, `odometer_calculated`, `total_mileage`, `current_odometer`) durante la convivencia con la app movil.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del dispositivo en Flespi" } ], "responses": { "200": { "description": "Datos de odometro obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Valor visible del odometro. La fuente y el parametro se reservan para rutas admin; los alias snake_case se mantienen durante la convivencia con la app movil", "properties": { "currentKm": { "type": "number", "nullable": true, "description": "Valor DEVICE exacto o initialKm + accumulatedKm; null antes de la primera lectura DEVICE", "example": 150000 }, "initial_odometer": { "type": "number", "deprecated": true, "description": "Alias legacy de initialKm (se elimina al completar la migracion de la app movil)", "example": 146800 }, "odometer_calculated": { "type": "boolean", "deprecated": true, "description": "Alias legacy de enabled", "example": true }, "total_mileage": { "type": "number", "deprecated": true, "description": "Alias legacy de accumulatedKm", "example": 3200 }, "current_odometer": { "type": "number", "deprecated": true, "description": "Alias legacy de currentKm", "example": 150000 } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "patch": { "summary": "Corregir odometro calculado de un tracker", "description": "Corrige el valor de un counter CALCULATED. Toma `odometer` como valor actual y calcula\n`initialKm = odometer - accumulatedKm`. Los aliases legacy se conservan\ndurante el despliegue gradual. La selección de fuente pertenece a Admin Panel.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del dispositivo en Flespi" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "odometer" ], "properties": { "odometer": { "type": "number", "minimum": 0, "description": "Lectura actual del odometro del vehiculo en km", "example": 150000 }, "odometer_calculated": { "type": "boolean", "enum": [ true ], "deprecated": true, "description": "Alias legacy opcional; el cliente no puede cambiar la fuente" } } } } } }, "responses": { "200": { "description": "Odometro configurado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "allOf": [ { "type": "object", "description": "Valor visible del odometro. La fuente y el parametro se reservan para rutas admin; los alias snake_case se mantienen durante la convivencia con la app movil", "properties": { "currentKm": { "type": "number", "nullable": true, "description": "Valor DEVICE exacto o initialKm + accumulatedKm; null antes de la primera lectura DEVICE", "example": 150000 }, "initial_odometer": { "type": "number", "deprecated": true, "description": "Alias legacy de initialKm (se elimina al completar la migracion de la app movil)", "example": 146800 }, "odometer_calculated": { "type": "boolean", "deprecated": true, "description": "Alias legacy de enabled", "example": true }, "total_mileage": { "type": "number", "deprecated": true, "description": "Alias legacy de accumulatedKm", "example": 3200 }, "current_odometer": { "type": "number", "deprecated": true, "description": "Alias legacy de currentKm", "example": 150000 } } } ], "description": "Estado del counter tras la configuracion (misma forma que el GET)" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/{flespiId}/horometer": { "get": { "summary": "Obtener datos de horometro de un tracker", "description": "Obtiene el estado del counter de horas motor (`tracker.counters.engineHours`) para un tracker identificado por su `flespiId`.\n\nDevuelve `currentHours`, el valor DEVICE exacto o el valor calculado. La fuente y el\nparametro son configuración operativa y solo se exponen en las rutas admin.\n\nLa respuesta incluye ademas los alias snake_case legacy (`initial_horometer`, `horometer_calculated`, `total_engine_hours`, `current_horometer`) durante la convivencia con la app movil.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del dispositivo en Flespi" } ], "responses": { "200": { "description": "Datos de horometro obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Valor visible de las horas motor. La fuente y el parametro se reservan para rutas admin; los alias snake_case se mantienen durante la convivencia con la app movil", "properties": { "currentHours": { "type": "number", "nullable": true, "description": "Valor DEVICE exacto o initialHours + accumulatedSeconds / 3600; null antes de la primera lectura DEVICE", "example": 5000 }, "initial_horometer": { "type": "number", "deprecated": true, "description": "Alias legacy de initialHours (se elimina al completar la migracion de la app movil)", "example": 4800 }, "horometer_calculated": { "type": "boolean", "deprecated": true, "description": "Alias legacy de enabled", "example": true }, "total_engine_hours": { "type": "number", "deprecated": true, "description": "Horas acumuladas (accumulatedSeconds / 3600), alias legacy", "example": 200 }, "current_horometer": { "type": "number", "deprecated": true, "description": "Alias legacy de currentHours", "example": 5000 } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "patch": { "summary": "Corregir horometro calculado de un tracker", "description": "Corrige el valor de un counter CALCULATED. Toma `horometer` como valor actual y calcula\n`initialHours = horometer - accumulatedSeconds / 3600`. Los aliases legacy\nse conservan durante el despliegue gradual. La selección de fuente pertenece a Admin Panel.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del dispositivo en Flespi" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "horometer" ], "properties": { "horometer": { "type": "number", "minimum": 0, "description": "Lectura actual del horometro del vehiculo en horas", "example": 5000 }, "horometer_calculated": { "type": "boolean", "enum": [ true ], "deprecated": true, "description": "Alias legacy opcional; el cliente no puede cambiar la fuente" } } } } } }, "responses": { "200": { "description": "Horometro configurado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "allOf": [ { "type": "object", "description": "Valor visible de las horas motor. La fuente y el parametro se reservan para rutas admin; los alias snake_case se mantienen durante la convivencia con la app movil", "properties": { "currentHours": { "type": "number", "nullable": true, "description": "Valor DEVICE exacto o initialHours + accumulatedSeconds / 3600; null antes de la primera lectura DEVICE", "example": 5000 }, "initial_horometer": { "type": "number", "deprecated": true, "description": "Alias legacy de initialHours (se elimina al completar la migracion de la app movil)", "example": 4800 }, "horometer_calculated": { "type": "boolean", "deprecated": true, "description": "Alias legacy de enabled", "example": true }, "total_engine_hours": { "type": "number", "deprecated": true, "description": "Horas acumuladas (accumulatedSeconds / 3600), alias legacy", "example": 200 }, "current_horometer": { "type": "number", "deprecated": true, "description": "Alias legacy de currentHours", "example": 5000 } } } ], "description": "Estado del counter tras la configuracion (misma forma que el GET)" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/{id}": { "get": { "summary": "Obtener un tracker por ID", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tracker encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un tracker por ID", "description": "Actualiza un tracker existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `name` (string): Nombre del tracker\n- `phone` (string): Número de teléfono asociado al tracker\n- `trip_config` (string, enum: ignition|no_config|motion): Configuración de calculadores\n - `ignition`: Usa calculadores de ignición (Trips_Ignition)\n - `no_config`: Usa calculadores normales (Trips)\n - `motion`: Usa calculador por movimiento (Trips_Motion_0-3391167)\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } }, "responses": { "200": { "description": "Tracker actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un tracker por ID", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tracker eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/roles": { "post": { "summary": "Crear un nuevo rol", "tags": [ "Usuarios - Roles" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre del rol" }, "accessPermissions": { "type": "array", "items": { "type": "string" }, "description": "IDs de los permisos de acceso" }, "actionPermissions": { "type": "array", "items": { "type": "string" }, "description": "IDs de los permisos de acción" }, "protected": { "type": "boolean", "description": "Indica si el rol está protegido (no se puede eliminar)" } }, "required": [ "name", "accessPermissions", "actionPermissions" ] } } } }, "responses": { "201": { "description": "Rol creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Rol creado exitosamente" }, "role": { "type": "object", "properties": { "name": { "type": "string" }, "clientId": { "type": "string" }, "accessPermissions": { "type": "array", "items": { "type": "string" } }, "actionPermissions": { "type": "array", "items": { "type": "string" } }, "protected": { "type": "boolean", "description": "No se puede eliminar", "default": false }, "userCount": { "type": "integer", "example": 5 } }, "required": [ "name", "clientId", "accessPermissions", "actionPermissions" ] } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "409": { "description": "Ya existe un rol con el mismo nombre para este cliente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Ya existe un rol con el mismo nombre para este cliente" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "get": { "summary": "Obtener roles del cliente del token", "tags": [ "Usuarios - Roles" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de roles del cliente obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "clientId": { "type": "string" }, "accessPermissions": { "type": "array", "items": { "type": "string" } }, "actionPermissions": { "type": "array", "items": { "type": "string" } }, "protected": { "type": "boolean", "description": "No se puede eliminar", "default": false }, "userCount": { "type": "integer", "example": 5 } }, "required": [ "name", "clientId", "accessPermissions", "actionPermissions" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/roles/{id}": { "get": { "summary": "Obtener un rol por ID", "tags": [ "Usuarios - Roles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Rol encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "clientId": { "type": "string" }, "accessPermissions": { "type": "array", "items": { "type": "string" } }, "actionPermissions": { "type": "array", "items": { "type": "string" } }, "protected": { "type": "boolean", "description": "No se puede eliminar", "default": false }, "userCount": { "type": "integer", "example": 5 } }, "required": [ "name", "clientId", "accessPermissions", "actionPermissions" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un rol por ID", "tags": [ "Usuarios - Roles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre del rol" }, "accessPermissions": { "type": "array", "items": { "type": "string" }, "description": "IDs de los permisos de acceso" }, "actionPermissions": { "type": "array", "items": { "type": "string" }, "description": "IDs de los permisos de acción" }, "protected": { "type": "boolean", "description": "Indica si el rol está protegido (no se puede eliminar)" } } } } } }, "responses": { "200": { "description": "Rol actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "clientId": { "type": "string" }, "accessPermissions": { "type": "array", "items": { "type": "string" } }, "actionPermissions": { "type": "array", "items": { "type": "string" } }, "protected": { "type": "boolean", "description": "No se puede eliminar", "default": false }, "userCount": { "type": "integer", "example": 5 } }, "required": [ "name", "clientId", "accessPermissions", "actionPermissions" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un rol por ID", "tags": [ "Usuarios - Roles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Rol eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "No se puede eliminar un rol protegido", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "No se puede eliminar un rol protegido" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "409": { "description": "No se puede eliminar el rol porque está asignado a usuarios", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "No se puede eliminar el rol porque está asignado a usuarios" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/permissions/access": { "get": { "summary": "Obtener permisos de acceso filtrados por restricciones del cliente", "tags": [ "Usuarios - Permisos" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene los permisos de acceso disponibles para el cliente, excluyendo aquellos bloqueados por las restricciones del cliente", "responses": { "200": { "description": "Lista de permisos de acceso filtrados obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "label": { "type": "string" } }, "required": [ "_id", "name", "description", "label" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/permissions/action": { "get": { "summary": "Obtener permisos de acción filtrados por restricciones del cliente", "tags": [ "Usuarios - Permisos" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene los permisos de acción disponibles para el cliente, excluyendo aquellos bloqueados por las restricciones del cliente", "responses": { "200": { "description": "Lista de permisos de acción filtrados obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "label": { "type": "string" } }, "required": [ "_id", "name", "description", "label" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences": { "post": { "summary": "Crear una nueva geofence en Flespi", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Crea una nueva geofence (geocerca) directamente en Flespi y la asigna automáticamente al calculator de geofences.\nSoporta tres tipos de geometrías:\n- **circle**: Requiere center (lat, lng) y radius (en metros)\n- **polygon**: Requiere un array de points (mínimo 3 puntos)\n- **corridor**: Requiere un array de points (mínimo 2 puntos) y width (ancho en metros)\n\n**Nota importante sobre el campo type:**\n- El campo `type` debe enviarse en la raíz del JSON\n- Ya no se incluye dentro del objeto `geometry`\n- Este campo es requerido y debe ser uno de: circle, polygon, o corridor\n\nCampos opcionales personalizados (se guardan automáticamente en metadata de Flespi):\n- **address**: Dirección física de la geofence\n- **color**: Código de color en formato HEX (ej: \"#FF0000\")\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type", "geometry" ], "properties": { "name": { "type": "string", "description": "Nombre de la geofence", "example": "Almacén Central" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ], "description": "Tipo de geometría (requerido)", "example": "circle" }, "address": { "type": "string", "description": "Dirección física", "example": "Av. Principal 123, Lima, Perú" }, "color": { "type": "string", "description": "Color en formato HEX", "example": "#FF0000" }, "geometry": { "oneOf": [ { "type": "object", "title": "Geometría Circle", "required": [ "center", "radius" ], "properties": { "center": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "example": -12.0464 }, "lng": { "type": "number", "example": -77.0428 } } }, "radius": { "type": "number", "description": "Radio (metros)", "example": 500 } } }, { "type": "object", "title": "Geometría Polygon", "required": [ "points" ], "properties": { "points": { "type": "array", "minItems": 3, "items": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } } } }, { "type": "object", "title": "Geometría Corridor", "required": [ "points", "width" ], "properties": { "points": { "type": "array", "minItems": 2, "description": "Array de puntos que definen la polilínea", "items": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "Ancho del corredor (metros)", "example": 100 } } } ] } } } } } }, "responses": { "201": { "description": "Geofence creada exitosamente en Flespi y asignada al calculator", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "MongoDB ObjectId de la geocerca" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ] }, "name": { "type": "string" }, "color": { "type": "string", "description": "HEX (ej: #FF0000)" }, "overlay": { "type": "string" }, "address": { "type": "string" }, "clientId": { "type": "string" }, "geometry": { "type": "object", "properties": { "center": { "type": "object", "description": "Solo para circle", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "radius": { "type": "number", "description": "metros, solo para circle" }, "points": { "type": "array", "description": "Para polygon y corridor", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "metros, solo para corridor" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "get": { "summary": "Obtener geofences del cliente autenticado", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene todas las geofences (geocercas) del cliente autenticado desde Flespi.\nEl sistema automáticamente filtra las geofences por el `clientId` del usuario autenticado,\nque se encuentra almacenado en el campo `metadata.clientId` de cada geofence en Flespi.\n", "responses": { "200": { "description": "Lista de geofences del cliente obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "MongoDB ObjectId de la geocerca" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ] }, "name": { "type": "string" }, "color": { "type": "string", "description": "HEX (ej: #FF0000)" }, "overlay": { "type": "string" }, "address": { "type": "string" }, "clientId": { "type": "string" }, "geometry": { "type": "object", "properties": { "center": { "type": "object", "description": "Solo para circle", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "radius": { "type": "number", "description": "metros, solo para circle" }, "points": { "type": "array", "description": "Para polygon y corridor", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "metros, solo para corridor" } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar múltiples geocercas por _id", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Elimina varias geocercas por sus _id de MongoDB, tanto en Flespi como en la base de datos.\n\n**Comportamiento:**\n- Solo se eliminan geocercas que pertenecen al cliente autenticado (`clientId` del token)\n- Cada _id se resuelve a la geocerca en MongoDB; si no existe o no es del cliente, se reporta en `errors`\n- Para cada geocerca encontrada se elimina en Flespi y en MongoDB (reutilizando la lógica de eliminación simple)\n- Si falla la eliminación de una geocerca, se registra el error y se continúa con las demás\n\n**Notas:**\n- Los IDs deben ser ObjectId de MongoDB (24 caracteres hexadecimales)\n- La respuesta incluye `deletedCount` y un array `errors` con los _id que no se encontraron o fallaron\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "ObjectId de la geocerca en MongoDB" }, "description": "Array de _id de geocercas a eliminar" }, "example": [ "507f1f77bcf86cd799439011", "507f191e810c19729de860ea" ] } } }, "responses": { "200": { "description": "Eliminación completada (parcial o total)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deletedCount": { "type": "number", "description": "Cantidad de geocercas eliminadas exitosamente", "example": 3 }, "errors": { "type": "array", "description": "Errores por _id (no encontrada o fallo al eliminar)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "_id de la geocerca que falló o no se encontró", "example": "507f1f77bcf86cd799439011" }, "error": { "type": "string", "description": "Mensaje de error", "example": "Geocerca no encontrada" } } }, "example": [] } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/import": { "post": { "summary": "Subir y procesar archivo KML/KMZ", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Sube un archivo KML o KMZ y procesa automáticamente todas las ubicaciones (placemarks) encontradas.\nPara cada placemark válido:\n- Se extrae el nombre, color y geometría\n- Se calcula el centro de la geometría para geocoding inverso\n- Se obtiene la dirección usando Azure Maps\n- Se crea una geofence en Flespi con los datos extraídos\n\n**Tipos de geometría soportados:**\n- **Point**: Se convierte en circle con radio por defecto de 100m\n- **Polygon**: Se mantiene como polygon con los puntos del outerBoundaryIs\n- **LineString**: Se convierte en corridor con ancho por defecto de 10m\n\n**Notas:**\n- El color se extrae de los estilos KML (PolyStyle o LineStyle)\n- Si no se encuentra color, se usa #FF0000 por defecto\n- Si el geocoding falla, la geofence se crea sin dirección\n- Los errores en geofences individuales no detienen el proceso completo\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Archivo KML o KMZ (tamaño máximo 50MB)" } } } } } }, "responses": { "200": { "description": "Archivo procesado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "totalProcessed": { "type": "number", "description": "Total de placemarks procesados del archivo", "example": 5 }, "totalCreated": { "type": "number", "description": "Total de geofences creadas exitosamente", "example": 4 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/export": { "post": { "summary": "Exportar geocercas seleccionadas a archivo KML", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo KML con las geocercas indicadas por sus _id de MongoDB.\n\n**Comportamiento:**\n- Solo se exportan geocercas que pertenecen al cliente autenticado (`clientId` del token)\n- Los círculos se exportan como Point con ExtendedData (geometryType, radius) para conservar el tipo al re-importar\n- Los polígonos y corredores se exportan con su geometría\n- El archivo se devuelve como descarga con nombre `geofences.kml`\n\n**Notas:**\n- Los IDs deben ser ObjectId de MongoDB (24 caracteres hexadecimales)\n- Si no se encuentra ninguna geocerca con los IDs proporcionados para el cliente, se responde 404\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "ObjectId de la geocerca en MongoDB" }, "description": "Array de _id de geocercas a exportar a KML" } } } }, "responses": { "200": { "description": "Archivo KML generado exitosamente", "content": { "application/vnd.google-earth.kml+xml": { "schema": { "type": "string", "format": "binary", "description": "Contenido del archivo KML" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/{id}": { "get": { "summary": "Obtener una geofence por ID", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene una geofence específica por su MongoDB ObjectId.\nRetorna todos los campos almacenados en MongoDB: `geometry`, `color`, `address`, `clientId`, `flespiId` y `type`.\n\nEl `id` a usar es el campo `id` que devuelve el endpoint de lista (`GET /api/geofences`).\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "MongoDB ObjectId de la geofence (24 caracteres hex)", "example": "507f1f77bcf86cd799439011" } ], "responses": { "200": { "description": "Geofence encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "MongoDB ObjectId de la geocerca" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ] }, "name": { "type": "string" }, "color": { "type": "string", "description": "HEX (ej: #FF0000)" }, "overlay": { "type": "string" }, "address": { "type": "string" }, "clientId": { "type": "string" }, "geometry": { "type": "object", "properties": { "center": { "type": "object", "description": "Solo para circle", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "radius": { "type": "number", "description": "metros, solo para circle" }, "points": { "type": "array", "description": "Para polygon y corridor", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "metros, solo para corridor" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar una geofence por ID en Flespi", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Actualiza una geofence existente en Flespi y MongoDB. Permite editar todos los campos, incluyendo la geometría.\n\n**CAMPOS EDITABLES:**\n- ✅ `name` - Nombre de la geofence\n- ✅ `address` - Dirección física\n- ✅ `color` - Color en formato HEX\n- ✅ `geometry` - Geometría completa (tipo, centro, radio, puntos, ancho, etc.)\n- ✅ `type` - Tipo de geofence (circle, polygon, corridor)\n\n**FUNCIONAMIENTO INTERNO:** \nPara permitir la actualización de la geometría, el sistema internamente:\n1. Elimina la geofence existente en Flespi\n2. Crea una nueva geofence con los datos actualizados\n3. Actualiza la referencia en MongoDB\n4. Reasigna la geofence al calculator de geofences\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID de la geofence en Flespi", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type", "geometry" ], "properties": { "name": { "type": "string", "description": "Nombre de la geofence", "example": "Almacén Norte Actualizado" }, "address": { "type": "string", "description": "Dirección física", "example": "Av. Norte 456, Lima, Perú" }, "color": { "type": "string", "description": "Color en formato HEX", "example": "#00FF00" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ], "description": "Tipo de geometría (requerido)", "example": "circle" }, "geometry": { "oneOf": [ { "type": "object", "title": "Geometría Circle", "required": [ "center", "radius" ], "properties": { "center": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "example": -12.0464 }, "lng": { "type": "number", "example": -77.0428 } } }, "radius": { "type": "number", "description": "Radio (metros)", "example": 500 } } }, { "type": "object", "title": "Geometría Polygon", "required": [ "points" ], "properties": { "points": { "type": "array", "minItems": 3, "items": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } } } }, { "type": "object", "title": "Geometría Corridor", "required": [ "points", "width" ], "properties": { "points": { "type": "array", "minItems": 2, "description": "Array de puntos que definen la polilínea", "items": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "Ancho del corredor (metros)", "example": 100 } } } ] } } } } } }, "responses": { "200": { "description": "Geofence actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "MongoDB ObjectId de la geocerca" }, "type": { "type": "string", "enum": [ "circle", "polygon", "corridor" ] }, "name": { "type": "string" }, "color": { "type": "string", "description": "HEX (ej: #FF0000)" }, "overlay": { "type": "string" }, "address": { "type": "string" }, "clientId": { "type": "string" }, "geometry": { "type": "object", "properties": { "center": { "type": "object", "description": "Solo para circle", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "radius": { "type": "number", "description": "metros, solo para circle" }, "points": { "type": "array", "description": "Para polygon y corridor", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "width": { "type": "number", "description": "metros, solo para corridor" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/alerts": { "get": { "summary": "Obtener todas las alertas", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de alertas (campos base; sin campos específicos por tipo)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "description": "Elemento de listado de alertas (GET todas). Solo campos base más identificadores y timestamps.\nEn la respuesta, las refs vienen pobladas: alertTriggerId como { _id, name, label }; assets como array de { _id, name, plate }; users como array de { _id, name, email }; clientId como { _id, name }.\n", "properties": { "_id": { "type": "string", "description": "ID de la alerta" }, "clientId": { "type": "string", "description": "ID del cliente" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "clientId" ] } ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } }, "post": { "summary": "Crear una nueva alerta", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "description": "Crea una nueva alerta. El payload se valida según el tipo de trigger (alertTriggerId):\n- **speed_limit:** Requiere speedLimit (km/h); minDuration opcional. Crea calculator en Flespi.\n- **geofence:** Requiere geofences (array de ObjectIds, al menos una) y geofenceActivationType (entrance, exit o both).\n- **ignition** y **lost_connection:** Solo campos base; no requieren campos adicionales.\nLos canales de notificación (typeNotification) exigen que los arrays emails/phones/users no estén vacíos cuando el canal está activo.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h. Obligatorio para tipo exceso de velocidad. Crea calculator en Flespi automáticamente." }, "minDuration": { "type": "number", "description": "Duración mínima en segundos. Por defecto 30 para exceso de velocidad." } }, "required": [ "speedLimit" ] } ] }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "geofences": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "IDs de las geocercas (ObjectId). Obligatorio para tipo geocerca (al menos una)." }, "geofenceActivationType": { "type": "string", "enum": [ "entrance", "exit", "both" ], "description": "Cuándo disparar la alerta: entrance (entrada), exit (salida) o both (ambas). Obligatorio para tipo geocerca." } }, "required": [ "geofences", "geofenceActivationType" ] } ] }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de encendido/apagado. Solo campos base; no requiere campos adicionales." }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de pérdida de conexión. Solo campos base; no requiere campos adicionales." } ], "description": "Payload de creación/edición de alerta según tipo (discriminado por alertTriggerId). La validación exige los campos del tipo correspondiente." } } } }, "responses": { "201": { "description": "Alerta creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Alerta completa (respuesta del servidor). Incluye todos los campos posibles según el tipo.", "properties": { "alertTriggerId": { "type": "string" }, "name": { "type": "string" }, "assets": { "type": "array", "items": { "type": "string" } }, "users": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "phones": { "type": "array", "items": { "type": "string" } }, "clientId": { "type": "string" }, "typeNotification": { "type": "object", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean" }, "description": { "type": "string" }, "speedLimit": { "type": "number", "description": "km/h. Solo para tipo exceso de velocidad." }, "minDuration": { "type": "number", "description": "Segundos. Solo para tipo exceso de velocidad." }, "geofences": { "type": "array", "items": { "type": "string" }, "description": "Solo para tipo geocerca." }, "geofenceActivationType": { "type": "string", "enum": [ "entrance", "exit", "both" ], "description": "Solo para tipo geocerca: entrance, exit o both." }, "calculatorId": { "type": "number", "description": "Se asigna automáticamente por el sistema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "alertTriggerId", "name", "assets", "users", "clientId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/alerts/{id}": { "get": { "summary": "Obtener una alerta por ID", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Detalles de la alerta según el tipo de trigger (speed_limit, geofence, ignition, lost_connection)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "oneOf": [ { "allOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h. Obligatorio para tipo exceso de velocidad. Crea calculator en Flespi automáticamente." }, "minDuration": { "type": "number", "description": "Duración mínima en segundos. Por defecto 30 para exceso de velocidad." } }, "required": [ "speedLimit" ] } ] }, { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "calculatorId": { "type": "number", "description": "Se asigna automáticamente por el sistema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, { "allOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "geofences": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "IDs de las geocercas (ObjectId). Obligatorio para tipo geocerca (al menos una)." }, "geofenceActivationType": { "type": "string", "enum": [ "entrance", "exit", "both" ], "description": "Cuándo disparar la alerta: entrance (entrada), exit (salida) o both (ambas). Obligatorio para tipo geocerca." } }, "required": [ "geofences", "geofenceActivationType" ] } ] }, { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, { "allOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de encendido/apagado. Solo campos base; no requiere campos adicionales." }, { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, { "allOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de pérdida de conexión. Solo campos base; no requiere campos adicionales." }, { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] } ], "description": "Detalle de alerta según tipo de trigger (GET por ID). Discriminado por alertTriggerId." } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } }, "put": { "summary": "Actualizar una alerta por ID", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "description": "Actualiza una alerta existente. El payload se valida según el tipo de trigger (alertTriggerId en el body o el de la alerta actual).\nMismas reglas que creación: speed_limit requiere speedLimit; geofence requiere geofences y geofenceActivationType; ignition y lost_connection solo base.\nSi se modifican speedLimit, geofences o minDuration, el sistema actualiza el calculator en Flespi.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h. Obligatorio para tipo exceso de velocidad. Crea calculator en Flespi automáticamente." }, "minDuration": { "type": "number", "description": "Duración mínima en segundos. Por defecto 30 para exceso de velocidad." } }, "required": [ "speedLimit" ] } ] }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "properties": { "geofences": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "IDs de las geocercas (ObjectId). Obligatorio para tipo geocerca (al menos una)." }, "geofenceActivationType": { "type": "string", "enum": [ "entrance", "exit", "both" ], "description": "Cuándo disparar la alerta: entrance (entrada), exit (salida) o both (ambas). Obligatorio para tipo geocerca." } }, "required": [ "geofences", "geofenceActivationType" ] } ] }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de encendido/apagado. Solo campos base; no requiere campos adicionales." }, { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] } ], "description": "Alerta de pérdida de conexión. Solo campos base; no requiere campos adicionales." } ], "description": "Payload de creación/edición de alerta según tipo (discriminado por alertTriggerId). La validación exige los campos del tipo correspondiente." } } } }, "responses": { "200": { "description": "Alerta actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Alerta completa (respuesta del servidor). Incluye todos los campos posibles según el tipo.", "properties": { "alertTriggerId": { "type": "string" }, "name": { "type": "string" }, "assets": { "type": "array", "items": { "type": "string" } }, "users": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "phones": { "type": "array", "items": { "type": "string" } }, "clientId": { "type": "string" }, "typeNotification": { "type": "object", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean" }, "description": { "type": "string" }, "speedLimit": { "type": "number", "description": "km/h. Solo para tipo exceso de velocidad." }, "minDuration": { "type": "number", "description": "Segundos. Solo para tipo exceso de velocidad." }, "geofences": { "type": "array", "items": { "type": "string" }, "description": "Solo para tipo geocerca." }, "geofenceActivationType": { "type": "string", "enum": [ "entrance", "exit", "both" ], "description": "Solo para tipo geocerca: entrance, exit o both." }, "calculatorId": { "type": "number", "description": "Se asigna automáticamente por el sistema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "alertTriggerId", "name", "assets", "users", "clientId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar una alerta por ID", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "description": "Elimina una alerta. Si la alerta tiene un calculatorId asociado, el sistema automáticamente \nremoverá los dispositivos del calculator en Flespi antes de eliminar la alerta.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Alerta eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Alerta eliminada correctamente" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/alerts/{id}/state": { "patch": { "summary": "Actualizar el estado de una alerta", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "description": "Actualiza el estado de una alerta. Si el estado se cambia a false y la alerta tiene un calculatorId asociado, \nel sistema automáticamente removerá los dispositivos del calculator en Flespi para desactivar la alerta.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "boolean", "description": "Estado de la alerta (true para activa, false para inactiva). \nSi se cambia a false, se removerán automáticamente los dispositivos del calculator.\n" } }, "required": [ "state" ] } } } }, "responses": { "200": { "description": "Estado de la alerta actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Estado de la alerta actualizado correctamente" }, "state": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/alert-triggers": { "get": { "summary": "Obtener todos los disparadores de alerta", "tags": [ "Alertas - Disparadores" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de disparadores de alerta", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } }, "post": { "summary": "Crear un nuevo disparador de alerta", "tags": [ "Alertas - Disparadores" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } }, "responses": { "201": { "description": "Disparador de alerta creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } } }, "/api/alert-triggers/{id}": { "get": { "summary": "Obtener un disparador de alerta por ID", "tags": [ "Alertas - Disparadores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Detalles del disparador de alerta", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } }, "put": { "summary": "Actualizar un disparador de alerta por ID", "tags": [ "Alertas - Disparadores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } }, "responses": { "200": { "description": "Disparador de alerta actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } }, "delete": { "summary": "Eliminar un disparador de alerta por ID", "tags": [ "Alertas - Disparadores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Disparador de alerta eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } } }, "/api/notifications": { "get": { "summary": "Obtener listado paginado de notificaciones", "description": "Retorna notificaciones del cliente en formato simplificado (NotificationBase) con paginación offset-based.\nSoporta filtros multi-valor por tipo de alerta, estado y activo, además de rango de fechas.\nSi no se especifica rango de fechas, retorna los últimos 30 días.\nIncluye conteo global de notificaciones no revisadas independiente de los filtros activos.\n", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "description": "Número de página (mínimo 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Cantidad de resultados por página (máximo 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "types", "in": "query", "description": "Filtrar por tipo de alerta. Repetible: `?types=speed_limit&types=geofence`. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection", "road_speed_limit", "sos_alarm", "temperature" ] } } }, { "name": "status", "in": "query", "description": "Filtrar por estado de la notificación. Repetible: `?status=unreviewed&status=false_positive`. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] } } }, { "name": "assetIds", "in": "query", "description": "Filtrar por ID(s) de activo (ObjectId de 24 caracteres hexadecimales). Repetible: `?assetIds=ID1&assetIds=ID2`. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "example": [ "507f1f77bcf86cd799439011" ] } }, { "name": "startDate", "in": "query", "description": "Fecha de inicio del rango (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "description": "Fecha de fin del rango (ISO 8601)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Listado paginado de notificaciones con metadata", "content": { "application/json": { "schema": { "type": "object", "description": "Respuesta paginada del listado de notificaciones", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "description": "Payload simplificado para listado de notificaciones (sin positions ni campos pesados)", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection" ] }, "name": { "type": "string", "description": "Nombre de la alerta" }, "alertTrigger": { "type": "object", "description": "Trigger de alerta asociado", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" } } }, "asset": { "type": "object", "description": "Activo asociado a la notificación", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } }, "location": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] }, "calculatorId": { "type": "number", "nullable": true, "description": "ID del calculator en Flespi (opcional)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "alertTrigger", "asset", "location", "address", "status", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "description": "Metadata de paginación", "properties": { "page": { "type": "integer", "description": "Página actual", "example": 1 }, "limit": { "type": "integer", "description": "Cantidad de resultados por página", "example": 20 }, "total": { "type": "integer", "description": "Total de resultados con los filtros aplicados", "example": 45 }, "totalPages": { "type": "integer", "description": "Total de páginas", "example": 3 } }, "required": [ "page", "limit", "total", "totalPages" ] }, "unreviewedCount": { "type": "integer", "description": "Conteo global de notificaciones no revisadas (independiente de filtros de tipo/status)", "example": 12 } }, "required": [ "notifications", "pagination", "unreviewedCount" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/notifications/status": { "patch": { "summary": "Actualizar estado de múltiples notificaciones", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "description": "Actualiza el estado de múltiples notificaciones en una sola operación.\nSolo se actualizan las notificaciones que pertenecen al cliente autenticado.\nSi algunos IDs no existen o no pertenecen al cliente, simplemente no se actualizan (reflejado en modifiedCount).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "minItems": 1, "description": "Lista de IDs de notificaciones (ObjectId de 24 caracteres hexadecimales)", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ], "description": "Nuevo estado para las notificaciones" } }, "required": [ "ids", "status" ] } } } }, "responses": { "200": { "description": "Notificaciones actualizadas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Estados de notificaciones actualizados correctamente" }, "modifiedCount": { "type": "integer", "description": "Cantidad de notificaciones efectivamente actualizadas", "example": 5 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/notifications/{id}": { "get": { "summary": "Obtener detalle de una notificación por ID", "description": "Retorna la notificación completa según su tipo (NotificationDetail).\nEl payload incluye campos específicos por tipo: speed_limit, geofence, ignition, lost_connection.\n", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Detalle de la notificación (NotificationDetail según type)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "oneOf": [ { "allOf": [ { "type": "object", "description": "Payload simplificado para listado de notificaciones (sin positions ni campos pesados)", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection" ] }, "name": { "type": "string", "description": "Nombre de la alerta" }, "alertTrigger": { "type": "object", "description": "Trigger de alerta asociado", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" } } }, "asset": { "type": "object", "description": "Activo asociado a la notificación", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } }, "location": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] }, "calculatorId": { "type": "number", "nullable": true, "description": "ID del calculator en Flespi (opcional)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "alertTrigger", "asset", "location", "address", "status", "createdAt", "updatedAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "speed_limit" ] }, "maxSpeed": { "type": "number" }, "initialSpeed": { "type": "number" }, "speedLimit": { "type": "number" }, "duration": { "type": "number" }, "route": { "type": "string", "nullable": true }, "positions": { "type": "array", "items": { "type": "object", "description": "Punto de posición (lat, lng, fecha, opcional velocidad)", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "at": { "type": "string", "format": "date-time" }, "speed": { "type": "number", "description": "Velocidad (opcional)" } } } }, "initialAddress": { "type": "string", "nullable": true }, "finalAddress": { "type": "string", "nullable": true } } } ] }, { "allOf": [ { "type": "object", "description": "Payload simplificado para listado de notificaciones (sin positions ni campos pesados)", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection" ] }, "name": { "type": "string", "description": "Nombre de la alerta" }, "alertTrigger": { "type": "object", "description": "Trigger de alerta asociado", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" } } }, "asset": { "type": "object", "description": "Activo asociado a la notificación", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } }, "location": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] }, "calculatorId": { "type": "number", "nullable": true, "description": "ID del calculator en Flespi (opcional)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "alertTrigger", "asset", "location", "address", "status", "createdAt", "updatedAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "geofence" ] }, "geofenceId": { "type": "string", "nullable": true }, "geofenceName": { "type": "string", "nullable": true }, "activationType": { "type": "string", "enum": [ "enter", "exit" ] }, "duration": { "type": "number" }, "positions": { "type": "array", "items": { "type": "object", "description": "Punto de posición (lat, lng, fecha, opcional velocidad)", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "at": { "type": "string", "format": "date-time" }, "speed": { "type": "number", "description": "Velocidad (opcional)" } } } } } } ] }, { "allOf": [ { "type": "object", "description": "Payload simplificado para listado de notificaciones (sin positions ni campos pesados)", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection" ] }, "name": { "type": "string", "description": "Nombre de la alerta" }, "alertTrigger": { "type": "object", "description": "Trigger de alerta asociado", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" } } }, "asset": { "type": "object", "description": "Activo asociado a la notificación", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } }, "location": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] }, "calculatorId": { "type": "number", "nullable": true, "description": "ID del calculator en Flespi (opcional)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "alertTrigger", "asset", "location", "address", "status", "createdAt", "updatedAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ignition" ] }, "ignitionState": { "type": "boolean" }, "positions": { "type": "array", "items": { "type": "object", "description": "Punto de posición (lat, lng, fecha, opcional velocidad)", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "at": { "type": "string", "format": "date-time" }, "speed": { "type": "number", "description": "Velocidad (opcional)" } } } }, "duration": { "type": "number" } } } ] }, { "allOf": [ { "type": "object", "description": "Payload simplificado para listado de notificaciones (sin positions ni campos pesados)", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection" ] }, "name": { "type": "string", "description": "Nombre de la alerta" }, "alertTrigger": { "type": "object", "description": "Trigger de alerta asociado", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" } } }, "asset": { "type": "object", "description": "Activo asociado a la notificación", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" }, "icon": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" } } } } }, "location": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] }, "calculatorId": { "type": "number", "nullable": true, "description": "ID del calculator en Flespi (opcional)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "alertTrigger", "asset", "location", "address", "status", "createdAt", "updatedAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "lost_connection" ] }, "duration": { "type": "number" }, "initialAddress": { "type": "string", "nullable": true }, "finalAddress": { "type": "string", "nullable": true }, "positions": { "type": "array", "items": { "type": "object", "description": "Punto de posición (lat, lng, fecha, opcional velocidad)", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "at": { "type": "string", "format": "date-time" }, "speed": { "type": "number", "description": "Velocidad (opcional)" } } } } } } ] } ], "description": "Detalle de notificación según tipo de alerta (discriminado por type)" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar una notificación por ID", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Notificación eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Notificación eliminada correctamente" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/notifications/{id}/navigation": { "get": { "summary": "Obtener notificaciones vecinas (anterior/siguiente)", "description": "Retorna los ids de la notificación anterior y siguiente dentro del listado\nordenado (mismo orden y filtros que la grilla: `createdAt` descendente).\nAcepta los mismos filtros que el listado (types, status, assetIds, startDate,\nendDate) para que los vecinos coincidan con lo que ve el usuario. Cada extremo\nes `null` cuando la notificación es el primer o último elemento del conjunto.\nSirve a la navegación Anterior/Siguiente de la vista de detalle, sin depender\nde la página cacheada (funciona en deep-link y tras refresh).\n", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" }, { "name": "types", "in": "query", "description": "Filtrar por tipo de alerta. Repetible. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "speed_limit", "geofence", "ignition", "lost_connection", "road_speed_limit", "sos_alarm", "temperature" ] } } }, { "name": "status", "in": "query", "description": "Filtrar por estado. Repetible. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ] } } }, { "name": "assetIds", "in": "query", "description": "Filtrar por activo. Repetible. Acepta también un solo valor escalar.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "startDate", "in": "query", "description": "Fecha inicial del rango (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "description": "Fecha final del rango (ISO 8601)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Ids de las notificaciones vecinas", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "previousId": { "type": "string", "nullable": true, "example": "6630f1c2a1b2c3d4e5f60718" }, "nextId": { "type": "string", "nullable": true, "example": "6630f1c2a1b2c3d4e5f6071a" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/notifications/{id}/status": { "patch": { "summary": "Actualizar el estado de una notificación", "tags": [ "Alertas - Notificaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ], "description": "Nuevo estado de la notificación (unreviewed, reviewed, false_positive)" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Estado de la notificación actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Estado de la notificación actualizado correctamente" }, "status": { "type": "string", "enum": [ "unreviewed", "reviewed", "false_positive" ], "example": "reviewed" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/drivers": { "get": { "summary": "Obtener todos los conductores", "tags": [ "Otros - Conductores" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de conductores", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un nuevo conductor", "description": "Crea un nuevo conductor en el sistema.\n\n**Datos requeridos:**\n- `rut` (string): RUT del conductor\n- `phone` (string): Número de teléfono del conductor\n- `firstname` (string): Nombre del conductor\n- `lastname` (string): Apellido del conductor\n- `email` (string): Correo electrónico del conductor\n- `address` (string): Dirección del conductor\n- `city` (string): Ciudad del conductor\n- `clientId` (string): ID del cliente asociado\n", "tags": [ "Otros - Conductores" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } }, "responses": { "201": { "description": "Conductor creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } } } }, "400": { "description": "Ya existe un conductor con el mismo RUT", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Ya existe un conductor con el mismo RUT" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/drivers/{id}": { "get": { "summary": "Obtener un conductor por ID", "tags": [ "Otros - Conductores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Detalles del conductor", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un conductor por ID", "description": "Actualiza un conductor existente. Solo se actualizan los campos proporcionados.\n\n**Datos que se pueden actualizar:**\n- `rut` (string): RUT del conductor\n- `phone` (string): Número de teléfono del conductor\n- `firstname` (string): Nombre del conductor\n- `lastname` (string): Apellido del conductor\n- `email` (string): Correo electrónico del conductor\n- `address` (string): Dirección del conductor\n- `city` (string): Ciudad del conductor\n- `clientId` (string): ID del cliente asociado\n", "tags": [ "Otros - Conductores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } }, "responses": { "200": { "description": "Conductor actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "rut": { "type": "string" }, "phone": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "clientId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "rut", "phone", "firstname", "lastname", "email", "address", "city", "clientId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un conductor por ID", "tags": [ "Otros - Conductores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Conductor eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Conductor eliminado correctamente" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/flespi/device-types": { "get": { "summary": "Obtener los tipos de dispositivos desde Flespi", "tags": [ "Integraciones - Flespi" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de tipos de dispositivos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID del tipo de dispositivo" }, "name": { "type": "string", "description": "Nombre del tipo de dispositivo" } } } } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/flespi/devices/{deviceId}/outputs": { "put": { "summary": "Actualizar output1 de un dispositivo en Flespi", "description": "Actualiza el output1 de un dispositivo específico en Flespi.\nEl sistema detecta el modelo de hardware del tracker y usa el metodo de control correspondiente:\n\n| Modelo | Metodo | Descripcion |\n|--------|--------|-------------|\n| FMC130 (Teltonika) | PUT settings/outputs3 | Controla output1 del dispositivo |\n| FMC150 (Teltonika) | PUT settings/outputs2 | Controla output1 del dispositivo |\n| GV20 (Concox) | POST commands → setting.relay_action.set | Controla corta corriente via relay |\n| BTG01L | POST commands → custom AT+GTOUT | Controla corta corriente via comando AT |\n\nSi el modelo del tracker no es soportado, retorna error 400.\n", "tags": [ "Integraciones - Flespi" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "output1": { "type": "boolean", "description": "Estado del output/corta corriente:\n- FMC130: true para activar output1, false para desactivar\n- GV20: true para cortar corriente, false para restaurar\n- BTG01L: true para cortar corriente, false para restaurar\n" } }, "required": [ "output1" ] } } } }, "responses": { "200": { "description": "Outputs actualizados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "description": "Respuesta de la API de Flespi" }, "model": { "type": "string", "description": "Modelo del dispositivo detectado automaticamente", "example": "FMC130", "enum": [ "FMC130", "FMC150", "GV20", "BTG01L" ] }, "action": { "type": "string", "description": "Descripcion de la accion realizada", "example": "Output1 activado" }, "supportsOutputState": { "type": "boolean", "description": "El modelo confirma el estado aplicado por settings (Teltonika FMC130/FMC150).\nEn GV20 y BTG01L es false y la confirmación queda a cargo de la telemetría.\n", "example": true }, "output1": { "type": "boolean", "nullable": true, "description": "Estado aplicado de la salida 1 según la respuesta del dispositivo al comando", "example": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Momento en que Flespi registró el estado aplicado", "example": "2026-08-17T02:08:28.640Z" }, "hasPendingChange": { "type": "boolean", "description": "El comando quedó encolado porque el dispositivo no está conectado; mientras sea\ntrue, output1 todavía refleja el valor anterior.\n", "example": false } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/flespi/devices/{deviceId}/output": { "get": { "summary": "Obtener el estado aplicado de los outputs de un dispositivo en Flespi", "description": "Devuelve el estado que el dispositivo confirmó al ejecutar el último comando de outputs.\n\nEl setting se resuelve según el modelo del tracker (outputs3 en FMC130, outputs2 en\nFMC150). Flespi actualiza este valor en menos de un segundo, mucho antes de que el\nestado de la salida viaje en la telemetría, por eso es la fuente recomendada para\nconfirmar un comando de corta corriente.\n\nSólo aplica a Teltonika FMC130/FMC150; GV20 y BTG01L usan comando dedicado y responden\nerror de validación.\n", "tags": [ "Integraciones - Flespi" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo" } ], "responses": { "200": { "description": "Configuración de outputs del dispositivo obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "description": "Valores crudos del setting de outputs, tal como los reporta Flespi", "properties": { "out1": { "type": "boolean", "description": "Estado del output 1", "example": true }, "out2": { "type": "boolean", "description": "Estado del output 2", "example": false }, "out3": { "type": "boolean", "description": "Estado del output 3 (sólo FMC130)", "example": false } } }, "output1": { "type": "boolean", "nullable": true, "description": "Estado aplicado de la salida 1 (corta corriente); null si Flespi todavía no lo conoce", "example": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Momento en que Flespi registró el estado aplicado", "example": "2026-08-17T02:08:28.640Z" }, "hasPendingChange": { "type": "boolean", "description": "El dispositivo todavía no confirmó el último cambio pedido; mientras sea true, output1 es el valor anterior", "example": false }, "supportsOutputState": { "type": "boolean", "description": "El modelo expone el estado aplicado por settings (Teltonika FMC130/FMC150)", "example": true }, "model": { "type": "string", "description": "Modelo del dispositivo detectado automáticamente", "example": "FMC130" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/flespi/devices/{deviceId}/resend-gps": { "put": { "summary": "Vuelve a enviar los datos del dispositivo en Flespi", "description": "Envia mensaje al gps para que vuelva a enviar los datos del dispositivo.", "tags": [ "Integraciones - Flespi" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo" } ], "responses": { "200": { "description": "Datos del dispositivo reenviados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Respuesta de la API de Flespi" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/layers": { "post": { "summary": "Crear una nueva capa", "tags": [ "Otros - Capas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Etiqueta de la capa" }, "file": { "type": "string", "format": "binary", "description": "Archivo KML" } }, "required": [ "label", "file" ] } } } }, "responses": { "201": { "description": "Capa creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "label": { "type": "string" }, "file": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "label", "file" ] } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } }, "get": { "summary": "Obtener todas las capas", "tags": [ "Otros - Capas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de capas", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "label": { "type": "string" }, "file": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "label", "file" ] } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } } }, "/api/layers/{id}": { "get": { "summary": "Obtener una capa por ID", "tags": [ "Otros - Capas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Capa encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "label": { "type": "string" }, "file": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "label", "file" ] } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } }, "put": { "summary": "Actualizar una capa", "tags": [ "Otros - Capas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Etiqueta de la capa" }, "file": { "type": "string", "format": "binary", "description": "Archivo KML" } } } } } }, "responses": { "200": { "description": "Capa actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "label": { "type": "string" }, "file": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "label", "file" ] } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } }, "delete": { "summary": "Eliminar una capa", "tags": [ "Otros - Capas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Capa eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } } }, "/api/forms/definitions/{key}": { "get": { "summary": "Obtener definición de formulario interno", "description": "Retorna una definición activa para renderizar formularios internos autenticados.", "tags": [ "Formularios" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "feedback" } ], "responses": { "200": { "description": "Definición obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } } }, "/api/forms/submissions": { "post": { "summary": "Enviar formulario interno", "description": "Guarda una respuesta de formulario usando el cliente y usuario de la sesión.", "tags": [ "Formularios" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "formKey", "values" ], "properties": { "formKey": { "type": "string", "example": "feedback" }, "values": { "type": "object", "additionalProperties": true }, "attachments": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Formulario enviado exitosamente", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } } } } }, "/api/positions/stats": { "post": { "summary": "Obtener estadísticas de posiciones de múltiples activos", "tags": [ "Reportes - Historial de Posiciones" ], "security": [ { "bearerAuth": [] } ], "description": "Recibe un array de IDs de activos y un rango de fechas.\nRetorna estadísticas de posiciones GPS por cada activo (velocidad máxima, velocidad promedio,\ndistancia total recorrida, total de posiciones) y estadísticas globales agregadas.\n\nSolo se procesan activos que tengan un tracker Flespi asignado (`mainTrackerId`).\n\n**Rango máximo:** 30 días.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "from", "to" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectId) a consultar", "example": [ "67a1b2c3d4e5f6g7h8i9j0k1", "67a1b2c3d4e5f6g7h8i9j0k2" ] }, "from": { "type": "string", "description": "Fecha de inicio del rango. Formatos: DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "01/03/2026 00:00:00" }, "to": { "type": "string", "description": "Fecha de fin del rango. Formatos: DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "10/03/2026 23:59:59" } } } } } }, "responses": { "200": { "description": "Estadísticas de posiciones obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "assetsPositionsStats": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "description": "ID del activo", "example": "67a1b2c3d4e5f6g7h8i9j0k1" }, "assetName": { "type": "string", "description": "Nombre del activo", "example": "Camión 01" }, "licensePlate": { "type": "string", "description": "Patente del vehículo", "example": "ABCD-12" }, "flespiId": { "type": "integer", "nullable": true, "description": "ID del tracker en Flespi", "example": 1234 }, "stats": { "type": "object", "properties": { "maxSpeed": { "type": "integer", "description": "Velocidad máxima registrada en km/h", "example": 120 }, "avgSpeed": { "type": "integer", "description": "Velocidad promedio en km/h", "example": 45 }, "totalPositions": { "type": "integer", "description": "Cantidad total de posiciones GPS registradas", "example": 1500 }, "totalDistanceKm": { "type": "number", "description": "Distancia total recorrida en kilómetros", "example": 234.5 } } } } } }, "globalStats": { "type": "object", "properties": { "maxSpeed": { "type": "integer", "description": "Velocidad máxima registrada en km/h", "example": 120 }, "avgSpeed": { "type": "integer", "description": "Velocidad promedio en km/h", "example": 45 }, "totalPositions": { "type": "integer", "description": "Cantidad total de posiciones GPS registradas", "example": 1500 }, "totalDistanceKm": { "type": "number", "description": "Distancia total recorrida en kilómetros", "example": 234.5 } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/positions/detail": { "post": { "summary": "Obtener detalle de posiciones de un activo", "tags": [ "Reportes - Historial de Posiciones" ], "security": [ { "bearerAuth": [] } ], "description": "Retorna las posiciones GPS individuales de un activo en un rango de fechas.\nCada posición incluye coordenadas, velocidad, dirección, estado de ignición y satélites.\n\nEl activo debe tener un tracker Flespi asignado (`mainTrackerId`).\n\n**Rango máximo:** 30 días.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "from", "to" ], "properties": { "assetId": { "type": "string", "description": "ID del activo (MongoDB ObjectId)", "example": "67a1b2c3d4e5f6g7h8i9j0k1" }, "from": { "type": "string", "description": "Fecha de inicio del rango. Formatos: DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "01/03/2026 00:00:00" }, "to": { "type": "string", "description": "Fecha de fin del rango. Formatos: DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "10/03/2026 23:59:59" } } } } } }, "responses": { "200": { "description": "Detalle de posiciones obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Timestamp Unix de la posición", "example": 1709251200 }, "lat": { "type": "number", "description": "Latitud", "example": -33.4489 }, "lng": { "type": "number", "description": "Longitud", "example": -70.6693 }, "speed": { "type": "number", "description": "Velocidad en km/h", "example": 60 }, "direction": { "type": "number", "description": "Dirección en grados (0-360)", "example": 180 }, "ignition": { "type": "boolean", "description": "Estado de la ignición del motor", "example": true }, "satellites": { "type": "integer", "description": "Cantidad de satélites GPS conectados", "example": 12 } } } }, "flespiId": { "type": "integer", "description": "ID del tracker en Flespi", "example": 1234 }, "assetName": { "type": "string", "description": "Nombre del activo", "example": "Camión 01" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/speed-excess/stats": { "post": { "summary": "Obtener estadísticas de excesos de velocidad", "tags": [ "Reportes - Excesos de Velocidad" ], "security": [ { "bearerAuth": [] } ], "description": "Recibe N trackers, un límite de velocidad, duración mínima y rango de fechas.\nRetorna estadísticas de excesos de velocidad por tracker, analizando las posiciones\nGPS de los viajes para detectar segmentos donde la velocidad supera el límite.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "speedLimit" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a consultar", "example": [ 1234, 5678 ] }, "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h", "example": 80 }, "minDuration": { "type": "integer", "description": "Duración mínima en segundos para considerar un exceso (default: 0)", "default": 0, "example": 30 } } } } } }, "responses": { "200": { "description": "Estadísticas de excesos de velocidad obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado", "example": 1234 }, "summary": { "nullable": true, "allOf": [ { "type": "object", "properties": { "totalSpeedExcess": { "type": "integer", "description": "Cantidad total de excesos de velocidad", "example": 5 }, "totalDuration": { "type": "number", "description": "Duración total de los excesos en segundos", "example": 3600 }, "averageExcessSpeed": { "type": "integer", "description": "Velocidad promedio durante los excesos en km/h (sin decimales)", "example": 96 }, "maxSpeed": { "type": "number", "description": "Velocidad máxima registrada en km/h", "example": 120 } } } ], "description": "Resumen de excesos o null si no hay excesos" } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/speed-excess": { "post": { "summary": "Obtener detalle de excesos de velocidad de un tracker", "tags": [ "Reportes - Excesos de Velocidad" ], "security": [ { "bearerAuth": [] } ], "description": "Devuelve cada infracción de velocidad individualmente con coordenadas y dirección geocodificada.\nIdeal para mostrar los eventos en un mapa o tabla detallada.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerId", "speedLimit" ], "properties": { "trackerId": { "type": "integer", "description": "ID del tracker (flespiId) a consultar", "example": 7174525 }, "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h", "example": 80 }, "minDuration": { "type": "integer", "description": "Duración mínima en segundos para considerar un exceso (default: 0)", "default": 0, "example": 30 } } } } } }, "responses": { "200": { "description": "Detalle de excesos de velocidad obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado", "example": 7174525 }, "summary": { "nullable": true, "allOf": [ { "type": "object", "properties": { "totalSpeedExcess": { "type": "integer", "description": "Cantidad total de excesos de velocidad", "example": 5 }, "totalDuration": { "type": "number", "description": "Duración total de los excesos en segundos", "example": 3600 }, "averageExcessSpeed": { "type": "integer", "description": "Velocidad promedio durante los excesos en km/h (sin decimales)", "example": 96 }, "maxSpeed": { "type": "number", "description": "Velocidad máxima registrada en km/h", "example": 120 } } } ], "description": "Estadísticas agregadas o null si no hay excesos" }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "description": "Inicio del incidente en formato ISO 8601 con zona horaria", "example": "2025-12-17T10:30:00-03:00" }, "endTime": { "type": "string", "description": "Fin del incidente en formato ISO 8601 con zona horaria", "example": "2025-12-17T10:32:15-03:00" }, "duration": { "type": "integer", "description": "Duración del incidente en segundos", "example": 135 }, "averageSpeed": { "type": "integer", "description": "Velocidad promedio durante el incidente en km/h", "example": 93 }, "maxSpeed": { "type": "number", "description": "Velocidad máxima durante el incidente en km/h", "example": 110 }, "lat": { "type": "number", "description": "Latitud del inicio del incidente", "example": -33.4569 }, "lng": { "type": "number", "description": "Longitud del inicio del incidente", "example": -70.6483 }, "address": { "type": "string", "description": "Dirección geocodificada del inicio del incidente (vacío si no se pudo geocodificar)", "example": "Av. Apoquindo 4700, Las Condes, Santiago" } } }, "description": "Lista de incidentes individuales de exceso (vacía si no hay excesos)" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/trips/export": { "post": { "summary": "Exportar resumen de viajes", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de viajes para los trackers indicados.\n\n**Excel:** tabla plana con estadísticas por asset.\n**PDF:** reporte multi-sección con página de resumen general y una sección por vehículo\ncon viajes agrupados por día y totales diarios. Acepta `fuelNormRate` y `fuelPrice`\npara incluir cálculos de combustible y costo.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a incluir en el reporte", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "fuelNormRate": { "type": "number", "description": "Norma de consumo de combustible (litros/100km). Default: 0", "default": 0, "example": 8.5 }, "fuelPrice": { "type": "number", "description": "Precio del combustible por litro. Default: 0", "default": 0, "example": 1200 } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/stops/export": { "post": { "summary": "Exportar resumen de paradas", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de paradas (estadísticas por asset)\npara los trackers indicados en el rango de fechas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a incluir en el reporte", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/speed-excess/export": { "post": { "summary": "Exportar resumen de excesos de velocidad", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de excesos de velocidad\n(estadísticas por asset) para los trackers indicados.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "speedLimit", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a incluir en el reporte", "example": [ 1234, 5678 ] }, "speedLimit": { "type": "number", "description": "Límite de velocidad en km/h", "example": 80 }, "minDuration": { "type": "integer", "description": "Duración mínima en segundos para considerar un exceso (default: 0)", "default": 0, "example": 30 }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/idle-time/stats": { "post": { "summary": "Obtener estadísticas de ralentí", "tags": [ "Reportes - Ralentí" ], "security": [ { "bearerAuth": [] } ], "description": "Recibe N trackers y un rango de fechas. Retorna estadísticas de ralentí por tracker,\ndetectando periodos donde el vehículo tiene el motor encendido pero no se mueve\n(ignition ON + speed < 3 km/h, duración mínima 3 minutos).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a consultar", "example": [ 1234, 5678 ] } } } } } }, "responses": { "200": { "description": "Estadísticas de ralentí obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado", "example": 1234 }, "summary": { "nullable": true, "allOf": [ { "type": "object", "properties": { "totalIdleEvents": { "type": "integer", "description": "Cantidad total de eventos de ralentí", "example": 12 }, "totalIdleDuration": { "type": "number", "description": "Duración total de ralentí en segundos", "example": 7200 }, "avgIdleDuration": { "type": "number", "description": "Duración promedio de ralentí en segundos", "example": 600 }, "maxIdleDuration": { "type": "number", "description": "Duración máxima de un evento de ralentí en segundos", "example": 1800 } } } ], "description": "Resumen de ralentí o null si no hay eventos" } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/idle-time": { "post": { "summary": "Obtener detalle de ralentí de un tracker", "tags": [ "Reportes - Ralentí" ], "security": [ { "bearerAuth": [] } ], "description": "Devuelve cada evento de ralentí individualmente con coordenadas y dirección geocodificada.\nIdeal para mostrar los eventos en un mapa o tabla detallada.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerId" ], "properties": { "trackerId": { "type": "integer", "description": "ID del tracker (flespiId) a consultar", "example": 7174525 } } } } } }, "responses": { "200": { "description": "Detalle de ralentí obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado", "example": 7174525 }, "summary": { "nullable": true, "allOf": [ { "type": "object", "properties": { "totalIdleEvents": { "type": "integer", "description": "Cantidad total de eventos de ralentí", "example": 12 }, "totalIdleDuration": { "type": "number", "description": "Duración total de ralentí en segundos", "example": 7200 }, "avgIdleDuration": { "type": "number", "description": "Duración promedio de ralentí en segundos", "example": 600 }, "maxIdleDuration": { "type": "number", "description": "Duración máxima de un evento de ralentí en segundos", "example": 1800 } } } ], "description": "Estadísticas agregadas o null si no hay eventos" }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string", "description": "Inicio del evento en formato ISO 8601 con zona horaria", "example": "2025-12-17T10:30:00-03:00" }, "endTime": { "type": "string", "description": "Fin del evento en formato ISO 8601 con zona horaria", "example": "2025-12-17T10:45:00-03:00" }, "duration": { "type": "integer", "description": "Duración del evento en segundos", "example": 900 }, "lat": { "type": "number", "description": "Latitud del evento", "example": -33.4569 }, "lng": { "type": "number", "description": "Longitud del evento", "example": -70.6483 }, "address": { "type": "string", "description": "Dirección geocodificada del evento", "example": "Av. Apoquindo 4700, Las Condes, Santiago" } } }, "description": "Lista de incidentes individuales de ralentí" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/idle-time/export": { "post": { "summary": "Exportar resumen de ralentí", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de ralentí\n(estadísticas por asset) para los trackers indicados.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a incluir en el reporte", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/working-hours/stats": { "post": { "summary": "Obtener estadísticas de horas de trabajo", "tags": [ "Reportes - Horas de Trabajo" ], "security": [ { "bearerAuth": [] } ], "description": "Recibe N trackers y un rango de fechas. Retorna estadísticas de horas de trabajo\npor tracker: viajes, paradas dentro de viajes, tiempo de conducción, tiempo de paradas\ny tiempo total de trabajo, filtrado por días de la semana y horario laboral configurable.\n\n**Defaults:** Lunes a viernes, 08:00-17:00.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a consultar", "example": [ 1234, 5678 ] }, "weekDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir (default: lunes a viernes)", "default": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] }, "startTime": { "type": "string", "description": "Hora de inicio del horario laboral (formato HH:mm, default: 08:00)", "default": "08:00", "example": "08:00" }, "endTime": { "type": "string", "description": "Hora de fin del horario laboral (formato HH:mm, default: 17:00)", "default": "17:00", "example": "17:00" } } } } } }, "responses": { "200": { "description": "Estadísticas de horas de trabajo obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado" }, "summary": { "nullable": true, "type": "object", "properties": { "totalTrips": { "type": "integer", "description": "Total de viajes en el periodo" }, "totalStops": { "type": "integer", "description": "Total de paradas dentro de viajes" }, "totalDrivingSeconds": { "type": "integer", "description": "Tiempo total de conducción en segundos (recortado al horario)" }, "totalStopSeconds": { "type": "integer", "description": "Tiempo total de paradas en segundos (recortado al horario)" }, "totalWorkingSeconds": { "type": "integer", "description": "Tiempo total de trabajo (conducción + paradas) en segundos" }, "daysWithActivity": { "type": "integer", "description": "Número de días con al menos un viaje" }, "avgDailyWorkingSeconds": { "type": "integer", "description": "Promedio diario de trabajo en segundos" } } } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/working-hours": { "post": { "summary": "Obtener desglose diario de horas de trabajo de un tracker", "tags": [ "Reportes - Horas de Trabajo" ], "security": [ { "bearerAuth": [] } ], "description": "Devuelve el desglose diario de horas de trabajo de un tracker: por cada día\nindica cantidad de viajes, paradas, tiempo de conducción, tiempo de paradas\ny tiempo total de trabajo dentro del horario laboral configurado.\n\n**Defaults:** Lunes a viernes, 08:00-17:00.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerId" ], "properties": { "trackerId": { "type": "integer", "description": "ID del tracker (flespiId)", "example": 7174525 }, "weekDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir (default: lunes a viernes)", "default": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] }, "startTime": { "type": "string", "description": "Hora de inicio del horario laboral (formato HH:mm, default: 08:00)", "default": "08:00", "example": "08:00" }, "endTime": { "type": "string", "description": "Hora de fin del horario laboral (formato HH:mm, default: 17:00)", "default": "17:00", "example": "17:00" } } } } } }, "responses": { "200": { "description": "Desglose diario obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker consultado" }, "summary": { "nullable": true, "type": "object", "properties": { "totalTrips": { "type": "integer", "description": "Total de viajes en el periodo" }, "totalStops": { "type": "integer", "description": "Total de paradas dentro de viajes" }, "totalDrivingSeconds": { "type": "integer", "description": "Tiempo total de conducción en segundos (recortado al horario)" }, "totalStopSeconds": { "type": "integer", "description": "Tiempo total de paradas en segundos (recortado al horario)" }, "totalWorkingSeconds": { "type": "integer", "description": "Tiempo total de trabajo (conducción + paradas) en segundos" }, "daysWithActivity": { "type": "integer", "description": "Número de días con al menos un viaje" }, "avgDailyWorkingSeconds": { "type": "integer", "description": "Promedio diario de trabajo en segundos" } } }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Fecha en formato DD/MM/YYYY", "example": "13/03/2026" }, "dayName": { "type": "string", "description": "Nombre del día de la semana", "example": "Viernes" }, "trips": { "type": "integer", "description": "Cantidad de viajes en el día" }, "stops": { "type": "integer", "description": "Cantidad de paradas en el día" }, "drivingSeconds": { "type": "integer", "description": "Segundos de conducción dentro del horario" }, "stopSeconds": { "type": "integer", "description": "Segundos de paradas dentro del horario" }, "workingSeconds": { "type": "integer", "description": "Total de segundos de trabajo (conducción + paradas)" } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/working-hours/export": { "post": { "summary": "Exportar resumen de horas de trabajo", "tags": [ "Reportes - Horas de Trabajo" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de horas de trabajo\n(estadísticas por asset) para los trackers indicados.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a exportar", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "weekDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir (default: lunes a viernes)", "default": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] }, "startTime": { "type": "string", "description": "Hora de inicio del horario laboral (default: 08:00)", "default": "08:00" }, "endTime": { "type": "string", "description": "Hora de fin del horario laboral (default: 17:00)", "default": "17:00" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/last-activity": { "post": { "summary": "Obtener reporte de última actividad de activos", "tags": [ "Reportes - Última Actividad" ], "security": [ { "bearerAuth": [] } ], "description": "Recibe un listado de IDs de activos (MongoDB ObjectIds) y un rango de fechas.\nRetorna el estado de comunicación de cada activo: última comunicación,\núltima posición reportada, dirección geocodificada y voltaje de batería.\n\nLos activos se clasifican como:\n- **Sin comunicación**: nunca han reportado datos.\n- **Fuera de rango**: su última comunicación fue antes de la fecha de inicio.\n- **Dentro de rango**: comunicaron dentro del periodo seleccionado.\n\n**Nota:** A diferencia de otros reportes, las fechas se envían en el body (no como query params).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "from", "to" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds) a consultar", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] }, "from": { "type": "string", "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "01/01/2025 08:30:00" }, "to": { "type": "string", "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "31/01/2025 17:45:00" } } } } } }, "responses": { "200": { "description": "Reporte de última actividad obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "description": "ID del activo (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "assetName": { "type": "string", "description": "Nombre del activo", "example": "Camión 01" }, "plate": { "type": "string", "description": "Patente del vehículo", "example": "ABCD-12" }, "lastCommunicationAt": { "type": "string", "nullable": true, "description": "Fecha de última comunicación en formato ISO 8601, o null si nunca comunicó", "example": "2025-12-17T10:30:00.000Z" }, "lastReportedPosition": { "nullable": true, "allOf": [ { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitud de la última posición reportada", "example": -33.4569 }, "lng": { "type": "number", "description": "Longitud de la última posición reportada", "example": -70.6483 } } } ], "description": "Última posición GPS reportada, o null si no hay posición" }, "lastReportedAddress": { "type": "string", "nullable": true, "description": "Dirección geocodificada de la última posición, o null", "example": "Av. Apoquindo 4700, Las Condes, Santiago" }, "batteryVolts": { "type": "number", "nullable": true, "description": "Voltaje de la batería del vehículo, o null si no está disponible", "example": 12.8 }, "isOutsideSelectedRange": { "type": "boolean", "description": "true si la última comunicación fue antes del rango seleccionado", "example": true }, "hasCommunication": { "type": "boolean", "description": "true si el activo ha comunicado al menos una vez", "example": false } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/last-activity/export": { "post": { "summary": "Exportar reporte de última actividad", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el reporte de última actividad\nde los activos seleccionados, mostrando solo los activos inactivos\n(sin comunicación o fuera de rango).\n\n**Nota:** A diferencia de otros reportes de exportación, las fechas se envían en el body (no como query params).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "from", "to", "format" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds) a incluir en el reporte", "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] }, "from": { "type": "string", "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "01/01/2025 08:30:00" }, "to": { "type": "string", "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss", "example": "31/01/2025 17:45:00" }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/tasks/export": { "post": { "summary": "Exportar reporte de tareas", "tags": [ "Reportes - Exportación" ], "description": "Genera un archivo Excel o PDF con el listado de tareas del rango\n(semántica de solapamiento del horario de la tarea con el rango).\n\n**Permisos requeridos:** `access_reports` + `access_tasks`\n\n**Nota:** Las fechas se envían en el body (no como query params).\n\n**Formato de fecha:** `DD/MM/YYYY HH:mm:ss`\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "format" ], "properties": { "from": { "type": "string", "example": "01/01/2025 08:00:00", "description": "Fecha de inicio (DD/MM/YYYY HH:mm:ss)" }, "to": { "type": "string", "example": "31/01/2025 17:45:00", "description": "Fecha de fin (DD/MM/YYYY HH:mm:ss)" }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "unassigned", "assigned", "done", "failed", "delayed", "arrived", "faulty" ] }, "description": "Estados de tarea a filtrar (opcional)" }, "employeeIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de empleados a filtrar (opcional)" }, "formLabels": { "type": "array", "items": { "type": "string" }, "description": "Nombres de formularios a filtrar (opcional)" }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato del archivo a generar" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/positions/export": { "post": { "summary": "Exportar resumen de posiciones", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de posiciones (estadísticas por asset)\npara los trackers indicados en el rango de fechas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a exportar", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "xlsx", "pdf" ], "description": "Formato del archivo exportado", "example": "xlsx" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/scheduled-reports": { "get": { "summary": "Obtener reportes programados", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene todos los reportes programados del cliente autenticado", "responses": { "200": { "description": "Lista de reportes programados", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID del reporte programado" }, "name": { "type": "string", "description": "Nombre del reporte" }, "clientId": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } }, "createdBy": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" } } }, "reportType": { "type": "string", "enum": [ "trips_history", "stops_history", "speed_excess" ] }, "assetIds": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" } } } }, "reportConfig": { "type": "object", "properties": { "speedLimit": { "type": "number" }, "minDuration": { "type": "number" }, "fuelNormRate": { "type": "number" }, "fuelPrice": { "type": "number" } } }, "includeSummary": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "daily: solo hora. weekly: requiere weekDays. monthly: requiere monthDays." }, "weekDays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Solo aplica si frequency es weekly (0=domingo, 6=sábado)" }, "monthDays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Solo aplica si frequency es monthly" }, "executionTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:30" }, "periodValue": { "type": "integer" }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana cuyos datos se incluyen en el reporte" }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "description": "Formatos de archivo. Si se envían múltiples, se genera un ZIP." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "isActive": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } }, "post": { "summary": "Crear reporte programado", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Crea un nuevo reporte programado. El tipo de reporte determina la validación aplicada:\n- trips_history: permite reportConfig con fuelNormRate y fuelPrice opcionales\n- stops_history: sin configuración adicional\n- speed_excess: requiere reportConfig.speedLimit obligatorio, minDuration opcional\n\n**Reglas de frecuencia:**\n- daily: solo executionTime. No enviar weekDays ni monthDays.\n- weekly: requiere weekDays (0=domingo a 6=sábado). No enviar monthDays.\n- monthly: requiere monthDays (1-31). No enviar weekDays.\n\n**controlDays:** array de días en inglés (monday, tuesday, etc.) que indica qué días incluir en los datos del reporte.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "reportType", "assetIds", "frequency", "executionTime", "periodValue", "periodUnit", "controlDays", "format", "recipients" ], "properties": { "name": { "type": "string", "description": "Nombre del reporte" }, "reportType": { "type": "string", "enum": [ "trips_history", "stops_history", "speed_excess" ], "description": "Tipo de reporte (inmutable post-creación)" }, "assetIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "ObjectIds de assets" }, "reportConfig": { "type": "object", "description": "Configuración específica según tipo de reporte", "properties": { "speedLimit": { "type": "number", "description": "Requerido para speed_excess" }, "minDuration": { "type": "number", "description": "Opcional para speed_excess (segundos)" }, "fuelNormRate": { "type": "number", "description": "Opcional para trips_history" }, "fuelPrice": { "type": "number", "description": "Opcional para trips_history" } } }, "includeSummary": { "type": "boolean", "default": false }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "daily: solo hora. weekly: requiere weekDays, no permite monthDays. monthly: requiere monthDays, no permite weekDays." }, "weekDays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Requerido si frequency es weekly (0=domingo, 6=sábado). No enviar con daily ni monthly." }, "monthDays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Requerido si frequency es monthly. No enviar con daily ni weekly." }, "executionTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:30", "description": "Hora de ejecución en formato HH:mm" }, "periodValue": { "type": "integer", "minimum": 1 }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "minItems": 1, "description": "Días cuyos datos se incluyen en el reporte" }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "minItems": 1, "description": "Formatos de archivo a generar (pdf o xlsx)." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1 }, "isActive": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Reporte programado creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID del reporte programado" }, "name": { "type": "string", "description": "Nombre del reporte" }, "clientId": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } }, "createdBy": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" } } }, "reportType": { "type": "string", "enum": [ "trips_history", "stops_history", "speed_excess" ] }, "assetIds": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" } } } }, "reportConfig": { "type": "object", "properties": { "speedLimit": { "type": "number" }, "minDuration": { "type": "number" }, "fuelNormRate": { "type": "number" }, "fuelPrice": { "type": "number" } } }, "includeSummary": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "daily: solo hora. weekly: requiere weekDays. monthly: requiere monthDays." }, "weekDays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Solo aplica si frequency es weekly (0=domingo, 6=sábado)" }, "monthDays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Solo aplica si frequency es monthly" }, "executionTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:30" }, "periodValue": { "type": "integer" }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana cuyos datos se incluyen en el reporte" }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "description": "Formatos de archivo. Si se envían múltiples, se genera un ZIP." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "isActive": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } } } } }, "/api/scheduled-reports/{id}": { "get": { "summary": "Obtener reporte programado por ID", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene un reporte programado específico del cliente autenticado", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" } ], "responses": { "200": { "description": "Reporte programado encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID del reporte programado" }, "name": { "type": "string", "description": "Nombre del reporte" }, "clientId": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } }, "createdBy": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" } } }, "reportType": { "type": "string", "enum": [ "trips_history", "stops_history", "speed_excess" ] }, "assetIds": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" } } } }, "reportConfig": { "type": "object", "properties": { "speedLimit": { "type": "number" }, "minDuration": { "type": "number" }, "fuelNormRate": { "type": "number" }, "fuelPrice": { "type": "number" } } }, "includeSummary": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "daily: solo hora. weekly: requiere weekDays. monthly: requiere monthDays." }, "weekDays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Solo aplica si frequency es weekly (0=domingo, 6=sábado)" }, "monthDays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Solo aplica si frequency es monthly" }, "executionTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:30" }, "periodValue": { "type": "integer" }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana cuyos datos se incluyen en el reporte" }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "description": "Formatos de archivo. Si se envían múltiples, se genera un ZIP." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "isActive": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Reporte programado no encontrado" } } }, "put": { "summary": "Actualizar reporte programado", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Actualiza un reporte programado existente. No se permite modificar el campo reportType.\nLa validación se aplica según el tipo de reporte existente en la base de datos.\n\n**Reglas de frecuencia:**\n- daily: solo executionTime. No enviar weekDays ni monthDays.\n- weekly: requiere weekDays (0=domingo a 6=sábado). No enviar monthDays.\n- monthly: requiere monthDays (1-31). No enviar weekDays.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Campos actualizables del reporte. No incluir reportType.", "properties": { "name": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "reportConfig": { "type": "object", "properties": { "speedLimit": { "type": "number" }, "minDuration": { "type": "number" }, "fuelNormRate": { "type": "number" }, "fuelPrice": { "type": "number" } } }, "includeSummary": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "weekDays": { "type": "array", "items": { "type": "integer" } }, "monthDays": { "type": "array", "items": { "type": "integer" } }, "executionTime": { "type": "string" }, "periodValue": { "type": "integer" }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "minItems": 1, "description": "Formatos de archivo a generar (pdf o xlsx)." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } } } } } } }, "responses": { "200": { "description": "Reporte programado actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID del reporte programado" }, "name": { "type": "string", "description": "Nombre del reporte" }, "clientId": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" } } }, "createdBy": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" } } }, "reportType": { "type": "string", "enum": [ "trips_history", "stops_history", "speed_excess" ] }, "assetIds": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "plate": { "type": "string" } } } }, "reportConfig": { "type": "object", "properties": { "speedLimit": { "type": "number" }, "minDuration": { "type": "number" }, "fuelNormRate": { "type": "number" }, "fuelPrice": { "type": "number" } } }, "includeSummary": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "daily: solo hora. weekly: requiere weekDays. monthly: requiere monthDays." }, "weekDays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Solo aplica si frequency es weekly (0=domingo, 6=sábado)" }, "monthDays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Solo aplica si frequency es monthly" }, "executionTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "example": "08:30" }, "periodValue": { "type": "integer" }, "periodUnit": { "type": "string", "enum": [ "hours", "days" ] }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana cuyos datos se incluyen en el reporte" }, "format": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx" ] }, "description": "Formatos de archivo. Si se envían múltiples, se genera un ZIP." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "isActive": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Reporte programado no encontrado" } } }, "delete": { "summary": "Eliminar reporte programado", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Elimina un reporte programado del cliente autenticado", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" } ], "responses": { "200": { "description": "Reporte programado eliminado correctamente" }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Reporte programado no encontrado" } } } }, "/api/scheduled-reports/{id}/state": { "patch": { "summary": "Actualizar estado de reporte programado", "tags": [ "Reportes - Reportes Programados" ], "security": [ { "bearerAuth": [] } ], "description": "Activa o desactiva un reporte programado (toggle isActive)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "isActive" ], "properties": { "isActive": { "type": "boolean", "description": "Nuevo estado del reporte programado" } } } } } }, "responses": { "200": { "description": "Estado actualizado correctamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Success" }, "isActive": { "type": "boolean" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Reporte programado no encontrado" } } } }, "/api/restrictions": { "get": { "summary": "Obtener todas las restricciones", "tags": [ "Clientes - Restricciones" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de restricciones", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "description": "Identificador en inglés" }, "label": { "type": "string", "description": "Etiqueta en español para UI" }, "description": { "type": "string" }, "blockedAccessPermissions": { "type": "array", "items": { "type": "string" } }, "blockedActionPermissions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label", "description" ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/restrictions/{id}": { "get": { "summary": "Obtener una restricción por ID", "tags": [ "Clientes - Restricciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Restricción encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "description": "Identificador en inglés" }, "label": { "type": "string", "description": "Etiqueta en español para UI" }, "description": { "type": "string" }, "blockedAccessPermissions": { "type": "array", "items": { "type": "string" } }, "blockedActionPermissions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "label", "description" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/device-health": { "get": { "summary": "Obtener reporte de salud de dispositivos del cliente", "description": "Obtiene un reporte unificado del estado de salud de los dispositivos del cliente autenticado.\n\n**Filtrado automático:** Solo retorna dispositivos del `clientId` del usuario autenticado.\n\nPermite filtrar por fechas, tipos de problema, severidad y hardware.\n", "tags": [ "Device Health" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de inicio del rango" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de fin del rango" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Tipos de issue a filtrar" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Severidades a filtrar" }, { "name": "hardware", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Modelos de hardware a filtrar" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Búsqueda por nombre de dispositivo" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Número de página" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Cantidad de resultados por página" } ], "responses": { "200": { "description": "Reporte de salud de dispositivos obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Reporte de salud con datos paginados y metadatos" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/device-health/hardware": { "get": { "summary": "Obtener modelos de hardware del cliente", "description": "Obtiene la lista de modelos de hardware únicos de los dispositivos del cliente autenticado.\n\n**Filtrado automático:** Solo retorna hardware del `clientId` del usuario autenticado.\n", "tags": [ "Device Health" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de modelos de hardware obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "Teltonika FMB920", "Queclink GV300" ] } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/device-health/{trackerId}": { "get": { "summary": "Obtener detalle de salud de un dispositivo del cliente", "description": "Obtiene el historial detallado de todos los intervalos de salud de un dispositivo específico.\n\n**Filtrado automático:** Solo retorna datos si el dispositivo pertenece al `clientId` del usuario autenticado.\n", "tags": [ "Device Health" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "trackerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del tracker" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de inicio del rango" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de fin del rango" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Tipos de issue a filtrar" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Número de página" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Cantidad de resultados por página" } ], "responses": { "200": { "description": "Detalle de salud del dispositivo obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Historial de intervalos de salud del dispositivo" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/activity-log": { "get": { "summary": "Listar eventos de actividad del cliente", "description": "Obtiene el registro de eventos de actividad del cliente autenticado.\n\n**Filtrado automático:** Solo retorna eventos del `clientId` del usuario autenticado.\n\n**Permisos requeridos:** `access_activity_log`\n", "tags": [ "Activity Log" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Número de página" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Cantidad de resultados por página" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de inicio del filtro" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Fecha de fin del filtro" } ], "responses": { "200": { "description": "Lista de eventos de actividad obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "description": "Evento de actividad" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/activity-log/{id}": { "get": { "summary": "Obtener detalle de un evento de actividad", "description": "Obtiene el detalle completo de un evento de actividad específico.\n\n**Filtrado automático:** Solo retorna el evento si pertenece al `clientId` del usuario autenticado.\n\n**Permisos requeridos:** `access_activity_log`\n", "tags": [ "Activity Log" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Evento de actividad encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Detalle completo del evento" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import/preview": { "post": { "summary": "Vista previa de importación de datos", "description": "Procesa un archivo Excel/CSV y muestra una vista previa de los datos antes de importar.\n\nValida formato, detecta errores y permite revisar datos antes del import definitivo.\n", "tags": [ "Work - Importaciones" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Archivo Excel/CSV (máximo 10MB)" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Vista previa generada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "previewId": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object" } }, "validRows": { "type": "integer" }, "invalidRows": { "type": "integer" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import/start": { "post": { "summary": "Iniciar importación de datos", "description": "Inicia el proceso de importación definitiva de los datos previamente validados.\n\nRequiere un `previewId` obtenido del endpoint `/import/preview`.\n", "tags": [ "Work - Importaciones" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewId": { "type": "string", "description": "ID de la vista previa generada" } }, "required": [ "previewId" ] } } } }, "responses": { "200": { "description": "Importación iniciada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "importId": { "type": "string" }, "status": { "type": "string", "example": "processing" }, "totalRows": { "type": "integer" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import/re-geocode": { "post": { "summary": "Re-geocodificar direcciones de importación", "description": "Vuelve a geocodificar direcciones que fallaron en el proceso inicial de importación.\n", "tags": [ "Work - Importaciones" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "importId": { "type": "string" }, "rowIds": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Re-geocodificación iniciada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import/history": { "get": { "summary": "Historial de importaciones", "description": "Obtiene el historial de todas las importaciones realizadas por el cliente.\n\n**Filtrado automático:** Solo retorna importaciones del `clientId` del usuario autenticado.\n", "tags": [ "Work - Importaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Historial obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "imports": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import/history/{id}": { "get": { "summary": "Detalle de importación", "description": "Obtiene el detalle completo de una importación específica, incluyendo resultados y errores.\n", "tags": [ "Work - Importaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Detalle de importación obtenido", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import-templates": { "get": { "summary": "Listar plantillas de importación", "description": "Obtiene las plantillas de importación configuradas para el cliente.\n", "tags": [ "Work - Plantillas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Plantillas obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear plantilla de importación", "description": "Crea una nueva plantilla de importación personalizada.\n", "tags": [ "Work - Plantillas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" } } } } } }, "responses": { "201": { "description": "Plantilla creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/import-templates/{id}": { "put": { "summary": "Actualizar plantilla de importación", "description": "Actualiza una plantilla de importación existente.\n", "tags": [ "Work - Plantillas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Plantilla actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar plantilla de importación", "description": "Elimina una plantilla de importación.\n", "tags": [ "Work - Plantillas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Plantilla eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/stats": { "get": { "summary": "Resumen agregado de Terreno", "description": "KPIs y agregados del dominio work para el tab Resumen: tareas por estado, sitio y\ndía, permanencia promedio, formularios enviados y check-ins por día y franja\nhoraria. Agrega server-side sobre Navixy para no bajar miles de tareas a la web.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Resumen" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "21/07/2026 00:00:00" }, "description": "Inicio del rango (DD/MM/YYYY HH:mm:ss, America/Santiago)" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "27/07/2026 23:59:59" }, "description": "Fin del rango (DD/MM/YYYY HH:mm:ss, America/Santiago)" } ], "responses": { "200": { "description": "Resumen agregado del rango", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "tasks": { "type": "object", "properties": { "total": { "type": "number" }, "byStatus": { "type": "object", "additionalProperties": { "type": "number" } }, "byDay": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-07-21" }, "byStatus": { "type": "object", "additionalProperties": { "type": "number" } } } } }, "avgStaySeconds": { "type": "number", "nullable": true }, "closedWithForm": { "type": "number" }, "formSubmitted": { "type": "number" }, "heatmap": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string", "example": "tuesday" }, "hour": { "type": "number" }, "count": { "type": "number" } } } } } }, "sites": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" } } } }, "employees": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" } } } }, "forms": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" }, "done": { "type": "number" }, "failed": { "type": "number" } } } }, "checkins": { "type": "object", "properties": { "total": { "type": "number" }, "byDay": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "number" } } } }, "heatmap": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string", "example": "tuesday" }, "hour": { "type": "number" }, "count": { "type": "number" } } } }, "withForm": { "type": "number" }, "byEmployee": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" } } } }, "byForm": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" } } } }, "byAddress": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "total": { "type": "number" } } } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/transportistas": { "get": { "summary": "Listar transportistas", "description": "Obtiene la lista de transportistas del cliente.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Transportistas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de transportistas obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear transportista", "description": "Crea un nuevo transportista.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Transportistas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nombre": { "type": "string" }, "rut": { "type": "string" }, "contacto": { "type": "object" } } } } } }, "responses": { "201": { "description": "Transportista creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/transportistas/{id}": { "get": { "summary": "Obtener transportista por ID", "tags": [ "Cargo - Transportistas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Transportista encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar transportista", "tags": [ "Cargo - Transportistas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Transportista actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar transportista", "tags": [ "Cargo - Transportistas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Transportista eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/pedidos": { "get": { "summary": "Listar pedidos", "description": "Obtiene la lista de pedidos de carga.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de pedidos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear pedido", "tags": [ "Cargo - Pedidos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Pedido creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/monitoreo": { "get": { "summary": "Monitoreo en vivo de carga", "description": "Obtiene el estado en tiempo real de pedidos, activos y transportistas.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Monitoreo" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Estado de monitoreo obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Estado en tiempo real del sistema de carga" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/navixy/{userId}": { "get": { "summary": "Obtener hashes de integración Navixy", "description": "Obtiene los hashes de autenticación para la integración con la plataforma Navixy.\n\nPermite generar URLs de autenticación para redirigir usuarios a Navixy.\n", "tags": [ "Integraciones - Navixy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del usuario" } ], "responses": { "200": { "description": "Hashes obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Hashes de integración Navixy" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/user-tracker-access/users/{userId}/trackers": { "get": { "tags": [ "User Tracker Access" ], "summary": "Obtener trackers asignados a un usuario", "description": "Retorna los trackers asignados a un usuario específico con audit trail.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del usuario" } ], "responses": { "200": { "description": "Configuración de acceso del usuario", "content": { "application/json": { "schema": { "type": "object", "properties": { "trackers": { "type": "array", "items": { "type": "object", "properties": { "trackerId": { "type": "string" }, "flespiId": { "type": "number" } } } }, "isActive": { "type": "boolean" }, "assignedBy": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "action": { "type": "string", "enum": [ "assigned", "modified", "removed" ] }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "403": { "description": "Sin permisos" }, "404": { "description": "Usuario no encontrado" } } }, "post": { "tags": [ "User Tracker Access" ], "summary": "Asignar trackers a un usuario", "description": "Reemplaza los trackers asignados al usuario con los nuevos trackers especificados.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del usuario" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackers" ], "properties": { "trackers": { "type": "array", "items": { "type": "object", "required": [ "trackerId", "flespiId" ], "properties": { "trackerId": { "type": "string", "description": "ObjectId del tracker" }, "flespiId": { "type": "number", "description": "ID de Flespi del tracker" } } } } } } } } }, "responses": { "201": { "description": "Trackers asignados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "count": { "type": "number" } } } } } }, "400": { "description": "Datos de entrada inválidos" }, "404": { "description": "Usuario no encontrado" } } }, "delete": { "tags": [ "User Tracker Access" ], "summary": "Eliminar trackers asignados a un usuario", "description": "Vacía el array de trackers, otorgando acceso completo al usuario.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del usuario" } ], "responses": { "200": { "description": "Trackers eliminados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Usuario no encontrado" } } }, "patch": { "tags": [ "User Tracker Access" ], "summary": "Toggle restricciones de acceso", "description": "Activa o desactiva las restricciones de acceso del usuario.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del usuario" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "isActive" ], "properties": { "isActive": { "type": "boolean", "description": "true para activar restricciones, false para desactivarlas" } } } } } }, "responses": { "200": { "description": "Estado de restricciones actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "isActive": { "type": "boolean" } } } } } }, "404": { "description": "Usuario o configuración no encontrada" } } } }, "/api/user-tracker-access/client-assets": { "get": { "tags": [ "User Tracker Access" ], "summary": "Obtener todos los assets del cliente", "description": "Retorna todos los assets del cliente sin filtro de asignaciones. Usado por el panel de administración.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de todos los assets del cliente", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "403": { "description": "Sin permisos" } } } }, "/api/maintenance/dashboard/overview": { "get": { "summary": "Resumen del dashboard de mantenimiento", "description": "Obtiene métricas generales del estado de mantenimiento de la flota.\n\n**Permisos requeridos:** `access_maintenance`\n", "tags": [ "Mantenimiento - Dashboard" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Resumen obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Métricas del dashboard" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/service-providers": { "get": { "summary": "Listar proveedores de servicio", "tags": [ "Mantenimiento - Proveedores" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de proveedores obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear proveedor de servicio", "tags": [ "Mantenimiento - Proveedores" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Proveedor creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/service-providers/{id}": { "get": { "summary": "Obtener proveedor por ID", "tags": [ "Mantenimiento - Proveedores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Proveedor encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar proveedor", "tags": [ "Mantenimiento - Proveedores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Proveedor actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar proveedor", "tags": [ "Mantenimiento - Proveedores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Proveedor eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/status/overview": { "get": { "summary": "Resumen de estado de mantenimiento de activos", "description": "Obtiene el estado de mantenimiento de todos los activos con datos enriquecidos.\n", "tags": [ "Mantenimiento - Estado" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Estado obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/profiles": { "get": { "summary": "Listar perfiles de mantenimiento", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de perfiles obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear perfil de mantenimiento", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Perfil creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/profiles/asset/{assetId}": { "get": { "summary": "Obtener perfil de mantenimiento por activo", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del activo" } ], "responses": { "200": { "description": "Perfil encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/profiles/{id}": { "get": { "summary": "Obtener perfil por ID", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Perfil encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar perfil", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Perfil actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/profiles/{id}/change-status": { "post": { "summary": "Cambiar estado operacional del perfil", "tags": [ "Mantenimiento - Perfiles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Estado cambiado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/faults": { "get": { "summary": "Listar fallas activas", "tags": [ "Mantenimiento - Fallas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de fallas obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear falla activa", "tags": [ "Mantenimiento - Fallas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Falla creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/faults/{id}": { "get": { "summary": "Obtener falla por ID", "tags": [ "Mantenimiento - Fallas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Falla encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar falla", "tags": [ "Mantenimiento - Fallas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Falla actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/faults/{id}/resolve": { "post": { "summary": "Resolver falla activa", "tags": [ "Mantenimiento - Fallas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Falla resuelta exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/dvir-reports": { "get": { "summary": "Listar reportes DVIR", "description": "Driver Vehicle Inspection Report - Reportes de inspección pre-viaje.\n", "tags": [ "Mantenimiento - DVIR" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de reportes obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear reporte DVIR", "tags": [ "Mantenimiento - DVIR" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Reporte creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/dvir-reports/{id}": { "get": { "summary": "Obtener reporte DVIR por ID", "tags": [ "Mantenimiento - DVIR" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Reporte encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar reporte DVIR", "tags": [ "Mantenimiento - DVIR" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Reporte actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/defects": { "get": { "summary": "Listar defectos", "tags": [ "Mantenimiento - Defectos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de defectos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear defecto", "tags": [ "Mantenimiento - Defectos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Defecto creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/defects/{id}": { "get": { "summary": "Obtener defecto por ID", "tags": [ "Mantenimiento - Defectos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Defecto encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar defecto", "tags": [ "Mantenimiento - Defectos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Defecto actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/schedules": { "get": { "summary": "Listar programaciones de mantenimiento", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de programaciones obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear programación de mantenimiento", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Programación creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/schedules/{id}": { "get": { "summary": "Obtener programación por ID", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Programación encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar programación", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Programación actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar programación", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Programación eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/schedules/{id}/assets": { "post": { "summary": "Asignar activo a programación", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Activo asignado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Reemplazar activos de programación", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Activos reemplazados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/schedules/{id}/assets/{assetId}": { "delete": { "summary": "Desasignar activo de programación", "tags": [ "Mantenimiento - Programaciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la programación" }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del activo" } ], "responses": { "200": { "description": "Activo desasignado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/upcoming-items": { "get": { "summary": "Listar ítems de mantenimiento próximos", "tags": [ "Mantenimiento - Próximos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/upcoming-items/{id}": { "get": { "summary": "Obtener ítem próximo por ID", "tags": [ "Mantenimiento - Próximos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Ítem encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/upcoming-items/{id}/snooze": { "post": { "summary": "Posponer ítem de mantenimiento", "tags": [ "Mantenimiento - Próximos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Ítem pospuesto exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/upcoming-items/{id}/ignore": { "post": { "summary": "Ignorar ítem de mantenimiento", "tags": [ "Mantenimiento - Próximos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Ítem ignorado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/upcoming-items/{id}/resolve": { "post": { "summary": "Resolver ítem de mantenimiento", "tags": [ "Mantenimiento - Próximos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Ítem resuelto exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders": { "get": { "summary": "Listar órdenes de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de órdenes obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Orden creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/categories": { "get": { "summary": "Listar categorías de órdenes de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Categorías obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}": { "get": { "summary": "Obtener orden de trabajo por ID", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Orden encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Orden actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Orden eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/items": { "get": { "summary": "Listar ítems de orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Ítems obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Agregar ítem a orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Ítem agregado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/items/{itemId}": { "delete": { "summary": "Eliminar ítem de orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del ítem" } ], "responses": { "200": { "description": "Ítem eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/forms": { "get": { "summary": "Listar formularios de orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Formularios obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Agregar formulario a orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Formulario agregado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/forms/{formId}": { "delete": { "summary": "Eliminar formulario de orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden" }, { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del formulario" } ], "responses": { "200": { "description": "Formulario eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/complete": { "post": { "summary": "Completar orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Orden completada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/close": { "post": { "summary": "Cerrar orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Orden cerrada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/cancel": { "post": { "summary": "Cancelar orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Orden cancelada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{id}/comments": { "get": { "summary": "Listar comentarios de orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Comentarios obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Agregar comentario a orden de trabajo", "tags": [ "Mantenimiento - Órdenes de Trabajo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Comentario agregado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/service-logs": { "get": { "summary": "Listar registros de servicio", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de registros obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear registro de servicio", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Registro creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/service-logs/{id}": { "get": { "summary": "Obtener registro de servicio por ID", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Registro encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar registro de servicio", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Registro actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/service-logs/{id}/attachments": { "get": { "summary": "Listar adjuntos de registro de servicio", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Adjuntos obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Agregar adjunto a registro de servicio", "tags": [ "Mantenimiento - Registros de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Adjunto agregado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/issues": { "get": { "summary": "Listar problemas de mantenimiento", "tags": [ "Mantenimiento - Problemas" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de problemas obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear problema de mantenimiento", "tags": [ "Mantenimiento - Problemas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Problema creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/issues/{id}": { "get": { "summary": "Obtener problema por ID", "tags": [ "Mantenimiento - Problemas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Problema encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar problema", "tags": [ "Mantenimiento - Problemas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Problema actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{workOrderId}/service-tasks": { "get": { "summary": "Listar tareas de servicio de orden de trabajo", "tags": [ "Mantenimiento - Tareas de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workOrderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden de trabajo" } ], "responses": { "200": { "description": "Lista de tareas obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear tarea de servicio", "tags": [ "Mantenimiento - Tareas de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workOrderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden de trabajo" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Tarea creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/work-orders/{workOrderId}/service-tasks/{id}": { "get": { "summary": "Obtener tarea de servicio por ID", "tags": [ "Mantenimiento - Tareas de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workOrderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden de trabajo" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tarea encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar tarea de servicio", "tags": [ "Mantenimiento - Tareas de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workOrderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden de trabajo" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Tarea actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar tarea de servicio", "tags": [ "Mantenimiento - Tareas de Servicio" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workOrderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la orden de trabajo" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Tarea eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/parts": { "get": { "summary": "Listar catálogo de partes", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Catálogo obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear parte en catálogo", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Parte creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/parts/{id}": { "put": { "summary": "Actualizar parte del catálogo", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Parte actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar parte del catálogo", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Parte eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/inventory-locations": { "get": { "summary": "Listar ubicaciones de inventario", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Ubicaciones obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear ubicación de inventario", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Ubicación creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/inventory-locations/{id}": { "put": { "summary": "Actualizar ubicación de inventario", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Ubicación actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/inventory-stock": { "get": { "summary": "Listar stock de inventario", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stock obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/inventory-stock/{id}": { "put": { "summary": "Actualizar stock de inventario", "tags": [ "Mantenimiento - Inventario" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Stock actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/cost-entries": { "get": { "summary": "Listar entradas de costos", "tags": [ "Mantenimiento - Costos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Entradas obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear entrada de costo", "tags": [ "Mantenimiento - Costos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Entrada creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/cost-entries/summary": { "get": { "summary": "Obtener resumen de costos", "tags": [ "Mantenimiento - Costos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Resumen obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Resumen de costos agregados" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/invoice-import": { "post": { "summary": "Iniciar importación de factura con IA", "description": "Sube una factura PDF y extrae datos usando IA (Azure Document Intelligence).\n", "tags": [ "Mantenimiento - Importación de Facturas" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Archivo PDF de factura" } } } } } }, "responses": { "200": { "description": "Importación iniciada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "importId": { "type": "string" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/invoice-import/{id}/status": { "get": { "summary": "Obtener estado de importación de factura", "tags": [ "Mantenimiento - Importación de Facturas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Estado obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Estado del proceso de importación" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/maintenance/invoice-import/{id}/apply": { "post": { "summary": "Aplicar datos de factura a orden de trabajo", "tags": [ "Mantenimiento - Importación de Facturas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Datos aplicados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips": { "get": { "summary": "Obtener viajes de varios activos (historial multi-activo)", "description": "Obtiene los viajes de los assets seleccionados en un rango de fechas, agrupados por\ntracker y con las posiciones completas de cada viaje (a diferencia de `/api/trips/stats`,\nque las trunca). Respeta el scope de assets autorizado para el usuario.\n\nMáximo 30 assets por request y rango máximo de 30 días.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "assetIds", "required": true, "schema": { "type": "string" }, "description": "Lista CSV de ids de assets (máximo 30). Solo se consideran los assets dentro del scope autorizado.", "example": "665f1c2ab8d4e21f30a11111,665f1c2ab8d4e21f30a22222" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Viajes agrupados por tracker obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "assetsTrips": { "type": "array", "description": "Un elemento por tracker (mainTrackerId del asset), incluso sin viajes en el rango", "items": { "type": "object", "properties": { "trackerId": { "type": "number", "description": "ID del mainTracker (mainTrackerId del asset)", "example": 7174578 }, "icon": { "type": "object", "nullable": true, "description": "Ícono del asset (id y color) para la UI" }, "trips": { "type": "array", "items": { "type": "object", "properties": { "avg_speed": { "type": "number", "description": "km/h" }, "begin": { "type": "number", "description": "Unix timestamp (segundos)" }, "distance": { "type": "number", "description": "metros" }, "duration": { "type": "number", "description": "segundos" }, "end": { "type": "number", "description": "Unix timestamp (segundos)" }, "end_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Identidad del viaje. Los viajes del engine de interval (la fuente activa) exponen el `_id` de Mongo como string; los viajes legacy de Flespi exponen su id numérico." }, "max_speed": { "type": "number", "description": "km/h" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "alt": { "type": "number", "description": "metros" }, "dir": { "type": "number", "description": "grados (0-359)" }, "lat": { "type": "number", "description": "grados decimales" }, "lng": { "type": "number", "description": "grados decimales" }, "speed": { "type": "number", "description": "km/h" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" } } } }, "route": { "type": "string" }, "start_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" }, "type": { "type": "string" }, "clientId": { "type": "string" }, "assetId": { "type": "string", "nullable": true, "description": "null para trips de trackers sin Asset linkeado" } }, "required": [ "avg_speed", "begin", "distance", "duration", "end", "end_battery_level", "id", "max_speed", "positions", "route", "start_battery_level", "timestamp", "type", "clientId" ] } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/stops/stats": { "get": { "summary": "Obtener estadísticas de paradas entre viajes para todos los mainTrackers de los assets", "description": "Obtiene estadísticas de paradas entre viajes para todos los mainTrackers de los assets del cliente autenticado en un rango de fechas.\nRetorna estadísticas individuales por cada tracker.\nIncluye todos los trackers aunque no tengan paradas (stats: null).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Estadísticas de paradas obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "stopsStats": { "type": "array", "description": "Array de estadísticas de paradas por cada tracker (mainTrackerId)", "items": { "type": "object", "properties": { "trackerId": { "type": "number", "description": "ID del mainTracker (mainTrackerId del Asset)", "example": 7174578 }, "stats": { "type": "object", "nullable": true, "description": "Estadísticas de paradas del tracker. null si no tiene paradas válidas en el rango de fechas", "properties": { "totalStops": { "type": "number", "description": "Total de paradas entre viajes", "example": 25 }, "totalStoppedTime": { "type": "number", "description": "Tiempo total detenido en segundos", "example": 7200.5 }, "averageStopTime": { "type": "number", "description": "Tiempo promedio por parada en segundos", "example": 288.02 } } } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/stats": { "get": { "summary": "Obtener estadísticas de viajes para todos los mainTrackers de los assets", "description": "Obtiene estadísticas de viajes para todos los mainTrackers de los assets del cliente autenticado en un rango de fechas.\nRetorna estadísticas individuales por cada tracker.\nIncluye todos los trackers aunque no tengan viajes (stats: null).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Estadísticas de viajes obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "tripsStats": { "type": "array", "description": "Array de estadísticas por cada tracker (mainTrackerId)", "items": { "type": "object", "properties": { "trackerId": { "type": "number", "description": "ID del mainTracker (mainTrackerId del Asset)", "example": 7174578 }, "stats": { "nullable": true, "description": "Estadísticas del tracker. null si no tiene viajes válidos en el rango de fechas", "type": "object", "properties": { "totalTrips": { "type": "integer" }, "totalDistance": { "type": "number", "description": "metros" }, "totalDuration": { "type": "number", "description": "segundos" }, "averageSpeed": { "type": "number", "description": "km/h" }, "maxSpeed": { "type": "number", "description": "km/h" }, "minSpeed": { "type": "number", "description": "km/h" }, "averageDistancePerTrip": { "type": "number", "description": "metros" }, "averageDurationPerTrip": { "type": "number", "description": "segundos" }, "averageStartBatteryLevel": { "type": "number" }, "averageEndBatteryLevel": { "type": "number" }, "lowBatteryTrips": { "type": "integer", "description": "batería < 20%" }, "totalDrivingTime": { "type": "number", "description": "segundos" }, "totalStopsTime": { "type": "number", "description": "segundos" }, "totalStops": { "type": "integer", "description": "Cantidad de paradas DENTRO de viaje (stopKind within_trip) del tracker en el rango. No incluye parqueos entre viajes (stopKind between_trips, incluidos los que siguen en curso) — ver totalStops de /api/trips/stops/stats, que es esa otra clase de parada. Mismo nombre de campo, tipo de dato opuesto." } }, "required": [ "totalTrips", "totalDistance", "totalDuration", "averageSpeed", "maxSpeed", "minSpeed", "averageDistancePerTrip", "averageDurationPerTrip", "averageStartBatteryLevel", "averageEndBatteryLevel", "lowBatteryTrips", "totalDrivingTime", "totalStopsTime", "totalStops" ] } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}": { "get": { "summary": "Obtener viajes por Flespi ID", "description": "Obtiene los viajes de un dispositivo específico. Si se proporcionan parámetros de fecha, filtra los viajes por el rango especificado.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n\n**Nota:** Si no se proporciona hora en el parámetro `to`, automáticamente se ajusta a las 23:59:59 del día.\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo solo fecha: `01/01/2025`, con hora: `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo solo fecha: `31/01/2025`, con hora: `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Lista de viajes obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "avg_speed": { "type": "number", "description": "km/h" }, "begin": { "type": "number", "description": "Unix timestamp (segundos)" }, "distance": { "type": "number", "description": "metros" }, "duration": { "type": "number", "description": "segundos" }, "end": { "type": "number", "description": "Unix timestamp (segundos)" }, "end_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Identidad del viaje. Los viajes del engine de interval (la fuente activa) exponen el `_id` de Mongo como string; los viajes legacy de Flespi exponen su id numérico." }, "max_speed": { "type": "number", "description": "km/h" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "alt": { "type": "number", "description": "metros" }, "dir": { "type": "number", "description": "grados (0-359)" }, "lat": { "type": "number", "description": "grados decimales" }, "lng": { "type": "number", "description": "grados decimales" }, "speed": { "type": "number", "description": "km/h" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" } } } }, "route": { "type": "string" }, "start_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" }, "type": { "type": "string" }, "clientId": { "type": "string" }, "assetId": { "type": "string", "nullable": true, "description": "null para trips de trackers sin Asset linkeado" } }, "required": [ "avg_speed", "begin", "distance", "duration", "end", "end_battery_level", "id", "max_speed", "positions", "route", "start_battery_level", "timestamp", "type", "clientId" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/trip/{tripId}": { "get": { "summary": "Obtener un viaje específico por ID", "description": "Obtiene un viaje específico de un dispositivo por su ID único. El sistema transforma automáticamente el viaje agregando información de cliente y activo, además de obtener las direcciones de inicio y fin mediante geocoding.", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "name": "tripId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del viaje" } ], "responses": { "200": { "description": "Viaje específico obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "avg_speed": { "type": "number", "description": "km/h" }, "begin": { "type": "number", "description": "Unix timestamp (segundos)" }, "distance": { "type": "number", "description": "metros" }, "duration": { "type": "number", "description": "segundos" }, "end": { "type": "number", "description": "Unix timestamp (segundos)" }, "end_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Identidad del viaje. Los viajes del engine de interval (la fuente activa) exponen el `_id` de Mongo como string; los viajes legacy de Flespi exponen su id numérico." }, "max_speed": { "type": "number", "description": "km/h" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "alt": { "type": "number", "description": "metros" }, "dir": { "type": "number", "description": "grados (0-359)" }, "lat": { "type": "number", "description": "grados decimales" }, "lng": { "type": "number", "description": "grados decimales" }, "speed": { "type": "number", "description": "km/h" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" } } } }, "route": { "type": "string" }, "start_battery_level": { "type": "number", "description": "porcentaje (0-100)" }, "timestamp": { "type": "number", "description": "Unix timestamp (segundos)" }, "type": { "type": "string" }, "clientId": { "type": "string" }, "assetId": { "type": "string", "nullable": true, "description": "null para trips de trackers sin Asset linkeado" } }, "required": [ "avg_speed", "begin", "distance", "duration", "end", "end_battery_level", "id", "max_speed", "positions", "route", "start_battery_level", "timestamp", "type", "clientId" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/stats": { "get": { "summary": "Obtener estadísticas de viajes por Flespi ID", "description": "Obtiene estadísticas agregadas de los viajes de un dispositivo específico en un rango de fechas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Estadísticas de viajes obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Mensaje descriptivo de la respuesta" }, "dateRange": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Fecha de inicio en formato ISO" }, "to": { "type": "string", "format": "date-time", "description": "Fecha de fin en formato ISO" } } }, "stats": { "type": "object", "properties": { "totalTrips": { "type": "integer" }, "totalDistance": { "type": "number", "description": "metros" }, "totalDuration": { "type": "number", "description": "segundos" }, "averageSpeed": { "type": "number", "description": "km/h" }, "maxSpeed": { "type": "number", "description": "km/h" }, "minSpeed": { "type": "number", "description": "km/h" }, "averageDistancePerTrip": { "type": "number", "description": "metros" }, "averageDurationPerTrip": { "type": "number", "description": "segundos" }, "averageStartBatteryLevel": { "type": "number" }, "averageEndBatteryLevel": { "type": "number" }, "lowBatteryTrips": { "type": "integer", "description": "batería < 20%" }, "totalDrivingTime": { "type": "number", "description": "segundos" }, "totalStopsTime": { "type": "number", "description": "segundos" }, "totalStops": { "type": "integer", "description": "Cantidad de paradas DENTRO de viaje (stopKind within_trip) del tracker en el rango. No incluye parqueos entre viajes (stopKind between_trips, incluidos los que siguen en curso) — ver totalStops de /api/trips/stops/stats, que es esa otra clase de parada. Mismo nombre de campo, tipo de dato opuesto." } }, "required": [ "totalTrips", "totalDistance", "totalDuration", "averageSpeed", "maxSpeed", "minSpeed", "averageDistancePerTrip", "averageDurationPerTrip", "averageStartBatteryLevel", "averageEndBatteryLevel", "lowBatteryTrips", "totalDrivingTime", "totalStopsTime", "totalStops" ] } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/trip/{tripId}/stops-trips": { "get": { "summary": "Obtener paradas dentro de un viaje específico", "description": "Obtiene todas las paradas que ocurrieron dentro de un viaje específico de un dispositivo. Utiliza el calculador de paradas de Flespi para obtener los intervalos de parada filtrados por el ID del viaje.", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "name": "tripId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del viaje" } ], "responses": { "200": { "description": "Lista de paradas dentro del viaje obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "begin": { "type": "integer", "description": "Unix timestamp (segundos)" }, "end": { "type": "integer", "description": "Unix timestamp (segundos)" }, "duration": { "type": "integer", "description": "segundos" }, "lat": { "type": "number", "description": "grados decimales" }, "lng": { "type": "number", "description": "grados decimales" }, "timestamp": { "type": "integer", "description": "Unix timestamp (segundos)" }, "type": { "type": "string" }, "trip_id": { "type": "integer" }, "stop_duration": { "type": "integer", "description": "segundos" }, "trip": { "type": "object", "properties": { "id": { "type": "integer" }, "begin": { "type": "integer" }, "end": { "type": "integer" } } }, "address": { "type": "string", "nullable": true, "description": "Cacheada en Redis", "example": "Av. Principal 123, Lima, Perú" } }, "required": [ "id", "begin", "end", "duration", "lat", "lng", "timestamp", "type" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/stops": { "get": { "summary": "Obtener paradas entre viajes de un dispositivo", "description": "Obtiene todas las paradas entre viajes de un dispositivo específico. Las paradas entre viajes son intervalos de tiempo en los que el vehículo está detenido entre dos viajes consecutivos. Si se proporcionan parámetros de fecha, filtra las paradas por el rango especificado.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Lista de paradas entre viajes del dispositivo obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "active": { "type": "boolean" }, "begin": { "type": "integer", "description": "Unix timestamp (segundos)" }, "device_id": { "type": "integer" }, "duration": { "type": "integer", "description": "segundos" }, "end": { "type": "integer", "description": "Unix timestamp (segundos)" }, "id": { "type": "integer" }, "ident": { "type": "string" }, "parking_duration": { "type": "integer", "description": "segundos" }, "start": { "type": "object", "properties": { "position.latitude": { "type": "number", "format": "double" }, "position.longitude": { "type": "number", "format": "double" } }, "required": [ "position.latitude", "position.longitude" ] }, "timestamp": { "type": "number", "format": "double", "description": "Unix timestamp (segundos)" }, "type": { "type": "string", "example": "stops_between_trips" }, "address": { "type": "string", "nullable": true, "description": "Cacheada en Redis", "example": "Av. Principal 123, Lima, Perú" } }, "required": [ "active", "begin", "device_id", "duration", "end", "id", "ident", "parking_duration", "start", "timestamp", "type" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/stops/{stopId}": { "get": { "summary": "Obtener una parada entre viajes específica por ID", "description": "Obtiene una parada entre viajes específica de un dispositivo por su ID único. El sistema obtiene automáticamente la dirección de la parada mediante geocoding.\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "name": "stopId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID de la parada" } ], "responses": { "200": { "description": "Parada entre viajes obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "active": { "type": "boolean" }, "begin": { "type": "integer", "description": "Unix timestamp (segundos)" }, "device_id": { "type": "integer" }, "duration": { "type": "integer", "description": "segundos" }, "end": { "type": "integer", "description": "Unix timestamp (segundos)" }, "id": { "type": "integer" }, "ident": { "type": "string" }, "parking_duration": { "type": "integer", "description": "segundos" }, "start": { "type": "object", "properties": { "position.latitude": { "type": "number", "format": "double" }, "position.longitude": { "type": "number", "format": "double" } }, "required": [ "position.latitude", "position.longitude" ] }, "timestamp": { "type": "number", "format": "double", "description": "Unix timestamp (segundos)" }, "type": { "type": "string", "example": "stops_between_trips" }, "address": { "type": "string", "nullable": true, "description": "Cacheada en Redis", "example": "Av. Principal 123, Lima, Perú" } }, "required": [ "active", "begin", "device_id", "duration", "end", "id", "ident", "parking_duration", "start", "timestamp", "type" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/stops-in-trips": { "get": { "summary": "Obtener todas las paradas dentro de viajes de un dispositivo", "description": "Obtiene todas las paradas que ocurrieron dentro de viajes de un dispositivo específico. Si se proporcionan parámetros de fecha, filtra las paradas por el rango especificado.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Lista de paradas del dispositivo obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "begin": { "type": "integer", "description": "Unix timestamp (segundos)" }, "end": { "type": "integer", "description": "Unix timestamp (segundos)" }, "duration": { "type": "integer", "description": "segundos" }, "lat": { "type": "number", "description": "grados decimales" }, "lng": { "type": "number", "description": "grados decimales" }, "timestamp": { "type": "integer", "description": "Unix timestamp (segundos)" }, "type": { "type": "string" }, "trip_id": { "type": "integer" }, "stop_duration": { "type": "integer", "description": "segundos" }, "trip": { "type": "object", "properties": { "id": { "type": "integer" }, "begin": { "type": "integer" }, "end": { "type": "integer" } } }, "address": { "type": "string", "nullable": true, "description": "Cacheada en Redis", "example": "Av. Principal 123, Lima, Perú" } }, "required": [ "id", "begin", "end", "duration", "lat", "lng", "timestamp", "type" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/timeline": { "get": { "summary": "Obtener línea de tiempo combinada de trips, stops y stops entre trips", "description": "Obtiene una línea de tiempo cronológica que combina trips, stops dentro de trips y stops entre trips de un dispositivo específico. \nTodos los eventos están ordenados cronológicamente por su timestamp de inicio (begin).\n\n**Tipos de eventos en la línea de tiempo:**\n- `trip`: Viaje del dispositivo\n- `stop_in_trip`: Parada dentro de un viaje\n- `stop_between_trips`: Parada entre viajes\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Línea de tiempo obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "trip", "stop_in_trip", "stop_between_trips" ], "description": "Tipo de evento en la línea de tiempo" }, "begin": { "type": "integer", "description": "Timestamp de inicio del evento" }, "end": { "type": "integer", "description": "Timestamp de fin del evento" }, "timestamp": { "type": "integer", "description": "Timestamp del evento" }, "tripId": { "type": "integer", "description": "ID del viaje asociado (solo para stop_in_trip)", "example": 12345 }, "data": { "type": "object", "description": "Datos completos del evento (trip, stop_in_trip o stop_between_trips)", "properties": { "id": { "type": "integer", "description": "ID del viaje o parada" }, "distance": { "type": "number", "description": "Distancia recorrida en metros (solo para trip)" }, "duration": { "type": "integer", "description": "Duración en segundos" }, "avg_speed": { "type": "number", "description": "Velocidad promedio en km/h (solo para trip)" }, "max_speed": { "type": "number", "description": "Velocidad máxima en km/h (solo para trip)" }, "start_battery_level": { "type": "number", "description": "Nivel de batería al inicio en porcentaje 0-100 (solo para trip)" }, "end_battery_level": { "type": "number", "description": "Nivel de batería al final en porcentaje 0-100 (solo para trip)" }, "startAddress": { "type": "string", "nullable": true, "description": "Dirección de inicio (solo para trip)" }, "endAddress": { "type": "string", "nullable": true, "description": "Dirección de fin (solo para trip)" }, "address": { "type": "string", "nullable": true, "description": "Dirección de la parada (solo para stop_in_trip y stop_between_trips)" }, "lat": { "type": "number", "description": "Latitud de la posición (solo para stop_in_trip y stop_between_trips)" }, "lng": { "type": "number", "description": "Longitud de la posición (solo para stop_in_trip y stop_between_trips)" }, "type": { "type": "string", "description": "Tipo de evento o parada" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "alt": { "type": "number" }, "dir": { "type": "number" }, "speed": { "type": "number" }, "timestamp": { "type": "number" } } }, "description": "Array de posiciones del viaje (solo para trip, opcional)" }, "route": { "type": "string", "description": "Ruta codificada del viaje (solo para trip)" }, "clientId": { "type": "string", "description": "ID del cliente (solo para trip)" }, "assetId": { "type": "string", "description": "ID del activo (solo para trip)" }, "trip_id": { "type": "integer", "description": "ID del viaje asociado (solo para stop_in_trip)" }, "active": { "type": "boolean", "description": "Indica si la parada está activa (solo para stop_between_trips)" }, "device_id": { "type": "integer", "description": "ID del dispositivo en Flespi (solo para stop_between_trips)" }, "ident": { "type": "string", "description": "Identificador del dispositivo (solo para stop_between_trips)" }, "stop_duration": { "type": "integer", "description": "Duración de la parada en segundos (solo para stop_between_trips)" } } } }, "required": [ "eventType", "begin", "end", "timestamp", "data" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/{flespiId}/trips-with-stops": { "get": { "summary": "Obtener línea de tiempo de trips con stops dentro de viajes", "description": "Obtiene una línea de tiempo cronológica que combina trips y stops dentro de trips de un dispositivo específico.\n**No incluye stops entre trips.** Todos los eventos están ordenados cronológicamente por su timestamp de inicio (begin).\n\n**Tipos de eventos en la línea de tiempo:**\n- `trip`: Viaje del dispositivo\n- `stop_in_trip`: Parada dentro de un viaje\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n\n**Ejemplos:**\n- Solo fecha: `01/01/2025` → Desde 01/01/2025 00:00:00 hasta 01/01/2025 23:59:59\n- Con hora: `01/01/2025 08:30` → Desde 01/01/2025 08:30:00\n- Con hora completa: `01/01/2025 08:30:45` → Desde 01/01/2025 08:30:45\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "responses": { "200": { "description": "Línea de tiempo obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "trip", "stop_in_trip" ], "description": "Tipo de evento en la línea de tiempo" }, "begin": { "type": "integer", "description": "Timestamp de inicio del evento", "example": 1704067200 }, "end": { "type": "integer", "description": "Timestamp de fin del evento", "example": 1704070800 }, "timestamp": { "type": "integer", "description": "Timestamp del evento", "example": 1704067200 }, "tripId": { "type": "integer", "description": "ID del viaje asociado (solo para stop_in_trip)", "example": 12345 }, "data": { "type": "object", "description": "Datos completos del evento (trip o stop_in_trip)", "properties": { "id": { "type": "integer", "description": "ID del viaje o parada" }, "distance": { "type": "number", "description": "Distancia recorrida (solo para trip)" }, "duration": { "type": "integer", "description": "Duración en segundos" }, "startAddress": { "type": "string", "nullable": true, "description": "Dirección de inicio (solo para trip)" }, "endAddress": { "type": "string", "nullable": true, "description": "Dirección de fin (solo para trip)" }, "address": { "type": "string", "nullable": true, "description": "Dirección de la parada (solo para stop_in_trip)" }, "latitude": { "type": "number", "description": "Latitud de la posición" }, "longitude": { "type": "number", "description": "Longitud de la posición" } } } }, "required": [ "eventType", "begin", "end", "timestamp", "data" ] } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/auth/my-api-tokens": { "post": { "summary": "Crear un API token propio", "description": "Crea un nuevo API token (prefijo `atk_`) para el usuario autenticado.\n\n**Permisos requeridos:** `access_api_keys`\n\n**Datos requeridos:**\n- `name` (string, 1-100 caracteres): Nombre descriptivo del token\n- `type` (`persistent` | `temporary`): Tipo de token\n\n**Datos opcionales:**\n- `expiresIn` (number, milisegundos): Obligatorio cuando `type` es `temporary`; define la vida útil del token\n\n**Comportamiento:**\n- El token raw se retorna **una sola vez** y nunca se almacena en texto plano (solo su hash HMAC-SHA256)\n- El `clientId` y el `userId` se asignan automáticamente desde la sesión\n- Aplica rate limiting de creación de tokens\n\n**Requiere sesión de usuario:** un bearer `atk_` es rechazado con `403` y código `SESSION_REQUIRED`; un API token no puede crear otros tokens.\n", "tags": [ "Auth - Autenticación" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nombre descriptivo del token", "example": "Integración ERP" }, "type": { "type": "string", "enum": [ "persistent", "temporary" ], "description": "Tipo de token", "example": "persistent" }, "expiresIn": { "type": "number", "description": "Vida útil en milisegundos (obligatorio para tokens temporales)", "example": 3600000 } } } } } }, "responses": { "201": { "description": "API token creado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Token raw (prefijo atk_) - se muestra una única vez", "example": "atk_Xy2b...base64url" }, "tokenId": { "type": "string", "description": "ID del token creado", "example": "507f1f77bcf86cd799439011" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "get": { "summary": "Listar los API tokens propios", "description": "Lista los API tokens del usuario autenticado (sin exponer el hash ni el token raw).\n\n**Permisos requeridos:** `access_api_keys`\n\n**Requiere sesión de usuario:** un bearer `atk_` es rechazado con `403` y código `SESSION_REQUIRED`.\n", "tags": [ "Auth - Autenticación" ], "responses": { "200": { "description": "Lista de API tokens del usuario", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID del token" }, "name": { "type": "string", "description": "Nombre descriptivo del token" }, "tokenPrefix": { "type": "string", "description": "Prefijo visible del token (primeros 12 caracteres)", "example": "atk_Xy2bQ9zP" }, "type": { "type": "string", "enum": [ "persistent", "temporary" ] }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Fecha de expiración (null para tokens persistentes)" }, "isRevoked": { "type": "boolean", "description": "Si el token fue revocado" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Última vez que se usó el token" }, "createdAt": { "type": "string", "format": "date-time", "description": "Fecha de creación" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/auth/my-api-tokens/{tokenId}": { "delete": { "summary": "Revocar un API token propio", "description": "Revoca un API token del usuario autenticado por su ID (marca `isRevoked: true`).\n\n**Permisos requeridos:** `access_api_keys`\n\n**Comportamiento:**\n- Solo revoca tokens que pertenecen al usuario autenticado y no estén ya revocados\n- Retorna 404 si el token no existe o ya fue revocado\n\n**Requiere sesión de usuario:** un bearer `atk_` es rechazado con `403` y código `SESSION_REQUIRED`; un API token no puede revocar otros tokens.\n", "tags": [ "Auth - Autenticación" ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del API token" } ], "responses": { "200": { "description": "Token revocado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Token revocado exitosamente" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/geocode": { "get": { "summary": "Geocodificar una dirección de tarea", "description": "Forward geocoding de una dirección para los formularios de tarea.\n\n**Comportamiento:**\n- Provider primario Navixy, con fallback a Azure (con cache Redis)\n- Reemplaza el `/geocoder/search_address` que el web llamaba directo desde el browser\n- Devuelve la mejor coincidencia (0 o 1 resultado)\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Dirección a geocodificar" } ], "responses": { "200": { "description": "Coincidencias de geocodificación", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitud" }, "lng": { "type": "number", "description": "Longitud" }, "address": { "type": "string", "description": "Dirección formateada" } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/routes/optimize": { "post": { "summary": "Optimizar el orden de una ruta", "description": "Optimiza el orden de los puntos de una ruta (resolución del orden de visita óptimo vía Navixy).\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "startPoint", "routePoints" ], "properties": { "startPoint": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "description": "Punto de partida de la ruta" }, "routePoints": { "type": "array", "minItems": 1, "description": "Puntos de la ruta a ordenar", "items": { "type": "object", "required": [ "location", "from", "to" ], "properties": { "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "from": { "type": "string", "description": "Inicio de la ventana horaria" }, "to": { "type": "string", "description": "Fin de la ventana horaria" } } } } } } } } }, "responses": { "200": { "description": "Orden optimizado de la ruta", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "result": { "type": "array", "description": "Índices de los puntos en el orden óptimo de visita", "items": { "type": "number" } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/routes": { "post": { "summary": "Crear una ruta con checkpoints", "description": "Crea una ruta (secuencia de tareas encadenadas) con sus checkpoints en Navixy.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route", "checkpoints" ], "properties": { "route": { "type": "object", "required": [ "label", "from", "to" ], "description": "`trackerId` es obligatorio (en esa forma o, transitoriamente, como\nsu alias legacy `tracker_id`).\n", "properties": { "trackerId": { "type": "integer", "description": "ID del tracker/empleado asignado" }, "tracker_id": { "type": "integer", "deprecated": true, "description": "Alias legacy de `trackerId`; será eliminado" }, "label": { "type": "string" }, "description": { "type": "string" }, "from": { "type": "string", "description": "Inicio de la ventana horaria de la ruta" }, "to": { "type": "string", "description": "Fin de la ventana horaria de la ruta" } } }, "checkpoints": { "type": "array", "minItems": 1, "description": "Checkpoints (puntos de la ruta)", "items": { "type": "object", "required": [ "label", "description", "location", "from", "to" ], "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "object", "required": [ "lat", "lng", "address", "radius" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "integer", "description": "Radio del checkpoint en metros" } } }, "from": { "type": "string" }, "to": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Ruta creada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "ID de la ruta creada" }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "ID del checkpoint creado" } } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/bulk": { "post": { "summary": "Iniciar una operación masiva de tareas", "description": "Encola una operación masiva (update, delete o assign) sobre hasta 500 tareas y\nresponde de inmediato con el id de la operación. El procesamiento es asíncrono\n(BullMQ); consultar el progreso vía `GET /api/work/tasks/bulk/{bulkOperationId}`.\n\n**Operaciones (`operation`):**\n- `update`: `items` es un array de tareas completas a actualizar\n- `delete`: `items` es un array de `{ id }`\n- `assign`: `items` es un array de `{ id, trackerId }` (trackerId nullable para desasignar)\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "operation", "items" ], "properties": { "operation": { "type": "string", "enum": [ "update" ] }, "items": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Tareas completas a actualizar (mismo shape que el update unitario, con `id`)", "items": { "type": "object" } } } }, { "type": "object", "required": [ "operation", "items" ], "properties": { "operation": { "type": "string", "enum": [ "delete" ] }, "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" } } } } } }, { "type": "object", "required": [ "operation", "items" ], "properties": { "operation": { "type": "string", "enum": [ "assign" ] }, "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "id", "trackerId" ], "properties": { "id": { "type": "integer" }, "trackerId": { "type": "integer", "nullable": true } } } } } } ] } } } }, "responses": { "202": { "description": "Operación masiva encolada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "bulkOperationId": { "type": "string", "description": "ID de la operación masiva (para consultar su progreso)" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/bulk/{bulkOperationId}": { "get": { "summary": "Consultar el estado de una operación masiva", "description": "Devuelve el estado y progreso de una operación masiva de tareas previamente encolada.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "bulkOperationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "description": "ID de la operación masiva (ObjectId de 24 caracteres hex)" } ], "responses": { "200": { "description": "Estado de la operación masiva", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "userId": { "type": "string" }, "operation": { "type": "string", "enum": [ "update", "delete", "assign" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "completed_with_errors", "failed" ] }, "totalItems": { "type": "integer" }, "processedItems": { "type": "integer" }, "succeededItems": { "type": "integer" }, "failedItems": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "integer" }, "reason": { "type": "string" } } } }, "failureReason": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/recurring": { "get": { "summary": "Listar tareas recurrentes", "description": "Lista las tareas recurrentes (schedules) del cliente, enriquecidas con su empleado\ny su plantilla de formulario.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "responses": { "200": { "description": "Lista de tareas recurrentes", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "description": "Tarea recurrente adaptada (con empleado y plantilla de formulario embebidos)", "properties": { "id": { "type": "number" }, "trackerId": { "type": "number" }, "label": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "number" } } }, "maxDelay": { "type": "number" }, "minStayDuration": { "type": "number" }, "minArrivalDuration": { "type": "number" }, "fromTime": { "type": "string" }, "duration": { "type": "number" }, "parameters": { "type": "object", "description": "Frecuencia adaptada (weekdays | monthDays)", "properties": { "type": { "type": "string", "enum": [ "weekdays", "monthDays" ] }, "weekdays": { "type": "array", "items": { "type": "number" } }, "monthDays": { "type": "array", "items": { "type": "number" } } } }, "formTemplateId": { "type": "number", "nullable": true }, "type": { "type": "string" }, "employee": { "type": "object", "description": "Empleado Navixy adaptado", "properties": { "id": { "type": "string" }, "trackerId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "formTemplate": { "type": "object", "description": "Plantilla de formulario asociada" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear una tarea recurrente", "description": "Crea una tarea recurrente (schedule) que genera tareas según una frecuencia (días de\nla semana o días del mes).\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "location", "duration", "parameters" ], "description": "Datos de entrada para crear o actualizar una tarea recurrente.\n`fromTime` es obligatorio (en esa forma o, transitoriamente, como su alias\nlegacy `from_time`).\n", "properties": { "trackerId": { "type": "integer", "nullable": true, "description": "ID del tracker/empleado (nullable — schedule sin empleado)" }, "tracker_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `trackerId`; será eliminado" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "location": { "type": "object", "required": [ "lat", "lng", "address", "radius" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "integer", "description": "Radio en metros" } } }, "fromTime": { "type": "string", "description": "Hora de inicio de la tarea recurrente" }, "from_time": { "type": "string", "deprecated": true, "description": "Alias legacy de `fromTime`; será eliminado" }, "duration": { "type": "integer", "description": "Duración en segundos (entero positivo)" }, "parameters": { "type": "object", "description": "Frecuencia de la recurrencia", "oneOf": [ { "type": "object", "required": [ "type", "weekdays" ], "properties": { "type": { "type": "string", "enum": [ "weekdays" ] }, "weekdays": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Días de la semana (1-7)" } } }, { "type": "object", "required": [ "type" ], "description": "`monthDays` es obligatorio (en esa forma o, transitoriamente, como su\nalias legacy `month_days`). El valor `month_days` del discriminante\n`type` es un valor de enum persistido y no cambia.\n", "properties": { "type": { "type": "string", "enum": [ "month_days" ] }, "monthDays": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Días del mes (1-31)" }, "month_days": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "deprecated": true, "description": "Alias legacy de `monthDays`; será eliminado" } } } ] }, "maxDelay": { "type": "integer", "description": "Atraso máximo tolerado, en minutos" }, "max_delay": { "type": "integer", "deprecated": true, "description": "Alias legacy de `maxDelay`; será eliminado" }, "minStayDuration": { "type": "integer", "description": "Permanencia mínima exigida en la zona, en minutos" }, "min_stay_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minStayDuration`; será eliminado" }, "formTemplateId": { "type": "integer", "nullable": true, "description": "ID de la plantilla de formulario (null = sin plantilla)" }, "form_template_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `formTemplateId`; será eliminado" } } } } } }, "responses": { "201": { "description": "Tarea recurrente creada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "ID del schedule creado" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/recurring/{scheduleId}": { "patch": { "summary": "Actualizar una tarea recurrente", "description": "Actualiza una tarea recurrente existente. El id proviene del path.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID del schedule (entero positivo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "location", "duration", "parameters" ], "description": "Datos de entrada para crear o actualizar una tarea recurrente.\n`fromTime` es obligatorio (en esa forma o, transitoriamente, como su alias\nlegacy `from_time`).\n", "properties": { "trackerId": { "type": "integer", "nullable": true, "description": "ID del tracker/empleado (nullable — schedule sin empleado)" }, "tracker_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `trackerId`; será eliminado" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "location": { "type": "object", "required": [ "lat", "lng", "address", "radius" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "integer", "description": "Radio en metros" } } }, "fromTime": { "type": "string", "description": "Hora de inicio de la tarea recurrente" }, "from_time": { "type": "string", "deprecated": true, "description": "Alias legacy de `fromTime`; será eliminado" }, "duration": { "type": "integer", "description": "Duración en segundos (entero positivo)" }, "parameters": { "type": "object", "description": "Frecuencia de la recurrencia", "oneOf": [ { "type": "object", "required": [ "type", "weekdays" ], "properties": { "type": { "type": "string", "enum": [ "weekdays" ] }, "weekdays": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Días de la semana (1-7)" } } }, { "type": "object", "required": [ "type" ], "description": "`monthDays` es obligatorio (en esa forma o, transitoriamente, como su\nalias legacy `month_days`). El valor `month_days` del discriminante\n`type` es un valor de enum persistido y no cambia.\n", "properties": { "type": { "type": "string", "enum": [ "month_days" ] }, "monthDays": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "description": "Días del mes (1-31)" }, "month_days": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "deprecated": true, "description": "Alias legacy de `monthDays`; será eliminado" } } } ] }, "maxDelay": { "type": "integer", "description": "Atraso máximo tolerado, en minutos" }, "max_delay": { "type": "integer", "deprecated": true, "description": "Alias legacy de `maxDelay`; será eliminado" }, "minStayDuration": { "type": "integer", "description": "Permanencia mínima exigida en la zona, en minutos" }, "min_stay_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minStayDuration`; será eliminado" }, "formTemplateId": { "type": "integer", "nullable": true, "description": "ID de la plantilla de formulario (null = sin plantilla)" }, "form_template_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `formTemplateId`; será eliminado" } } } } } }, "responses": { "200": { "description": "Tarea recurrente actualizada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar una tarea recurrente", "description": "Elimina una tarea recurrente (schedule) del cliente.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID del schedule (entero positivo)" } ], "responses": { "200": { "description": "Tarea recurrente eliminada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks": { "get": { "summary": "Listar tareas", "description": "Lista las tareas del cliente, ya adaptadas al DTO de UI y enriquecidas con el\nempleado embebido (antes lo resolvía el web con `useEmployeeNavixyList`).\n\nCon `page` pagina el resultado; sin `page` devuelve todas las tareas que matchean\nel filtro.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página (base 1). Omitirlo devuelve todas las tareas que matchean el filtro.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Tamaño de página. Solo aplica junto con `page`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "from", "in": "query", "required": false, "description": "Inicio del rango (ISO 8601). Filtra por la fecha de inicio de la tarea.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Fin del rango (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "statuses", "in": "query", "required": false, "description": "Estados a incluir. Repetible (`?statuses=done&statuses=failed`).", "schema": { "type": "array", "items": { "type": "string", "enum": [ "unassigned", "assigned", "done", "failed", "delayed", "arrived", "faulty" ] } } }, { "name": "employees", "in": "query", "required": false, "description": "Ids de empleado Navixy. El backend los traduce a `tracker_id`.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "search", "in": "query", "required": false, "description": "Búsqueda de texto libre sobre la tarea (etiqueta, descripción, dirección).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "from", "status", "label", "stayDuration" ], "default": "from" } }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Lista de tareas", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Tarea adaptada para la UI (con empleado y formulario embebidos)", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "trackerId": { "type": "string" }, "status": { "type": "string" }, "statusChangeDate": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "externalId": { "type": "string" }, "creationDate": { "type": "string" }, "location": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "number", "description": "Radio de llegada en metros" } } }, "address": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "arrivalDate": { "type": "string" }, "stayDuration": { "type": "number" }, "type": { "type": "string" }, "tags": { "type": "array", "items": { "type": "number" } }, "employee": { "type": "object", "description": "Empleado Navixy adaptado", "properties": { "id": { "type": "string" }, "trackerId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "form": { "type": "object", "description": "Plantilla de formulario adjunta a la tarea" } } } }, "total": { "type": "integer", "description": "Total de tareas que matchean el filtro, no solo la página.", "example": 3412 } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear una tarea", "description": "Crea una tarea. Opcionalmente puede crear también su formulario asociado\n(`createForm: true` + `formTemplateId`).\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "object", "required": [ "label", "location", "from", "to" ], "description": "Datos de entrada para crear o actualizar una tarea", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trackerId": { "type": "integer", "nullable": true, "description": "ID del tracker/empleado asignado (null = sin asignar)" }, "tracker_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `trackerId`; será eliminado" }, "location": { "type": "object", "required": [ "lat", "lng", "address", "radius" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "integer", "description": "Radio en metros" } } }, "from": { "type": "string", "description": "Inicio de la ventana horaria" }, "to": { "type": "string", "description": "Fin de la ventana horaria" }, "formTemplateId": { "type": "integer", "description": "ID de la plantilla de formulario a adjuntar" }, "form_template_id": { "type": "integer", "deprecated": true, "description": "Alias legacy de `formTemplateId`; será eliminado" }, "externalId": { "type": "string", "description": "Identificador externo de la tarea (sistemas del cliente)" }, "external_id": { "type": "string", "deprecated": true, "description": "Alias legacy de `externalId`; será eliminado" }, "maxDelay": { "type": "integer", "description": "Atraso máximo tolerado, en minutos" }, "max_delay": { "type": "integer", "deprecated": true, "description": "Alias legacy de `maxDelay`; será eliminado" }, "minStayDuration": { "type": "integer", "description": "Permanencia mínima exigida en la zona, en minutos" }, "min_stay_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minStayDuration`; será eliminado" }, "minArrivalDuration": { "type": "integer", "description": "Duración mínima para considerar llegada, en minutos" }, "min_arrival_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minArrivalDuration`; será eliminado" } } }, "createForm": { "type": "boolean", "default": false, "description": "Si es true, adjunta el formulario indicado por `formTemplateId`" } } } } } }, "responses": { "201": { "description": "Tarea creada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "ID de la tarea creada" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/{taskId}": { "get": { "summary": "Leer una tarea", "description": "Lee una tarea individual, adaptada al DTO de UI y enriquecida con su empleado.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "responses": { "200": { "description": "Tarea encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Tarea adaptada para la UI (con empleado y formulario embebidos)", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "trackerId": { "type": "string" }, "status": { "type": "string" }, "statusChangeDate": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "externalId": { "type": "string" }, "creationDate": { "type": "string" }, "location": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "number", "description": "Radio de llegada en metros" } } }, "address": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "arrivalDate": { "type": "string" }, "stayDuration": { "type": "number" }, "type": { "type": "string" }, "tags": { "type": "array", "items": { "type": "number" } }, "employee": { "type": "object", "description": "Empleado Navixy adaptado", "properties": { "id": { "type": "string" }, "trackerId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "form": { "type": "object", "description": "Plantilla de formulario adjunta a la tarea" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "patch": { "summary": "Actualizar una tarea", "description": "Actualiza una tarea existente. El id proviene del path.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "location", "from", "to" ], "description": "Datos de entrada para crear o actualizar una tarea", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trackerId": { "type": "integer", "nullable": true, "description": "ID del tracker/empleado asignado (null = sin asignar)" }, "tracker_id": { "type": "integer", "nullable": true, "deprecated": true, "description": "Alias legacy de `trackerId`; será eliminado" }, "location": { "type": "object", "required": [ "lat", "lng", "address", "radius" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "radius": { "type": "integer", "description": "Radio en metros" } } }, "from": { "type": "string", "description": "Inicio de la ventana horaria" }, "to": { "type": "string", "description": "Fin de la ventana horaria" }, "formTemplateId": { "type": "integer", "description": "ID de la plantilla de formulario a adjuntar" }, "form_template_id": { "type": "integer", "deprecated": true, "description": "Alias legacy de `formTemplateId`; será eliminado" }, "externalId": { "type": "string", "description": "Identificador externo de la tarea (sistemas del cliente)" }, "external_id": { "type": "string", "deprecated": true, "description": "Alias legacy de `externalId`; será eliminado" }, "maxDelay": { "type": "integer", "description": "Atraso máximo tolerado, en minutos" }, "max_delay": { "type": "integer", "deprecated": true, "description": "Alias legacy de `maxDelay`; será eliminado" }, "minStayDuration": { "type": "integer", "description": "Permanencia mínima exigida en la zona, en minutos" }, "min_stay_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minStayDuration`; será eliminado" }, "minArrivalDuration": { "type": "integer", "description": "Duración mínima para considerar llegada, en minutos" }, "min_arrival_duration": { "type": "integer", "deprecated": true, "description": "Alias legacy de `minArrivalDuration`; será eliminado" } } } } } }, "responses": { "200": { "description": "Tarea actualizada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar una tarea", "description": "Elimina una tarea del cliente.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "responses": { "200": { "description": "Tarea eliminada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/{taskId}/assign": { "post": { "summary": "Asignar o desasignar una tarea", "description": "Asigna una tarea a un tracker/empleado, o la desasigna enviando `trackerId: null`.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerId" ], "properties": { "trackerId": { "type": "integer", "nullable": true, "description": "ID del tracker/empleado; `null` para desasignar" } } } } } }, "responses": { "200": { "description": "Tarea asignada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "assigned": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/tasks/{taskId}/form": { "get": { "summary": "Leer el formulario de una tarea", "description": "Lee el formulario asociado a una tarea (passthrough tipado del formulario Navixy).\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "responses": { "200": { "description": "Formulario de la tarea", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Formulario adjunto (estructura passthrough del proveedor)", "properties": { "value": { "type": "object", "description": "Valores del formulario" }, "files": { "type": "array", "items": { "type": "object" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Adjuntar un formulario a una tarea", "description": "Adjunta un formulario (plantilla) a una tarea.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "templateId" ], "properties": { "templateId": { "type": "integer", "minimum": 1, "description": "ID de la plantilla de formulario a adjuntar" } } } } } }, "responses": { "200": { "description": "Formulario adjuntado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "created": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar el formulario de una tarea", "description": "Elimina el formulario asociado a una tarea.\n\n**Permisos requeridos:** `access_tasks`\n", "tags": [ "Trabajo - Tareas" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "ID de la tarea (entero positivo)" } ], "responses": { "200": { "description": "Formulario eliminado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/employees/tags": { "get": { "summary": "Listar los tags de empleados", "description": "Catálogo de tags de Navixy con que se clasifican los empleados.\n\nAlimenta el desplegable múltiple del formulario de empleado y el de tareas.\n\n**Permisos requeridos:** `access_employees` **o** `access_tasks` (catálogo compartido:\nel flujo de tareas etiqueta con estos tags).\n", "tags": [ "Trabajo - Empleados" ], "responses": { "200": { "description": "Tags disponibles", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/employees/trackers": { "get": { "summary": "Listar los trackers asignables a un empleado", "description": "Trackers de Navixy candidatos a vincularse con un empleado.\n\nEs el desplegable de tracker del formulario de empleado: viene de Navixy y no del\nstore de trackers de Atlas, porque el vínculo empleado↔tracker vive en Navixy.\n\n**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "responses": { "200": { "description": "Trackers disponibles", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/employees": { "get": { "summary": "Listar los empleados del cliente", "description": "Empleados de la plataforma Navixy del cliente, adaptados al DTO camelCase de Atlas.\n\nNavixy omite los campos sin valor en vez de mandarlos vacíos: un empleado sin tags ni\nubicación llega sin esas claves. No existe un detalle que agregue nada — `/employee/read`\ndevuelve exactamente las mismas claves que el listado.\n\n**Permisos requeridos:** `access_employees` **o** `access_tasks` (catálogo compartido:\nel flujo de tareas necesita elegir a quién asignarlas).\n", "tags": [ "Trabajo - Empleados" ], "responses": { "200": { "description": "Empleados del cliente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "trackerId": { "type": "integer", "nullable": true, "description": "Tracker asignado, o null si el empleado no tiene ninguno" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "driverLicenseNumber": { "type": "string" }, "driverLicenseCats": { "type": "string" }, "driverLicenseIssueDate": { "type": "string", "nullable": true }, "driverLicenseValidTill": { "type": "string", "nullable": true }, "hardwareKey": { "type": "string", "nullable": true }, "departmentId": { "type": "integer", "nullable": true }, "personnelNumber": { "type": "string" }, "ssn": { "type": "string" }, "tags": { "type": "array", "items": { "type": "integer" }, "description": "Ausente si el empleado no tiene tags" }, "location": { "allOf": [ { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } } ], "nullable": true, "description": "Ausente si el empleado no tiene ubicación" }, "iconId": { "type": "integer", "nullable": true, "description": "Solo lectura; Navixy lo cambia por /employee/avatar/*" }, "avatarFileName": { "type": "string", "nullable": true, "description": "Solo lectura; Navixy lo cambia por /employee/avatar/*" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un empleado", "description": "Crea el empleado en la plataforma Navixy del cliente.\n\n**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName" ], "properties": { "firstName": { "type": "string", "minLength": 1 }, "middleName": { "type": "string", "default": "" }, "lastName": { "type": "string", "default": "" }, "email": { "type": "string", "description": "Email válido o cadena vacía", "default": "" }, "phone": { "type": "string", "default": "" }, "trackerId": { "type": "integer", "nullable": true, "default": null }, "departmentId": { "type": "integer", "nullable": true, "default": null }, "hardwareKey": { "type": "string", "nullable": true, "default": null, "description": "null = sin llave; la cadena vacía guardaría una llave vacía en Navixy" }, "personnelNumber": { "type": "string", "default": "" }, "ssn": { "type": "string", "default": "" }, "tags": { "type": "array", "items": { "type": "integer" }, "default": [] }, "location": { "type": "object", "nullable": true, "default": null, "description": "Base del empleado. `lat`/`lng` pueden venir en null: el backend geocodifica la\ndirección al guardar. Debe reenviarse tal como la entrega el listado, porque\nNavixy reemplaza el empleado entero y omitirla borra la ubicación guardada.\n", "required": [ "address" ], "properties": { "lat": { "type": "number", "nullable": true, "default": null }, "lng": { "type": "number", "nullable": true, "default": null }, "address": { "type": "string", "minLength": 1 } } }, "driverLicenseNumber": { "type": "string", "default": "" }, "driverLicenseCats": { "type": "string", "default": "" }, "driverLicenseIssueDate": { "type": "string", "nullable": true, "default": null }, "driverLicenseValidTill": { "type": "string", "nullable": true, "default": null } } } } } }, "responses": { "201": { "description": "Empleado creado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id del recurso creado en Navixy" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "409": { "description": "El tracker ya está asignado a otro empleado (código 247 de Navixy)" }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/employees/{employeeId}": { "patch": { "summary": "Actualizar un empleado", "description": "Actualiza el empleado completo: Navixy valida el objeto entero y rechaza los payloads\nparciales, así que el body debe traer todos los campos.\n\n**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del empleado en Navixy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName" ], "properties": { "firstName": { "type": "string", "minLength": 1 }, "middleName": { "type": "string", "default": "" }, "lastName": { "type": "string", "default": "" }, "email": { "type": "string", "description": "Email válido o cadena vacía", "default": "" }, "phone": { "type": "string", "default": "" }, "trackerId": { "type": "integer", "nullable": true, "default": null }, "departmentId": { "type": "integer", "nullable": true, "default": null }, "hardwareKey": { "type": "string", "nullable": true, "default": null, "description": "null = sin llave; la cadena vacía guardaría una llave vacía en Navixy" }, "personnelNumber": { "type": "string", "default": "" }, "ssn": { "type": "string", "default": "" }, "tags": { "type": "array", "items": { "type": "integer" }, "default": [] }, "location": { "type": "object", "nullable": true, "default": null, "description": "Base del empleado. `lat`/`lng` pueden venir en null: el backend geocodifica la\ndirección al guardar. Debe reenviarse tal como la entrega el listado, porque\nNavixy reemplaza el empleado entero y omitirla borra la ubicación guardada.\n", "required": [ "address" ], "properties": { "lat": { "type": "number", "nullable": true, "default": null }, "lng": { "type": "number", "nullable": true, "default": null }, "address": { "type": "string", "minLength": 1 } } }, "driverLicenseNumber": { "type": "string", "default": "" }, "driverLicenseCats": { "type": "string", "default": "" }, "driverLicenseIssueDate": { "type": "string", "nullable": true, "default": null }, "driverLicenseValidTill": { "type": "string", "nullable": true, "default": null } } } } } }, "responses": { "200": { "description": "Empleado actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un empleado", "description": "Elimina el empleado de la plataforma Navixy del cliente.\n\n**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del empleado en Navixy" } ], "responses": { "200": { "description": "Empleado eliminado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/departments": { "get": { "summary": "Listar los departamentos del cliente", "description": "Departamentos de Navixy a los que se adscriben los empleados.\n\n**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "responses": { "200": { "description": "Departamentos del cliente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "location": { "allOf": [ { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" } } } ], "nullable": true, "description": "La dirección del departamento vive acá. Navixy no tiene un campo `address` plano\ny descarta en silencio lo que se le mande con ese nombre. Ausente cuando el\ndepartamento no tiene ubicación.\n" } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear un departamento", "description": "**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1 }, "location": { "type": "object", "nullable": true, "default": null, "description": "Igual que la del empleado; el backend geocodifica si faltan coordenadas", "required": [ "address" ], "properties": { "lat": { "type": "number", "nullable": true, "default": null }, "lng": { "type": "number", "nullable": true, "default": null }, "address": { "type": "string", "minLength": 1 } } } } } } } }, "responses": { "201": { "description": "Departamento creado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id del recurso creado en Navixy" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/work/departments/{departmentId}": { "patch": { "summary": "Actualizar un departamento", "description": "**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "parameters": [ { "name": "departmentId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del departamento en Navixy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1 }, "location": { "type": "object", "nullable": true, "default": null, "description": "Igual que la del empleado; el backend geocodifica si faltan coordenadas", "required": [ "address" ], "properties": { "lat": { "type": "number", "nullable": true, "default": null }, "lng": { "type": "number", "nullable": true, "default": null }, "address": { "type": "string", "minLength": 1 } } } } } } } }, "responses": { "200": { "description": "Departamento actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un departamento", "description": "**Permisos requeridos:** `access_employees`\n", "tags": [ "Trabajo - Empleados" ], "parameters": [ { "name": "departmentId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del departamento en Navixy" } ], "responses": { "200": { "description": "Departamento eliminado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/places": { "post": { "summary": "Crear un POI (lugar)", "description": "Crea un punto de interés (POI) para el cliente autenticado.\n\n**Permisos requeridos:** `access_locations`\n\nEl `clientId` se toma del token; no se envía en el body.\n", "tags": [ "Otros - Lugares" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "location" ], "properties": { "label": { "type": "string", "minLength": 1, "description": "Nombre del POI", "example": "Bodega central" }, "description": { "type": "string", "description": "Descripción opcional del POI" }, "iconId": { "type": "integer", "minimum": 0, "description": "ID del ícono asociado al POI", "example": 3 }, "location": { "type": "object", "required": [ "lat", "lng", "radius" ], "properties": { "lat": { "type": "number", "description": "Latitud", "example": -33.4489 }, "lng": { "type": "number", "description": "Longitud", "example": -70.6693 }, "address": { "type": "string", "description": "Dirección opcional" }, "radius": { "type": "number", "description": "Radio en metros (positivo)", "example": 150 } } } } } } } }, "responses": { "201": { "description": "POI creado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "_id": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "clientId": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "label": { "type": "string", "example": "Bodega central" }, "description": { "type": "string" }, "iconId": { "type": "integer", "example": 3 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "example": -33.4489 }, "lng": { "type": "number", "example": -70.6693 }, "address": { "type": "string" }, "radius": { "type": "number", "example": 150 } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "get": { "summary": "Listar POIs del cliente", "description": "Devuelve todos los POIs del cliente autenticado, ordenados por `label`.\nLa paginación, búsqueda y orden se resuelven en el frontend.\n\n**Permisos requeridos:** `access_locations`\n", "tags": [ "Otros - Lugares" ], "responses": { "200": { "description": "Lista de POIs", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "clientId": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "label": { "type": "string", "example": "Bodega central" }, "description": { "type": "string" }, "iconId": { "type": "integer", "example": 3 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "example": -33.4489 }, "lng": { "type": "number", "example": -70.6693 }, "address": { "type": "string" }, "radius": { "type": "number", "example": 150 } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar POIs en lote", "description": "Elimina múltiples POIs del cliente autenticado. El body es un arreglo de\nObjectId (al menos uno). Solo se eliminan los POIs pertenecientes al cliente.\n\n**Permisos requeridos:** `access_locations`\n", "tags": [ "Otros - Lugares" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "ObjectId del POI" }, "example": [ "686848c8083287f50c1bbe6c", "686848c8083287f50c1bbe6d" ] } } } }, "responses": { "200": { "description": "POIs eliminados", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deletedCount": { "type": "integer", "description": "Cantidad de POIs eliminados", "example": 2 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/places/{id}": { "get": { "summary": "Obtener un POI por ID", "description": "Devuelve un POI del cliente autenticado por su ID.\n\n**Permisos requeridos:** `access_locations`\n", "tags": [ "Otros - Lugares" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "POI encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "_id": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "clientId": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "label": { "type": "string", "example": "Bodega central" }, "description": { "type": "string" }, "iconId": { "type": "integer", "example": 3 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "example": -33.4489 }, "lng": { "type": "number", "example": -70.6693 }, "address": { "type": "string" }, "radius": { "type": "number", "example": 150 } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar un POI por ID", "description": "Actualiza un POI del cliente autenticado. Se debe enviar al menos un campo.\nNo se permiten campos desconocidos (validación estricta).\n\n**Permisos requeridos:** `access_locations`\n", "tags": [ "Otros - Lugares" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "example": "Bodega norte" }, "description": { "type": "string" }, "iconId": { "type": "integer", "minimum": 0, "example": 5 }, "location": { "type": "object", "required": [ "lat", "lng", "radius" ], "properties": { "lat": { "type": "number", "example": -33.4489 }, "lng": { "type": "number", "example": -70.6693 }, "address": { "type": "string" }, "radius": { "type": "number", "example": 200 } } } } } } } }, "responses": { "200": { "description": "POI actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "_id": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "clientId": { "type": "string", "example": "686848c8083287f50c1bbe6c" }, "label": { "type": "string", "example": "Bodega norte" }, "description": { "type": "string" }, "iconId": { "type": "integer", "example": 5 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "example": -33.4489 }, "lng": { "type": "number", "example": -70.6693 }, "address": { "type": "string" }, "radius": { "type": "number", "example": 200 } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar un POI por ID", "description": "Elimina un POI del cliente autenticado por su ID.\n\n**Permisos requeridos:** `access_locations`\n", "tags": [ "Otros - Lugares" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "POI eliminado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deleted": { "type": "string", "description": "ID del POI eliminado", "example": "686848c8083287f50c1bbe6c" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/activos/{id}/disponibilidad": { "patch": { "summary": "Actualizar disponibilidad de un activo", "description": "Actualiza el estado de disponibilidad de un activo de carga (vehículo).\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Activos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "Nuevo estado de disponibilidad del activo", "enum": [ "Disponible para cargar", "En ruta a su destino", "Esperando en destino", "No disponible-Conductor", "No disponible-Descanso", "Retornando a cargar" ] } } } } } }, "responses": { "200": { "description": "Disponibilidad actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Activo actualizado" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/ubicaciones": { "post": { "summary": "Crear ubicación de cargo", "description": "Crea una ubicación de cargo (origen/destino) vinculada a geozonas de Atlas.\nSi no se envían coordenadas, se desnormalizan desde la geozona de llegada.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Ubicaciones" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nombre", "geozonaLlegadaId" ], "properties": { "ubicacionBaseId": { "type": "string", "description": "ID de la ubicación base de Atlas (opcional)" }, "nombre": { "type": "string" }, "direccion": { "type": "string" }, "encargado": { "type": "string" }, "telefono": { "type": "string" }, "coordenadas": { "type": "object", "description": "Coordenadas explícitas; si se omiten se derivan de la geozona", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "geozonaLlegadaId": { "type": "string", "description": "ObjectId de la geozona de llegada" }, "geozonaDescargaId": { "type": "string", "description": "ObjectId de la geozona de descarga (opcional)" } } } } } }, "responses": { "201": { "description": "Ubicación creada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "description": "Ubicación de cargo creada" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "get": { "summary": "Listar ubicaciones de cargo", "description": "Obtiene la lista de ubicaciones de cargo del cliente con sus geozonas asociadas.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Ubicaciones" ], "responses": { "200": { "description": "Lista de ubicaciones obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/ubicaciones/{id}": { "get": { "summary": "Obtener ubicación de cargo por ID", "tags": [ "Cargo - Ubicaciones" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Ubicación encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar ubicación de cargo", "tags": [ "Cargo - Ubicaciones" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Al menos un campo debe ser provisto", "properties": { "ubicacionBaseId": { "type": "string" }, "nombre": { "type": "string" }, "direccion": { "type": "string" }, "encargado": { "type": "string" }, "telefono": { "type": "string" }, "coordenadas": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "geozonaLlegadaId": { "type": "string" }, "geozonaDescargaId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Ubicación actualizada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar ubicación de cargo", "tags": [ "Cargo - Ubicaciones" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Ubicación eliminada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Ubicación eliminada" }, "ubicacion": { "type": "object", "description": "Ubicación eliminada" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/pedidos/activos": { "get": { "summary": "Listar pedidos activos", "description": "Obtiene los pedidos en estados activos (`programado`, `en_transito`, `en_destino`,\n`descargando`) con su indicador de salud derivado.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "responses": { "200": { "description": "Lista de pedidos activos obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "description": "Pedido con campo `salud` derivado" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/pedidos/{id}": { "get": { "summary": "Obtener pedido por ID", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Pedido encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "put": { "summary": "Actualizar pedido", "description": "Actualiza campos informativos de un pedido. Solo permitido en estado `programado`.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Al menos un campo debe ser provisto", "properties": { "guiaDespacho": { "type": "string" }, "fechaProgramada": { "type": "string", "format": "date-time" }, "horaSalida": { "type": "string", "format": "date-time" }, "etaLlegada": { "type": "string", "format": "date-time" }, "distanciaKm": { "type": "number" } } } } } }, "responses": { "200": { "description": "Pedido actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Eliminar pedido", "description": "Elimina un pedido. Solo permitido en pedidos `completado` o `cancelado`\n(los activos deben cancelarse primero).\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Pedido eliminado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Pedido eliminado" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/pedidos/{id}/estado": { "patch": { "summary": "Cambiar estado de un pedido", "description": "Transición manual de estado. Solo acepta `completado` (desde estados operativamente\ncerrables) o `cancelado`. Las transiciones automáticas provienen del worker de eventos\nde geozona.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "estado" ], "properties": { "estado": { "type": "string", "description": "Estado destino de la transición manual", "enum": [ "completado", "cancelado" ] } } } } } }, "responses": { "200": { "description": "Estado del pedido actualizado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object" } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "409": { "description": "Transición inválida o modificación concurrente\n(`PEDIDO_INVALID_TRANSITION` / `PEDIDO_CONCURRENT_MODIFICATION`)\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Transición inválida: programado → completado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/pedidos/{id}/calcular-eta": { "post": { "summary": "Calcular ETA de un pedido", "description": "Calcula la ETA vía Azure Maps usando las coordenadas de origen y destino del pedido,\ny actualiza `etaLlegada` y `distanciaKm`.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "ETA calculada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "pedido": { "type": "object", "description": "Pedido actualizado" }, "eta": { "type": "object", "description": "Resultado del cálculo (eta, distanceKm, durationMin)" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } }, "503": { "description": "No se pudo calcular la ETA; Azure Maps no devolvió una ruta válida\n(`ETA_CALCULATION_FAILED`). El frontend debe permitir ingreso manual.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "No se pudo calcular la ETA. Ingresa la ETA manualmente." } } } } } } } } }, "/api/cargo/pedidos/{id}/sanear": { "post": { "summary": "Sanear un pedido (botón mágico)", "description": "Re-deriva el pedido contra el historial de Flespi y lo deja en su estado fidedigno.\nDevuelve el diff `before`/`after` de lo aplicado.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Pedidos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del recurso" } ], "responses": { "200": { "description": "Pedido saneado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "changed": { "type": "boolean", "description": "Si el saneo produjo cambios" }, "reason": { "type": "string", "description": "Motivo de la decisión de saneo" }, "applied": { "type": "boolean", "description": "Si el patch se aplicó al pedido" }, "before": { "type": "object", "description": "Estado del pedido antes del saneo" }, "after": { "type": "object", "description": "Estado del pedido después del saneo" } } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/cargo/rendimiento": { "get": { "summary": "Rendimiento de transportistas", "description": "Devuelve el rendimiento agregado por trayecto (`origen→destino`) sobre los pedidos\nterminales del cliente: métricas pooled y ranking de transportistas por trayecto.\n\n**Permisos requeridos:** `access_cargo`\n", "tags": [ "Cargo - Rendimiento" ], "parameters": [ { "name": "desde", "in": "query", "required": false, "description": "Fecha inicial del rango sobre `horaSalida` (ISO)", "schema": { "type": "string", "format": "date-time" } }, { "name": "hasta", "in": "query", "required": false, "description": "Fecha final del rango sobre `horaSalida` (ISO)", "schema": { "type": "string", "format": "date-time" } }, { "name": "retrasoUmbralMin", "in": "query", "required": false, "description": "Umbral de retraso en minutos (número ≥ 0; ausente/vacío usa el default)", "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "Rendimiento obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "description": "Trayecto con métricas y ranking de transportistas" } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/checkins": { "post": { "summary": "Obtener reporte de check-ins de tareas", "tags": [ "Reportes - Check-ins" ], "description": "Recibe un rango de fechas y filtros opcionales por empleados y formularios.\nRetorna los check-ins registrados en tareas dentro del periodo, con soporte\npara búsqueda de texto y para incluir/excluir los formularios asociados.\n\n**Permisos requeridos:** `access_reports` + `access_tasks`\n\n**Nota:** Las fechas se envían en el body (no como query params).\n\n**Formato de fecha:** `DD/MM/YYYY HH:mm:ss`\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "example": "01/01/2025 08:00:00", "description": "Fecha de inicio (DD/MM/YYYY HH:mm:ss)" }, "to": { "type": "string", "example": "31/01/2025 17:45:00", "description": "Fecha de fin (DD/MM/YYYY HH:mm:ss)" }, "employeeIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de empleados a filtrar (opcional)" }, "formIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de formularios a filtrar (opcional)" }, "includeTaskForms": { "type": "boolean", "default": true, "description": "Incluir los formularios asociados a las tareas" }, "search": { "type": "string", "description": "Texto de búsqueda libre (opcional)" } } } } } }, "responses": { "200": { "description": "Reporte de check-ins obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/checkins/export": { "post": { "summary": "Exportar reporte de check-ins", "tags": [ "Reportes - Exportación" ], "description": "Genera un archivo Excel o PDF con el reporte de check-ins de tareas.\n\n**Permisos requeridos:** `access_reports` + `access_tasks`\n\n**Nota:** Las fechas se envían en el body (no como query params).\n\n**Formato de fecha:** `DD/MM/YYYY HH:mm:ss`\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "format" ], "properties": { "from": { "type": "string", "example": "01/01/2025 08:00:00", "description": "Fecha de inicio (DD/MM/YYYY HH:mm:ss)" }, "to": { "type": "string", "example": "31/01/2025 17:45:00", "description": "Fecha de fin (DD/MM/YYYY HH:mm:ss)" }, "employeeIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de empleados a filtrar (opcional)" }, "formIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de formularios a filtrar (opcional)" }, "includeTaskForms": { "type": "boolean", "default": true, "description": "Incluir los formularios asociados a las tareas" }, "search": { "type": "string", "description": "Texto de búsqueda libre (opcional)" }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato del archivo a generar" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/utilization/stats": { "post": { "summary": "Obtener estadísticas de utilización de assets", "tags": [ "Reportes - Utilización" ], "description": "Recibe N assets y un rango de fechas. Retorna el resumen de utilización por asset:\nhoras de uso (basado en ignición), distancia recorrida y consumo de batería.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" } } } } } }, "responses": { "200": { "description": "Estadísticas de utilización obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/utilization": { "post": { "summary": "Obtener desglose diario de utilización de un asset", "tags": [ "Reportes - Utilización" ], "description": "Devuelve el desglose diario de utilización de un asset: viajes, horas de uso,\ndistancia recorrida y consumo de batería por día.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "type": "string", "description": "ID del activo (MongoDB ObjectId)" } } } } } }, "responses": { "200": { "description": "Desglose diario de utilización obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/utilization/export": { "post": { "summary": "Exportar reporte de utilización de assets", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de utilización de los assets seleccionados.\nIncluye horas de uso (basado en ignición), distancia recorrida, y consumo de batería.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackerIds", "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "integer" }, "description": "IDs de los trackers (flespiId) a incluir en el reporte", "example": [ 1234, 5678 ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geofence-visits/stats": { "post": { "summary": "Obtener resumen de visitas agrupado por geocercas", "tags": [ "Reportes - Visitas por Geocercas" ], "description": "Recibe N assets, N geocercas y un rango de fechas. Retorna estadísticas por geocerca:\ncantidad de visitas, tiempo total dentro, tiempo promedio de parada y trackers únicos.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "geofenceIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" }, "geofenceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de las geocercas" }, "minDuration": { "type": "integer", "default": 180, "description": "Duración mínima de la visita en segundos" }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir en el filtrado (opcional)" }, "controlHoursStart": { "type": "string", "example": "08:00", "description": "Hora de inicio del horario a considerar (HH:mm, opcional)" }, "controlHoursEnd": { "type": "string", "example": "17:00", "description": "Hora de fin del horario a considerar (HH:mm, opcional)" } } } } } }, "responses": { "200": { "description": "Resumen de visitas por geocercas obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geofence-visits/{geofenceId}/detail": { "post": { "summary": "Obtener detalle de visitas de una geocerca específica", "tags": [ "Reportes - Visitas por Geocercas" ], "description": "Devuelve cada entrada de un tracker a la geocerca indicada con fecha/hora de entrada,\nsalida y duración, más un resumen agregado (cantidad, tiempo total y promedio).\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "path", "name": "geofenceId", "required": true, "schema": { "type": "string" }, "description": "ID de la geocerca (MongoDB ObjectId)" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minDuration": { "type": "integer", "default": 180, "description": "Duración mínima de la visita en segundos" }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir en el filtrado (opcional)" }, "controlHoursStart": { "type": "string", "example": "08:00", "description": "Hora de inicio del horario a considerar (HH:mm, opcional)" }, "controlHoursEnd": { "type": "string", "example": "17:00", "description": "Hora de fin del horario a considerar (HH:mm, opcional)" } } } } } }, "responses": { "200": { "description": "Detalle de visitas de la geocerca obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geofence-visits/export": { "post": { "summary": "Exportar resumen de visitas por geocercas", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de visitas por geocercas.\nIncluye estadísticas por geocerca: cantidad de visitas, tiempo total dentro,\ntiempo promedio de parada y trackers únicos que visitaron la geocerca.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los trackers a filtrar (opcional)", "example": [ "7174525", "7174578" ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "minDuration": { "type": "integer", "minimum": 0, "default": 180, "description": "Duración mínima de permanencia en segundos (default: 180 = 3 min)", "example": 180 } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geofence-visits/{geofenceId}/detail/export": { "post": { "summary": "Exportar detalle de visitas de una geocerca específica", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el detalle de visitas de una geocerca específica.\nIncluye cada entrada de un tracker a la geocerca con fecha/hora de entrada, salida y duración.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "path", "name": "geofenceId", "required": true, "schema": { "type": "string" }, "description": "ID de la geocerca (MongoDB ObjectId)" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "minDuration": { "type": "integer", "minimum": 0, "default": 180, "description": "Duración mínima de permanencia en segundos (default: 180 = 3 min)", "example": 180 } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geozone-progress/stats": { "post": { "summary": "Obtener estadísticas de progreso de geozonas", "tags": [ "Reportes - Progreso de Geozonas" ], "description": "Recibe N assets y un rango de fechas. Retorna el progreso de cobertura de las\ngeozonas agrícolas (superficie cubierta) por los assets indicados.\n\n**Permisos requeridos:** `access_reports` + `access_agriculture`\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" }, "geozoneIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de las geozonas a filtrar (opcional)" } } } } } }, "responses": { "200": { "description": "Estadísticas de progreso de geozonas obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geozone-progress/{geozoneId}/detail": { "post": { "summary": "Obtener detalle de progreso de una geozona específica", "tags": [ "Reportes - Progreso de Geozonas" ], "description": "Devuelve el detalle de cobertura de una geozona agrícola específica para los\nassets indicados en el rango de fechas.\n\n**Permisos requeridos:** `access_reports` + `access_agriculture`\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "path", "name": "geozoneId", "required": true, "schema": { "type": "string" }, "description": "ID de la geozona" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" } } } } } }, "responses": { "200": { "description": "Detalle de progreso de la geozona obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/geozone-progress/export": { "post": { "summary": "Exportar reporte de progreso de geozonas", "tags": [ "Reportes - Exportación" ], "description": "Genera un archivo Excel o PDF con el progreso de cobertura de las geozonas agrícolas.\n\n**Permisos requeridos:** `access_reports` + `access_agriculture`\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "format" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" }, "geozoneIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de las geozonas a filtrar (opcional)" }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato del archivo a generar" }, "showSeconds": { "type": "boolean", "default": false, "description": "Mostrar segundos en las duraciones (opcional)" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/tracker-visits/stats": { "post": { "summary": "Obtener resumen de visitas agrupado por trackers", "tags": [ "Reportes - Visitas por Trackers" ], "description": "Recibe N assets, N geocercas y un rango de fechas. Retorna estadísticas por tracker:\ngeocercas visitadas, tiempo total dentro, tiempo total fuera y cantidad total de visitas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "geofenceIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" }, "geofenceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de las geocercas" }, "minDuration": { "type": "integer", "default": 180, "description": "Duración mínima de la visita en segundos" }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir en el filtrado (opcional)" }, "controlHoursStart": { "type": "string", "example": "08:00", "description": "Hora de inicio del horario a considerar (HH:mm, opcional)" }, "controlHoursEnd": { "type": "string", "example": "17:00", "description": "Hora de fin del horario a considerar (HH:mm, opcional)" } } } } } }, "responses": { "200": { "description": "Resumen de visitas por trackers obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/tracker-visits/{assetId}/detail": { "post": { "summary": "Obtener detalle de visitas de un asset específico", "tags": [ "Reportes - Visitas por Trackers" ], "description": "Resuelve el asset a su tracker principal (`mainTrackerId`) y devuelve el detalle de\nsus visitas a geocercas: nombre de geocerca, dirección, entrada, salida y duración.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "path", "name": "assetId", "required": true, "schema": { "type": "string" }, "description": "ID del activo (MongoDB ObjectId)" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minDuration": { "type": "integer", "default": 180, "description": "Duración mínima de la visita en segundos" }, "controlDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Días de la semana a incluir en el filtrado (opcional)" }, "controlHoursStart": { "type": "string", "example": "08:00", "description": "Hora de inicio del horario a considerar (HH:mm, opcional)" }, "controlHoursEnd": { "type": "string", "example": "17:00", "description": "Hora de fin del horario a considerar (HH:mm, opcional)" } } } } } }, "responses": { "200": { "description": "Detalle de visitas del tracker obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/tracker-visits/export": { "post": { "summary": "Exportar resumen de visitas por trackers", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el resumen de visitas por trackers.\nIncluye estadísticas por tracker: geocercas visitadas, tiempo total dentro,\ntiempo total fuera y cantidad total de visitas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "trackerIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los trackers a filtrar (opcional)", "example": [ "7174525", "7174578" ] }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "minDuration": { "type": "integer", "minimum": 0, "default": 180, "description": "Duración mínima de permanencia en segundos (default: 180 = 3 min)", "example": 180 } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/tracker-visits/{assetId}/detail/export": { "post": { "summary": "Exportar detalle de visitas de un tracker específico", "tags": [ "Reportes - Exportación" ], "security": [ { "bearerAuth": [] } ], "description": "Genera un archivo Excel o PDF con el detalle de visitas de un tracker específico.\nIncluye cada visita a geocercas con nombre de geocerca, dirección, fecha/hora de entrada, salida y duración.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "path", "name": "assetId", "required": true, "schema": { "type": "string" }, "description": "ID del activo (MongoDB ObjectId)" }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato de archivo a generar (pdf o xlsx).", "example": "pdf" }, "minDuration": { "type": "integer", "minimum": 0, "default": 180, "description": "Duración mínima de permanencia en segundos (default: 180 = 3 min)", "example": 180 } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/temperature/stats": { "post": { "summary": "Obtener estadísticas de temperatura", "tags": [ "Reportes - Temperatura" ], "description": "Recibe N assets y un rango de fechas. Retorna estadísticas de temperatura por asset\n(mínima, máxima y promedio) a partir de los sensores reportados.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" } } } } } }, "responses": { "200": { "description": "Estadísticas de temperatura obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/temperature": { "post": { "summary": "Obtener detalle de temperatura de un asset", "tags": [ "Reportes - Temperatura" ], "description": "Devuelve las lecturas de temperatura individuales de un asset en el rango de fechas.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "type": "string", "description": "ID del activo (MongoDB ObjectId)" } } } } } }, "responses": { "200": { "description": "Detalle de temperatura obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/reports/temperature/export": { "post": { "summary": "Exportar reporte de temperatura", "tags": [ "Reportes - Exportación" ], "description": "Genera un archivo Excel o PDF con el resumen de temperatura de los assets seleccionados.\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos\n", "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "format" ], "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "IDs de los activos (MongoDB ObjectIds)" }, "format": { "type": "string", "enum": [ "pdf", "xlsx" ], "description": "Formato del archivo a generar" }, "showSeconds": { "type": "boolean", "default": false, "description": "Mostrar segundos en las duraciones (opcional)" } } } } } }, "responses": { "200": { "description": "Archivo generado exitosamente", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/scheduled-reports/executions/{executionId}": { "get": { "summary": "Obtener detalle de una ejecución", "tags": [ "Reportes - Reportes Programados" ], "description": "Obtiene el detalle de una ejecución específica de un reporte programado del cliente autenticado", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID de la ejecución (MongoDB ObjectId)" } ], "responses": { "200": { "description": "Ejecución encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": {} } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/scheduled-reports/{id}/executions": { "get": { "summary": "Obtener historial de ejecuciones de un reporte programado", "tags": [ "Reportes - Reportes Programados" ], "description": "Obtiene el historial paginado de ejecuciones de un reporte programado, ordenado de más reciente a más antiguo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Número de página (por defecto 1)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "description": "Cantidad de ejecuciones por página (por defecto 10, máximo 50)" } ], "responses": { "200": { "description": "Historial de ejecuciones", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "executions": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/scheduled-reports/{id}/executions/latest": { "get": { "summary": "Obtener la última ejecución completada", "tags": [ "Reportes - Reportes Programados" ], "description": "Devuelve la última ejecución completada de un reporte programado, con todos sus\narchivos descargables (uno por formato marcado). Las URLs de descarga se re-firman\nen cada consulta. Retorna 404 si aún no hay ninguna ejecución exitosa.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del reporte programado" } ], "responses": { "200": { "description": "Última ejecución completada", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "fileUrl": { "type": "string" } } } }, "periodFrom": { "type": "string" }, "periodTo": { "type": "string" }, "emailSentAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/flespi/{flespiId}/name": { "patch": { "summary": "Renombrar un tracker por Flespi ID", "description": "Actualiza únicamente el nombre de un tracker identificado por su `flespiId`.\n\n**Permisos requeridos:** `access_fleet_assets`\n\n**Datos requeridos:**\n- `name` (string): Nuevo nombre del tracker (no puede estar vacío)\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Nuevo nombre del tracker", "example": "Camión 01" } } } } } }, "responses": { "200": { "description": "Tracker renombrado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/flespi/{flespiId}/inputs": { "get": { "summary": "Obtener inputs disponibles para configurar sensores", "description": "Devuelve los DIN (entradas digitales) disponibles para asociar a sensores de un\ntracker Atlas (Flespi), junto con los sensores ya configurados y las fuentes de\ntemperatura reportadas por el dispositivo.\n\n**Permisos requeridos:** `access_tracking` o `access_fleet_assets`\n\n**Comportamiento:**\n- `available`: DIN ofrecidos al usuario para asignar a un sensor (superset entre el\n rango por defecto y los DIN observados en telemetría dentro del rango válido)\n- `seen`: DIN que aparecieron al menos una vez en la telemetría del dispositivo\n- `configured`: sensores ya asignados según el subdocumento `sensors` del tracker en\n MongoDB (`null` si el tracker nunca fue configurado)\n- `temperatureSources`: fuentes de temperatura que el dispositivo reporta con su valor\n actual, en orden de prioridad (`[]` si Flespi está caído o no reporta temperatura)\n\n**Nota:** la telemetría de Flespi es best-effort; si falla, `seen` y\n`temperatureSources` degradan a arrays vacíos sin abortar la respuesta.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" } ], "responses": { "200": { "description": "Inputs del tracker obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "available": { "type": "array", "description": "DIN disponibles para asignar a un sensor", "items": { "type": "number" }, "example": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "seen": { "type": "array", "description": "DIN observados en la telemetría del dispositivo", "items": { "type": "number" }, "example": [ 1, 2 ] }, "configured": { "type": "object", "nullable": true, "description": "Sensores ya asignados (null si nunca se configuró)", "properties": { "sos": { "type": "object", "properties": { "inputBit": { "type": "number", "description": "DIN asignado al sensor SOS", "example": 1 } } }, "ignition": { "type": "object", "properties": { "inputBit": { "type": "number", "description": "DIN cableado a la ignición (reemplaza a engine.ignition.status en interval)", "example": 1 } } }, "temperature": { "type": "object", "properties": { "source": { "type": "string", "description": "Clave de telemetría de la fuente de temperatura" } } } } }, "temperatureSources": { "type": "array", "description": "Fuentes de temperatura reportadas con su valor actual", "items": { "type": "object" } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trackers/flespi/{flespiId}/sensors": { "patch": { "summary": "Configurar sensores de un tracker por Flespi ID", "description": "Actualiza la configuración de sensores de un tracker (PATCH parcial). Solo persiste\nlos sensores presentes en el body; el mapping sensor→DIN es metadata Atlas y no se\nreplica al dispositivo en Flespi.\n\n**Permisos requeridos:** `access_fleet_assets`\n\n**Semántica por sensor:**\n- objeto (`{ inputBit }` / `{ source }`) → asigna el sensor\n- `null` → desasigna el sensor (unset)\n- omitido → no se toca\n\n**Nota:** debe enviarse al menos un sensor a actualizar.\n\n**Colisión de DIN:** `sos` e `ignition` no pueden compartir `inputBit`. Se valida la\nconfiguración resultante (persistida + PATCH); la colisión responde 409\n`TRACKER_SENSOR_DIN_CONFLICT`.\n", "tags": [ "Tracking - Trackers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "flespiId", "in": "path", "required": true, "schema": { "type": "number" }, "description": "ID del dispositivo en Flespi" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "sos": { "type": "object", "nullable": true, "description": "Sensor SOS. null para desasignar", "required": [ "inputBit" ], "properties": { "inputBit": { "type": "number", "description": "DIN a asociar al sensor SOS", "example": 1 } } }, "ignition": { "type": "object", "nullable": true, "description": "Sensor de ignición por DIN. null para desasignar. Configurado, interval\nlee `din.N` como señal de ignición en vez de `engine.ignition.status`\n(viajes por ignición, alertas de ignición, horas motor).\n", "required": [ "inputBit" ], "properties": { "inputBit": { "type": "number", "description": "DIN cableado a la ignición", "example": 1 } } }, "temperature": { "type": "object", "nullable": true, "description": "Sensor de temperatura. null para desasignar", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "Clave de telemetría de la fuente de temperatura" } } } } } } } }, "responses": { "200": { "description": "Sensores del tracker actualizados exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "flespiId": { "type": "string" }, "imei": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "phone": { "type": "string" }, "hardware": { "type": "string" }, "lastPosition": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "altitude": { "type": "number" } } }, "lastConnection": { "type": "string", "format": "date-time" }, "speed": { "type": "number" }, "ignitionStatus": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "trip_config": { "type": "string", "enum": [ "ignition", "no_config", "motion" ], "description": "ignition = Trips_Ignition, no_config = Trips, motion = Trips_Motion_0-3391167", "default": "no_config" }, "initial_odometer": { "type": "number", "description": "Valor base del odometro (odometro_usuario - total_mileage al momento de configurar). Puede ser negativo", "default": 0 }, "odometer_calculated": { "type": "boolean", "description": "true = el tracker consume el odometro del calculator de Flespi, false = no configurado", "default": false }, "initial_horometer": { "type": "number", "description": "Valor base del horometro (horometro_usuario - total_engine_hours al momento de configurar). Puede ser negativo", "default": 0 }, "horometer_calculated": { "type": "boolean", "description": "true = el tracker consume el horometro del calculator de Flespi, false = no configurado", "default": false } }, "required": [ "imei" ] } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "409": { "description": "Conflicto con el estado actual del recurso", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "code": { "type": "string", "example": "TRACKER_SENSOR_DIN_CONFLICT" }, "message": { "type": "string", "example": "Esa entrada digital ya está asignada a otro sensor del dispositivo" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/bulk/fuel-config": { "patch": { "summary": "Vincular masivamente combustible a varios activos", "description": "Aplica la configuración de combustible a un lote de activos: los\nvincula a una tarifa default (`fuelType`) o a una FuelTariff custom de la\nempresa (`fuelTariffId`, el tipo base se deriva de la tarifa y el precio lo\ndefine la tarifa). Reemplaza el subdocumento completo — lo que no viene,\nse borra (p. ej. el precio propio al reactivar la sincronización CNE).\n\n**Permisos requeridos:** `access_fleet_assets`\n\n**Reglas:**\n- `fuelType` y `fuelTariffId` son mutuamente excluyentes (exactamente uno)\n- `fuelPriceOverride` solo acompaña a `fuelType` (con tarifa, el precio es de la tarifa)\n- Solo se actualizan activos del `clientId` del usuario autenticado\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "fuelNormRate" ], "properties": { "assetIds": { "type": "array", "minItems": 1, "maxItems": 500, "description": "IDs de los activos a vincular", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, "fuelType": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ], "description": "Tarifa default (tipo del catálogo); excluyente con fuelTariffId" }, "fuelTariffId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "FuelTariff custom de la empresa; excluyente con fuelType" }, "fuelNormRate": { "type": "number", "description": "Rendimiento nominal en km/L", "example": 10 }, "fuelPriceOverride": { "type": "number", "nullable": true, "description": "Precio propio del lote (CLP/L, bruto) con la sincronización CNE apagada" } } } } } }, "responses": { "200": { "description": "Configuración de combustible aplicada al lote", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "matched": { "type": "number", "description": "Cantidad de activos que coincidieron con el filtro", "example": 10 }, "modified": { "type": "number", "description": "Cantidad de activos efectivamente modificados", "example": 10 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Tarifa de combustible no encontrada" }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/assets/bulk/icon": { "patch": { "summary": "Actualizar masivamente el icono de varios activos", "description": "Actualiza el icono de un conjunto de activos en una sola operación.\n\n**Permisos requeridos:** `access_fleet_assets`\n\n**Datos requeridos:**\n- `assetIds` (array de ObjectId): IDs de los activos a actualizar (entre 1 y 500)\n- `icon` (object): Objeto con `id` (string) y `color` (string, formato hexadecimal\n #RRGGBB o #RGB); opcionalmente `useGroupColor` (boolean)\n\n**Comportamiento automático:**\n- Solo se actualizan activos del `clientId` del usuario autenticado\n- Los IDs fuera del cliente simplemente no coinciden\n", "tags": [ "Activos - Assets" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "icon" ], "properties": { "assetIds": { "type": "array", "minItems": 1, "maxItems": 500, "description": "IDs de los activos a actualizar", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "example": [ "68ed563b12a66729a9194215", "68ed563b12a66729a9194216" ] }, "icon": { "type": "object", "required": [ "id", "color" ], "properties": { "id": { "type": "string", "description": "Tipo de icono", "example": "truck" }, "color": { "type": "string", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "description": "Color en formato hexadecimal", "example": "#000000" }, "useGroupColor": { "type": "boolean", "description": "Usar el color del grupo del activo" } } } } } } } }, "responses": { "200": { "description": "Iconos actualizados masivamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "matchedCount": { "type": "number", "description": "Cantidad de activos que coincidieron con el filtro", "example": 10 }, "modifiedCount": { "type": "number", "description": "Cantidad de activos efectivamente modificados", "example": 10 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/stats/heatmap": { "get": { "summary": "Obtener mapa de calor de actividad de la flota", "description": "Devuelve el mapa de calor de actividad de la flota: cantidad de viajes iniciados por\ndía de la semana y hora del día en un rango de fechas. Usa el mismo scope de assets y\nfiltros (smart + monitoreo) que `GET /api/trips/stats`.\n\nSolo se emiten celdas con `tripsCount > 0`. La hora corresponde a la zona\n`America/Santiago`.\n\n**Permisos requeridos:** `access_trips`\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" }, { "in": "query", "name": "assetIds", "required": false, "schema": { "type": "string" }, "description": "Lista de IDs de activos separados por coma (CSV) para restringir el agregado al subconjunto seleccionado, siempre dentro del scope autorizado", "example": "68ed563b12a66729a9194215,68ed563b12a66729a9194216" } ], "responses": { "200": { "description": "Mapa de calor obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "heatmap": { "type": "array", "description": "Celdas del mapa de calor (solo celdas con tripsCount > 0)", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "description": "Día de la semana" }, "hour": { "type": "number", "description": "Hora del día (0-23, zona America/Santiago)", "example": 8 }, "tripsCount": { "type": "number", "description": "Cantidad de viajes iniciados en la celda", "example": 12 }, "distanceKm": { "type": "number", "description": "Suma de distancia (km) de los viajes de la celda", "example": 145.3 }, "durationSeconds": { "type": "number", "description": "Suma de duración (segundos) de los viajes de la celda", "example": 7200 } } } }, "totalTrips": { "type": "number", "description": "Total de viajes válidos agregados en el rango", "example": 120 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/trips/stats/daily": { "get": { "summary": "Obtener actividad diaria de viajes", "description": "Devuelve la actividad de viajes agregada por día calendario: cantidad de viajes\niniciados, distancia y duración acumuladas. Usa el mismo scope de assets y filtros\n(smart + monitoreo) que `GET /api/trips/stats`.\n\nSolo se emiten días con `tripsCount > 0`, en orden cronológico ascendente. El día\ncorresponde a la zona `America/Santiago`.\n\n**Permisos requeridos:** `access_trips`\n\n**Formatos de fecha aceptados:**\n- `DD/MM/YYYY` - Solo fecha (desde las 00:00:00 hasta las 23:59:59 del día)\n- `DD/MM/YYYY HH:mm` - Fecha con hora y minutos específicos\n- `DD/MM/YYYY HH:mm:ss` - Fecha con hora, minutos y segundos específicos\n", "tags": [ "Tracking - Viajes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "description": "Fecha de inicio. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `01/01/2025` o `01/01/2025 08:30`)", "example": "01/01/2025 08:30" }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "description": "Fecha de fin. Formatos aceptados - DD/MM/YYYY, DD/MM/YYYY HH:mm, DD/MM/YYYY HH:mm:ss (ejemplo: `31/01/2025` o `31/01/2025 17:45`)", "example": "31/01/2025 17:45" }, { "in": "query", "name": "assetIds", "required": false, "schema": { "type": "string" }, "description": "Lista de IDs de activos separados por coma (CSV) para restringir el agregado al subconjunto seleccionado, siempre dentro del scope autorizado", "example": "68ed563b12a66729a9194215" } ], "responses": { "200": { "description": "Actividad diaria obtenida exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "daily": { "type": "array", "description": "Días con actividad (solo días con tripsCount > 0), en orden cronológico", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Fecha local (zona America/Santiago) en formato YYYY-MM-DD", "example": "2025-01-15" }, "tripsCount": { "type": "number", "description": "Cantidad de viajes iniciados en el día", "example": 8 }, "distanceKm": { "type": "number", "description": "Suma de distancia (km) de los viajes del día", "example": 145.3 }, "durationSeconds": { "type": "number", "description": "Suma de duración (segundos) de los viajes del día", "example": 7200 } } } }, "totalTrips": { "type": "number", "description": "Total de viajes válidos agregados en el rango", "example": 120 } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/preview": { "post": { "summary": "Generar preview de importación de geocercas (KML/KMZ)", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Sube un archivo KML o KMZ y genera una sesión de preview con el resultado del análisis,\nsin crear todavía ninguna geocerca. Cada placemark se extrae, se prepara su geometría\n(simplificación con control de calidad) y se clasifica como importable, duplicada o\nrechazada.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- No crea geocercas: solo persiste una sesión de preview (con TTL) y sus ítems\n- Detecta duplicados comparando el hash de geometría contra las geocercas del cliente\n- La sesión debe confirmarse luego con `POST /api/geofences/imports/{previewId}/confirm`\n\n**Notas:**\n- El `previewId` retornado es el identificador de la sesión de preview\n- Tamaño máximo del archivo: 50MB\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Archivo KML o KMZ (tamaño máximo 50MB)" } } } } } }, "responses": { "201": { "description": "Preview generado exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "previewId": { "type": "string", "description": "ID de la sesión de preview", "example": "507f1f77bcf86cd799439011" }, "fileName": { "type": "string", "description": "Nombre del archivo subido", "example": "geocercas.kml" }, "sourceHash": { "type": "string", "description": "Hash SHA-256 del archivo original" }, "summary": { "type": "object", "properties": { "totalPlacemarks": { "type": "number", "description": "Total de placemarks encontrados en el archivo" }, "totalPolygons": { "type": "number", "description": "Total de polígonos encontrados" }, "totalItems": { "type": "number", "description": "Total de ítems generados en el preview" }, "importableCount": { "type": "number", "description": "Ítems importables (nuevos y válidos)" }, "rejectedCount": { "type": "number", "description": "Ítems rechazados" }, "duplicateCount": { "type": "number", "description": "Ítems duplicados (geometría equivalente ya existente)" }, "simplifiedCount": { "type": "number", "description": "Ítems cuya geometría fue simplificada" }, "rejectedWithHoles": { "type": "number", "description": "Polígonos rechazados por contener hoyos" }, "rejectedByQuality": { "type": "number", "description": "Ítems rechazados por no cumplir la calidad de simplificación" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/{previewId}/confirm": { "post": { "summary": "Confirmar importación de geocercas desde un preview", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Confirma una sesión de preview y encola el trabajo de importación en background que\ncrea las geocercas importables en Flespi y MongoDB.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- Consume la sesión de preview y crea un historial de importación (`importId`)\n- El procesamiento es asíncrono (BullMQ); el estado se consulta con\n `GET /api/geofences/imports/{importId}`\n- Es idempotente ante reintentos: si la importación ya fue iniciada, retorna\n `alreadyStarted: true`\n- Acepta opcionalmente `excludedItemIds` para excluir ítems importables puntuales:\n esos ítems quedan con estado `skipped` y no se crean como geocercas\n- En reintentos sobre una sesión ya consumida, las exclusiones nuevas se ignoran:\n manda la selección del primer confirm\n\n**Notas:**\n- El `previewId` debe ser un ObjectId de MongoDB (24 caracteres hexadecimales)\n- Si la exclusión no deja ítems importables, responde 400\n- El body es estricto: un campo desconocido (p. ej. un typo de\n `excludedItemIds`) responde 400 en vez de importar el preview completo\n", "parameters": [ { "name": "previewId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "ID de la sesión de preview (24 caracteres hex)", "example": "507f1f77bcf86cd799439011" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "excludedItemIds": { "type": "array", "maxItems": 5000, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "IDs de ítems del preview que se excluyen de la importación", "example": [ "507f1f77bcf86cd799439099" ] } } } } } }, "responses": { "202": { "description": "Importación encolada exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "importId": { "type": "string", "description": "ID del historial de importación", "example": "507f191e810c19729de860ea" }, "status": { "type": "string", "description": "Estado inicial de la importación", "example": "pending" }, "alreadyStarted": { "type": "boolean", "description": "true si la importación ya había sido iniciada", "example": false } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/previews/{previewId}/items": { "get": { "summary": "Listar ítems de un preview de importación con su geometría", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Lista los ítems generados por un preview de importación, incluyendo la geometría\nde cada geocerca parseada, para previsualizarlas en el mapa antes de confirmar.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- Solo retorna ítems si la sesión de preview pertenece al cliente y usuario autenticados\n- La sesión de preview expira por TTL (~1 hora) si no se confirma\n\n**Notas:**\n- A diferencia de `GET /api/geofences/imports/{importId}/items`, este listado incluye\n `geometry` y funciona antes de confirmar\n", "parameters": [ { "name": "previewId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "ID de la sesión de preview (24 caracteres hex)", "example": "507f1f77bcf86cd799439011" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Página a retornar" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }, "description": "Ítems por página (máximo 500)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "pending", "rejected", "duplicate" ] }, "description": "Filtra por estado del ítem ('all' retorna todos)" } ], "responses": { "200": { "description": "Ítems del preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID del ítem de importación", "example": "507f1f77bcf86cd799439099" }, "name": { "type": "string", "description": "Nombre final de la geocerca" }, "originalName": { "type": "string", "description": "Nombre original del placemark" }, "status": { "type": "string", "enum": [ "pending", "rejected", "duplicate" ], "description": "Clasificación del ítem en el preview" }, "rejectedReason": { "type": "string", "description": "Motivo de rechazo o duplicado, si aplica" }, "partIndex": { "type": "number", "description": "Índice de parte para placemarks multi-polígono" }, "partsTotal": { "type": "number", "description": "Total de partes del placemark" }, "originalVertices": { "type": "number", "description": "Vértices del polígono original" }, "simplifiedVertices": { "type": "number", "description": "Vértices tras la simplificación" }, "geometry": { "type": "object", "description": "Geometría preparada (ausente en rechazados sin geometría válida)", "properties": { "type": { "type": "string", "enum": [ "polygon" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } } } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/{importId}": { "get": { "summary": "Obtener estado de una importación de geocercas", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Obtiene el historial y el estado agregado de una importación de geocercas, incluyendo\nel conteo de ítems por estado.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- Solo retorna la importación si pertenece al cliente autenticado\n", "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "ID del historial de importación (24 caracteres hex)", "example": "507f191e810c19729de860ea" } ], "responses": { "200": { "description": "Estado de importación obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "import": { "type": "object", "description": "Documento del historial de importación (fileName, status, totales, timestamps, etc.)" }, "counts": { "type": "object", "description": "Conteo de ítems por estado", "additionalProperties": { "type": "number" }, "example": { "pending": 2, "created": 8, "duplicate": 1, "rejected": 3 } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/{importId}/items": { "get": { "summary": "Listar ítems de una importación de geocercas", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Lista de forma paginada los ítems de una importación de geocercas, con opción de\nfiltrar por estado.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- Solo retorna ítems si la importación pertenece al cliente autenticado\n- `limit` por defecto 50, máximo 200\n", "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "ID del historial de importación (24 caracteres hex)", "example": "507f191e810c19729de860ea" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "number", "default": 1 }, "description": "Número de página (>= 1)" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "number", "default": 50, "maximum": 200 }, "description": "Cantidad de ítems por página (máximo 200)" }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" }, "description": "Filtrar por estado del ítem (ej: pending, created, duplicate, rejected). Usar `all` u omitir para no filtrar" } ], "responses": { "200": { "description": "Ítems de la importación obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "originalName": { "type": "string" }, "status": { "type": "string" }, "rejectedReason": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "geometryHash": { "type": "string", "nullable": true }, "partIndex": { "type": "number" }, "partsTotal": { "type": "number" }, "originalVertices": { "type": "number" }, "simplifiedVertices": { "type": "number" }, "areaDeltaPct": { "type": "number" }, "maxBoundaryErrorMeters": { "type": "number" }, "flespiId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 50 }, "total": { "type": "number", "example": 14 }, "pages": { "type": "number", "example": 1 } } } } } } } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/geofences/imports/{importId}/rejected.csv": { "get": { "summary": "Descargar CSV de geocercas rechazadas de una importación", "tags": [ "Tracking - Geocercas" ], "security": [ { "bearerAuth": [] } ], "description": "Genera y descarga un archivo CSV con los ítems no importados de una importación\n(rechazados, duplicados y fallidos), incluyendo el motivo y el detalle sanitizado.\n\n**Permisos requeridos:** `access_locations`\n\n**Comportamiento:**\n- Solo procesa la importación si pertenece al cliente autenticado\n- El archivo se devuelve como descarga (`Content-Disposition: attachment`)\n- Columnas: name, originalName, status, reason, detail, partIndex, partsTotal, geometryHash\n", "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "ID del historial de importación (24 caracteres hex)", "example": "507f191e810c19729de860ea" } ], "responses": { "200": { "description": "Archivo CSV generado exitosamente", "content": { "text/csv": { "schema": { "type": "string", "description": "Contenido del archivo CSV de ítems rechazados" } } } }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "404": { "description": "Recurso no encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Recurso no encontrado" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/alerts/client/{clientId}": { "get": { "summary": "Obtener las alertas de un cliente", "tags": [ "Alertas - Alertas" ], "security": [ { "bearerAuth": [] } ], "description": "Devuelve las alertas asociadas a un cliente específico (campos base; sin campos\nespecíficos por tipo). Requiere el permiso `access_alerts`.\n", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID del cliente" } ], "responses": { "200": { "description": "Lista de alertas del cliente (campos base)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Campos comunes a todos los tipos de alerta. El payload de creación/edición depende del alertTriggerId.", "properties": { "alertTriggerId": { "type": "string", "description": "ID del disparador de alerta (determina el tipo y los campos requeridos)" }, "name": { "type": "string", "description": "Nombre de la alerta" }, "assets": { "type": "array", "items": { "type": "string" }, "description": "IDs de activos asociados" }, "users": { "type": "array", "items": { "type": "string" }, "description": "IDs de usuarios. Si typeNotification.app o typeNotification.browser son true, es obligatorio y debe tener al menos un elemento." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Emails para notificaciones. Si typeNotification.email es true, es obligatorio y debe tener al menos un elemento." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos para notificaciones (whatsapp). Si typeNotification.whatsapp es true, es obligatorio y debe tener al menos un elemento." }, "typeNotification": { "type": "object", "description": "Canales de notificación. Si un canal está en true, el array asociado no puede estar vacío:\n- email true requiere al menos un email en `emails`\n- whatsapp true requiere al menos un teléfono en `phones`\n- app o browser true requieren al menos un usuario en `users`\n", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "app": { "type": "boolean" }, "browser": { "type": "boolean" } }, "required": [ "email", "whatsapp", "app", "browser" ] }, "state": { "type": "boolean", "description": "Estado de la alerta (true activa, false inactiva)" }, "description": { "type": "string", "description": "Descripción opcional" } }, "required": [ "alertTriggerId", "name", "assets", "users" ] }, { "type": "object", "description": "Elemento de listado de alertas (GET todas). Solo campos base más identificadores y timestamps.\nEn la respuesta, las refs vienen pobladas: alertTriggerId como { _id, name, label }; assets como array de { _id, name, plate }; users como array de { _id, name, email }; clientId como { _id, name }.\n", "properties": { "_id": { "type": "string", "description": "ID de la alerta" }, "clientId": { "type": "string", "description": "ID del cliente" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "clientId" ] } ] } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/business-time/clock": { "get": { "summary": "Obtener el reloj de negocio del servidor", "description": "Devuelve la hora actual del servidor, la zona horaria de negocio (America/Santiago)\ny el fin del día de negocio (23:59:59.999 del día actual en esa zona).\n\n**Ruta pública:** no requiere autenticación JWT (`security: []`). Útil para que el\nfrontend sincronice su reloj y calcule límites de rango sin depender del reloj local.\n", "tags": [ "Público - Business Time" ], "security": [], "responses": { "200": { "description": "Reloj de negocio obtenido exitosamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "serverTime": { "type": "string", "format": "date-time", "description": "Hora actual del servidor en formato ISO 8601 (UTC)", "example": "2026-07-19T14:32:05.123Z" }, "businessTimezone": { "type": "string", "description": "Zona horaria de negocio", "example": "America/Santiago" }, "businessDayEnd": { "type": "string", "format": "date-time", "description": "Fin del día de negocio (23:59:59.999 zona de negocio) en formato ISO 8601 (UTC)", "example": "2026-07-20T02:59:59.999Z" } } } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/fuel-prices": { "get": { "summary": "Precios de combustible vigentes", "description": "Devuelve el precio vigente por tipo de combustible para la empresa del\nusuario: la vigencia propia de la empresa si existe, si no la global\n(feed CNE / sistema). Los tipos sin ninguna vigencia se omiten.\n", "tags": [ "Precios de combustible" ], "responses": { "200": { "description": "Precios vigentes obtenidos exitosamente", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "fuelType": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ] }, "pricePerLiter": { "type": "number", "description": "CLP por litro, bruto (IVA incluido)", "example": 935 }, "validFrom": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "cne", "manual" ] }, "scope": { "type": "string", "enum": [ "client", "global" ], "description": "client = vigencia propia de la empresa; global = sistema" } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear vigencia manual de precio", "description": "Alta manual de una vigencia de precio de combustible para la empresa\ndel usuario. La colección es append-only: una corrección es una\nvigencia nueva (se permite backdatear `validFrom`). Las vigencias\nglobales las escribe solo el sistema.\n", "tags": [ "Precios de combustible" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fuelType", "pricePerLiter" ], "properties": { "fuelType": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ] }, "pricePerLiter": { "type": "number", "description": "CLP por litro, bruto (IVA incluido)", "example": 950 }, "validFrom": { "type": "string", "format": "date-time", "description": "Inicio de vigencia (default ahora)" } } } } } }, "responses": { "201": { "description": "Vigencia creada exitosamente" }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/fuel-prices/history": { "get": { "summary": "Historial de vigencias de precios", "description": "Historial de vigencias visibles para la empresa (propias + globales),\nmás reciente primero. Filtrable por tipo de combustible.\n", "tags": [ "Precios de combustible" ], "parameters": [ { "in": "query", "name": "fuelType", "required": false, "schema": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ] } } ], "responses": { "200": { "description": "Historial obtenido exitosamente" }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/fuel-tariffs": { "get": { "summary": "Tarifas de combustible custom de la empresa", "description": "Variantes de combustible definidas por el cliente (FuelTariff): nombre\npropio sobre un tipo base, con precio sincronizado a las vigencias del\ntipo (`priceMode: cne`) o precio manual plano (`priceMode: manual`).\nLas 4 tarifas default no se listan acá: se derivan del enum de tipos.\n", "tags": [ "Tarifas de combustible" ], "responses": { "200": { "description": "Tarifas obtenidas exitosamente", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "example": "Convenio Copec" }, "fuelType": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ] }, "priceMode": { "type": "string", "enum": [ "cne", "manual" ], "description": "cne = sigue las vigencias del tipo base; manual = precio plano propio" }, "pricePerLiter": { "type": "number", "description": "CLP por litro, bruto. Rige solo en modo manual; puede persistir tras volver a sincronización CNE (se recuerda al reactivar el modo manual)", "example": 990 } } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "post": { "summary": "Crear tarifa de combustible custom", "description": "Alta de una FuelTariff: variante con nombre propio de un tipo base. El\nnombre es único por empresa (sin distinguir mayúsculas ni acentos). En\nmodo manual el precio por litro es obligatorio. El precio manual es\nplano (sin vigencias): cambiarlo re-valoriza el histórico de costos.\n", "tags": [ "Tarifas de combustible" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "fuelType", "priceMode" ], "properties": { "name": { "type": "string", "maxLength": 60, "example": "Convenio Copec" }, "fuelType": { "type": "string", "enum": [ "gasoline_93", "gasoline_95", "gasoline_97", "diesel" ] }, "priceMode": { "type": "string", "enum": [ "cne", "manual" ] }, "pricePerLiter": { "type": "number", "description": "CLP por litro, bruto. Obligatorio en modo manual", "example": 990 } } } } } }, "responses": { "201": { "description": "Tarifa creada exitosamente" }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "409": { "description": "Ya existe una tarifa con ese nombre" }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } }, "/api/fuel-tariffs/{fuelTariffId}": { "patch": { "summary": "Editar tarifa de combustible custom", "description": "Edita nombre y/o precio de una tarifa. El tipo base es inmutable. Cambiar\nel precio manual re-valoriza el histórico de costos e invalida el cache\nde exports de reportes de viajes.\n", "tags": [ "Tarifas de combustible" ], "parameters": [ { "in": "path", "name": "fuelTariffId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "priceMode": { "type": "string", "enum": [ "cne", "manual" ] }, "pricePerLiter": { "type": "number" } } } } } }, "responses": { "200": { "description": "Tarifa editada exitosamente" }, "400": { "description": "Error de validación", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string", "example": "El email es requerido" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error de validación" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } ] } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Tarifa no encontrada" }, "409": { "description": "Ya existe una tarifa con ese nombre" }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } }, "delete": { "summary": "Borrar tarifa de combustible custom", "description": "Borra la tarifa y desvincula en bloque sus activos: caen a la tarifa\ndefault de su tipo base conservando rendimiento y precio propio. No\nexiste «sin asignar».\n", "tags": [ "Tarifas de combustible" ], "parameters": [ { "in": "path", "name": "fuelTariffId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tarifa borrada; devuelve la cantidad de activos desvinculados", "content": { "application/json": { "schema": { "type": "object", "properties": { "unlinkedAssets": { "type": "number", "example": 12 } } } } } }, "401": { "description": "No autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Token inválido o expirado" } } } } } }, "403": { "description": "Sin permisos", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "No tiene permisos para realizar esta acción" } } } } } }, "404": { "description": "Tarifa no encontrada" }, "500": { "description": "Error interno del servidor", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Error interno del servidor" } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Error interno del servidor" } } } ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token de sesión Better Auth o API token (`atk_...`) en el header `Authorization: Bearer `. Los JWT legacy ya no son válidos." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Cookie de sesión Better Auth emitida al iniciar sesión en el frontend web. En producción el nombre lleva prefijo `__Secure-`." } } }, "tags": [ { "name": "Auth - Autenticación", "description": "Operaciones de autenticación" }, { "name": "Usuarios - Usuarios", "description": "Operaciones relacionadas con usuarios" }, { "name": "Usuarios - Roles", "description": "Operaciones relacionadas con roles" }, { "name": "Usuarios - Permisos", "description": "Operaciones relacionadas con permisos" }, { "name": "Activos - Assets", "description": "Operaciones relacionadas con activos" }, { "name": "Activos - Tipos", "description": "Operaciones relacionadas con tipos de activos" }, { "name": "Activos - Grupos", "description": "Operaciones relacionadas con grupos de activos" }, { "name": "Activos - Vehículos", "description": "Operaciones relacionadas con tipos de vehículos" }, { "name": "Tracking - Trackers", "description": "Operaciones relacionadas con trackers" }, { "name": "Tracking - Viajes", "description": "Operaciones relacionadas con viajes y paradas" }, { "name": "Tracking - Geocercas", "description": "Operaciones relacionadas con geocercas" }, { "name": "Alertas - Alertas", "description": "Operaciones relacionadas con alertas" }, { "name": "Alertas - Disparadores", "description": "Operaciones relacionadas con disparadores de alertas" }, { "name": "Alertas - Notificaciones", "description": "Operaciones relacionadas con notificaciones" }, { "name": "Clientes - Restricciones", "description": "Operaciones relacionadas con restricciones" }, { "name": "Integraciones - Flespi", "description": "Operaciones relacionadas con Flespi" }, { "name": "Otros - Conductores", "description": "Operaciones relacionadas con conductores" }, { "name": "Otros - Capas", "description": "Operaciones relacionadas con capas" }, { "name": "User Tracker Access", "description": "Operaciones de acceso personalizado a trackers por usuario" }, { "name": "Reportes - Historial de Posiciones", "description": "Estadísticas y detalle de posiciones GPS por activo" }, { "name": "Reportes - Excesos de Velocidad", "description": "Reportes de excesos de velocidad por tracker" }, { "name": "Reportes - Ralentí", "description": "Reportes de ralentí (motor encendido sin movimiento) por tracker" }, { "name": "Reportes - Horas de Trabajo", "description": "Reportes de horas de trabajo (conducción + paradas dentro de horario laboral) por tracker" }, { "name": "Reportes - Última Actividad", "description": "Reporte de estado de comunicación y última posición de activos" }, { "name": "Reportes - Reportes Programados", "description": "Gestión de reportes programados (CRUD)" }, { "name": "Device Health", "description": "Operaciones de salud de dispositivos del cliente" }, { "name": "Activity Log", "description": "Registro de actividad del cliente" }, { "name": "Work - Importaciones", "description": "Operaciones de importación de datos" }, { "name": "Work - Plantillas", "description": "Operaciones de plantillas de importación" }, { "name": "Cargo - Transportistas", "description": "Gestión de transportistas" }, { "name": "Cargo - Pedidos", "description": "Gestión de pedidos de carga" }, { "name": "Cargo - Monitoreo", "description": "Monitoreo en vivo de carga y transporte" }, { "name": "Integraciones - Navixy", "description": "Integración con plataforma Navixy" }, { "name": "Mantenimiento - Dashboard", "description": "Dashboard y métricas generales de mantenimiento" }, { "name": "Mantenimiento - Proveedores", "description": "Gestión de proveedores de servicio" }, { "name": "Mantenimiento - Estado", "description": "Estado de mantenimiento de activos" }, { "name": "Mantenimiento - Perfiles", "description": "Perfiles de mantenimiento por activo" }, { "name": "Mantenimiento - Fallas", "description": "Gestión de fallas activas" }, { "name": "Mantenimiento - DVIR", "description": "Driver Vehicle Inspection Reports" }, { "name": "Mantenimiento - Defectos", "description": "Gestión de defectos detectados" }, { "name": "Mantenimiento - Programaciones", "description": "Programación de mantenimientos preventivos" }, { "name": "Mantenimiento - Próximos", "description": "Ítems de mantenimiento próximos" }, { "name": "Mantenimiento - Órdenes de Trabajo", "description": "Gestión de órdenes de trabajo" }, { "name": "Mantenimiento - Registros de Servicio", "description": "Registros históricos de servicios realizados" }, { "name": "Mantenimiento - Problemas", "description": "Gestión de problemas de mantenimiento" }, { "name": "Mantenimiento - Tareas de Servicio", "description": "Tareas específicas dentro de órdenes de trabajo" }, { "name": "Mantenimiento - Inventario", "description": "Gestión de partes, ubicaciones y stock" }, { "name": "Mantenimiento - Costos", "description": "Gestión y agregación de costos de mantenimiento" }, { "name": "Mantenimiento - Importación de Facturas", "description": "Importación de facturas con extracción por IA" }, { "name": "Trabajo - Tareas", "description": "Gestión de tareas, tareas recurrentes, rutas y operaciones en lote" }, { "name": "Trabajo - Empleados", "description": "Gestión de empleados, departamentos y sus catálogos (tags, trackers)" }, { "name": "Otros - Lugares", "description": "Gestión de lugares (places) del cliente" }, { "name": "Cargo - Activos", "description": "Disponibilidad de activos de carga" }, { "name": "Cargo - Ubicaciones", "description": "Gestión de ubicaciones de carga" }, { "name": "Cargo - Rendimiento", "description": "Métricas de rendimiento de pedidos de carga" }, { "name": "Reportes - Check-ins", "description": "Reporte de check-ins de tareas" }, { "name": "Reportes - Utilización", "description": "Reporte de utilización de activos" }, { "name": "Reportes - Visitas por Geocercas", "description": "Reporte de visitas a geocercas" }, { "name": "Reportes - Visitas por Trackers", "description": "Reporte de visitas por tracker/activo" }, { "name": "Reportes - Progreso de Geozonas", "description": "Reporte de progreso de cobertura de geozonas (agricultura)" }, { "name": "Reportes - Temperatura", "description": "Reporte de temperatura por activo" }, { "name": "Reportes - Exportación", "description": "Exportación de reportes a archivo" }, { "name": "Público - Business Time", "description": "Reloj de servidor (endpoint público, sin autenticación)" }, { "name": "Formularios", "description": "Definiciones y envíos de formularios de la app" }, { "name": "Sistema", "description": "Endpoints de salud del servicio (liveness/readiness), sin autenticación" } ] }