{ "openapi": "3.0.3", "info": { "title": "API de silencios de alertas (omisiones)", "version": "1.0.0", "description": "Silencia una alerta para un vehículo durante N horas: mientras dure, el motor de omisiones NO la notifica a ese vehículo.\n\n- Las fechas van en **UTC** (ISO 8601). El cliente sólo manda la **duración** en `horas` (0 < horas ≤ 720).\n- Silenciar la **misma** alerta para el **mismo** vehículo otra vez **reinicia** la duración (no crea un duplicado).\n- Un silencio vence solo; también se puede cancelar antes (por su `_id` o por el par alerta + vehículo).\n- **Acceso:** sólo desde aplicaciones web servidas en `https://*.quro.com.mx` (el navegador manda la cabecera `Origin`; sin un `Origin` permitido la respuesta es **403**). `/health`, `/docs` y `/openapi.json` son públicos.", "contact": { "name": "Plataforma Quro" } }, "servers": [ { "url": "https://apiomi.silencio.quro.com.mx", "description": "Producción (contenedor api-omisiones-silenciado)" } ], "tags": [ { "name": "Silencios", "description": "Crear, cancelar y consultar silencios." }, { "name": "Operación", "description": "Salud del servicio." } ], "paths": { "/api/alertas/silenciar": { "post": { "tags": [ "Silencios" ], "operationId": "silenciar", "summary": "Silenciar una alerta para un vehículo", "description": "Crea el silencio, o REINICIA su duración si ya había uno activo para ese par alerta + vehículo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "alerta_id", "vehiculo_id", "uid_empresa", "horas" ], "properties": { "alerta_id": { "type": "string", "description": "ObjectId de la alerta (configuración) a silenciar." }, "vehiculo_id": { "type": "string", "description": "ObjectId del vehículo o su UID_Externo (el que usa el panel)." }, "uid_empresa": { "type": "string", "description": "ObjectId (24 hex) de la empresa dueña del vehículo en la base de omisiones. No es el UUID de la empresa en GPS." }, "horas": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 720, "description": "Duración en horas (máximo 720)." }, "motivo": { "type": "string", "maxLength": 200, "description": "Opcional, hasta 200 caracteres." }, "creado_por": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } } } } }, "example": { "alerta_id": "69eb9d55a1b2c3d4e5f60718", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" } } } } }, "responses": { "201": { "description": "Silencio creado o renovado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "silencio": { "$ref": "#/components/schemas/Silencio" } } }, "example": { "ok": true, "silencio": { "_id": "670d5f1a2b3c4d5e6f708192", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "alerta_id": "69eb9d55a1b2c3d4e5f60718", "alerta_nombre": "DETENCIÓN DE UNIDAD", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "vehiculo_alias": "TR-685", "vehiculo_uid_externo": null, "silenciada_desde": "2026-10-14T20:00:00.000Z", "silenciada_hasta": "2026-10-15T08:00:00.000Z", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" }, "creado_en": "2026-10-14T20:00:00.000Z", "cancelado_por": null, "cancelado_en": null, "expirado_en": null, "status": 1, "restante_segundos": 43200 } } } } }, "400": { "description": "Faltan campos o valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "horas excede el máximo permitido (720)" } } } }, "403": { "$ref": "#/components/responses/OrigenNoPermitido" }, "404": { "description": "El vehículo no existe (por UID_Externo).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Vehículo no encontrado por UID_Externo: b1c2d3e4-…" } } } }, "500": { "$ref": "#/components/responses/ErrorInterno" } } }, "delete": { "tags": [ "Silencios" ], "operationId": "cancelarPorPar", "summary": "Cancelar el silencio activo de un par alerta + vehículo", "description": "Para cuando la pantalla tiene los dos IDs pero no el `_id` del silencio.", "parameters": [ { "name": "alerta_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "vehiculo_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "ObjectId o UID_Externo." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelado_por": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } } } } } } } }, "responses": { "200": { "description": "Silencio cancelado (status 0).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "silencio": { "$ref": "#/components/schemas/Silencio" } } }, "example": { "ok": true, "silencio": { "_id": "670d5f1a2b3c4d5e6f708192", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "alerta_id": "69eb9d55a1b2c3d4e5f60718", "alerta_nombre": "DETENCIÓN DE UNIDAD", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "vehiculo_alias": "TR-685", "vehiculo_uid_externo": null, "silenciada_desde": "2026-10-14T20:00:00.000Z", "silenciada_hasta": "2026-10-15T08:00:00.000Z", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" }, "creado_en": "2026-10-14T20:00:00.000Z", "cancelado_por": null, "cancelado_en": "2026-10-14T22:00:00.000Z", "expirado_en": null, "status": 0, "restante_segundos": 0 } } } } }, "400": { "description": "Faltan los query params.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "alerta_id y vehiculo_id son requeridos como query params" } } } }, "403": { "$ref": "#/components/responses/OrigenNoPermitido" }, "404": { "description": "No hay silencio activo para ese par.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "No hay silencio activo para esa alerta/vehículo" } } } }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/api/alertas/silenciar/{id}": { "delete": { "tags": [ "Silencios" ], "operationId": "cancelar", "summary": "Cancelar un silencio por su _id", "description": "Idempotente: cancelar uno ya cancelado devuelve el mismo silencio.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`_id` del silencio." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelado_por": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } } } } } } } }, "responses": { "200": { "description": "Silencio cancelado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "silencio": { "$ref": "#/components/schemas/Silencio" } } }, "example": { "ok": true, "silencio": { "_id": "670d5f1a2b3c4d5e6f708192", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "alerta_id": "69eb9d55a1b2c3d4e5f60718", "alerta_nombre": "DETENCIÓN DE UNIDAD", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "vehiculo_alias": "TR-685", "vehiculo_uid_externo": null, "silenciada_desde": "2026-10-14T20:00:00.000Z", "silenciada_hasta": "2026-10-15T08:00:00.000Z", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" }, "creado_en": "2026-10-14T20:00:00.000Z", "cancelado_por": null, "cancelado_en": "2026-10-14T22:00:00.000Z", "expirado_en": null, "status": 0, "restante_segundos": 0 } } } } }, "400": { "description": "id inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "ObjectId inválido: abc" } } } }, "403": { "$ref": "#/components/responses/OrigenNoPermitido" }, "404": { "description": "No existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Silencio no encontrado" } } } }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/api/alertas/silenciadas": { "get": { "tags": [ "Silencios" ], "operationId": "listar", "summary": "Listar silencios (paginado)", "description": "Se requiere AL MENOS uno de `uid_empresa` o `vehiculo_id`.", "parameters": [ { "name": "uid_empresa", "in": "query", "schema": { "type": "string" }, "description": "ObjectId (24 hex) de la empresa en la base de omisiones." }, { "name": "vehiculo_id", "in": "query", "schema": { "type": "string" }, "description": "ObjectId o UID_Externo." }, { "name": "alerta_id", "in": "query", "schema": { "type": "string" } }, { "name": "activas", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "`true` = sólo los activos." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 50 } } ], "responses": { "200": { "description": "Página de silencios.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Silencio" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "example": { "ok": true, "items": [ { "_id": "670d5f1a2b3c4d5e6f708192", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "alerta_id": "69eb9d55a1b2c3d4e5f60718", "alerta_nombre": "DETENCIÓN DE UNIDAD", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "vehiculo_alias": "TR-685", "vehiculo_uid_externo": null, "silenciada_desde": "2026-10-14T20:00:00.000Z", "silenciada_hasta": "2026-10-15T08:00:00.000Z", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" }, "creado_en": "2026-10-14T20:00:00.000Z", "cancelado_por": null, "cancelado_en": null, "expirado_en": null, "status": 1, "restante_segundos": 43200 } ], "total": 1, "page": 1, "limit": 50 } } } }, "400": { "description": "Falta el alcance, o un id no es un ObjectId válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "se requiere uid_empresa o vehiculo_id (al menos uno)" } } } }, "403": { "$ref": "#/components/responses/OrigenNoPermitido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/api/alertas/silenciadas/vehiculo/{vehiculo_id}": { "get": { "tags": [ "Silencios" ], "operationId": "listarPorVehiculo", "summary": "Silencios ACTIVOS de un vehículo", "parameters": [ { "name": "vehiculo_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ObjectId o UID_Externo." } ], "responses": { "200": { "description": "Silencios activos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Silencio" } } } }, "example": { "ok": true, "items": [ { "_id": "670d5f1a2b3c4d5e6f708192", "uid_empresa": "66f1a2b3c4d5e6f708192a3b", "alerta_id": "69eb9d55a1b2c3d4e5f60718", "alerta_nombre": "DETENCIÓN DE UNIDAD", "vehiculo_id": "69c56400a1b2c3d4e5f60006", "vehiculo_alias": "TR-685", "vehiculo_uid_externo": null, "silenciada_desde": "2026-10-14T20:00:00.000Z", "silenciada_hasta": "2026-10-15T08:00:00.000Z", "horas": 12, "motivo": "Unidad en taller", "creado_por": { "uid": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a", "nombre": "Ana López", "email": "ana.lopez@empresa.com" }, "creado_en": "2026-10-14T20:00:00.000Z", "cancelado_por": null, "cancelado_en": null, "expirado_en": null, "status": 1, "restante_segundos": 43200 } ] } } } }, "403": { "$ref": "#/components/responses/OrigenNoPermitido" }, "404": { "description": "El vehículo no existe (por UID_Externo).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Vehículo no encontrado por UID_Externo: b1c2d3e4-…" } } } }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/health": { "get": { "tags": [ "Operación" ], "operationId": "salud", "summary": "Salud del servicio y de su base", "responses": { "200": { "description": "Servicio y Mongo en línea.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "ok", "service": "silenciado-api", "mongo": "online" } } } }, "503": { "description": "Mongo no responde.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "error", "service": "silenciado-api", "mongo": "offline", "error": "…" } } } } } } } }, "components": { "schemas": { "Silencio": { "type": "object", "description": "Un silencio: la alerta `alerta_id` NO se notifica para el vehículo `vehiculo_id` hasta `silenciada_hasta`.", "properties": { "_id": { "type": "string", "description": "Identificador del silencio (ObjectId).", "example": "670d5f1a2b3c4d5e6f708192" }, "uid_empresa": { "type": "string", "description": "ObjectId de la empresa en la base de omisiones (24 hex).", "example": "66f1a2b3c4d5e6f708192a3b" }, "alerta_id": { "type": "string", "description": "ObjectId de la configuración de alerta.", "example": "69eb9d55a1b2c3d4e5f60718" }, "alerta_nombre": { "type": "string", "nullable": true, "example": "DETENCIÓN DE UNIDAD" }, "vehiculo_id": { "type": "string", "description": "ObjectId del vehículo.", "example": "69c56400a1b2c3d4e5f60006" }, "vehiculo_alias": { "type": "string", "nullable": true, "example": "TR-685" }, "vehiculo_uid_externo": { "type": "string", "nullable": true, "example": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e" }, "silenciada_desde": { "type": "string", "format": "date-time", "description": "UTC.", "example": "2026-10-14T20:00:00.000Z" }, "silenciada_hasta": { "type": "string", "format": "date-time", "description": "UTC. Al pasar esta hora el silencio expira solo.", "example": "2026-10-15T08:00:00.000Z" }, "horas": { "type": "number", "example": 12 }, "motivo": { "type": "string", "nullable": true, "example": "Unidad en taller" }, "creado_por": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } }, "nullable": true }, "creado_en": { "type": "string", "format": "date-time", "nullable": true }, "cancelado_por": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } }, "nullable": true }, "cancelado_en": { "type": "string", "format": "date-time", "nullable": true }, "expirado_en": { "type": "string", "format": "date-time", "nullable": true, "description": "Cuándo se detectó que venció." }, "status": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = activo; 0 = cancelado o expirado.", "example": 1 }, "restante_segundos": { "type": "integer", "description": "Segundos que le quedan (0 si no está activo).", "example": 43200 } } }, "Quien": { "type": "object", "description": "Quién hizo la acción (auditoría). Opcional. También se acepta un texto plano, o los campos planos `_uid`, `_nombre` y `_email`.", "properties": { "uid": { "type": "string", "example": "0d8f1c2e-6b8a-4c7e-9a51-2f3e4d5c6b7a" }, "nombre": { "type": "string", "example": "Ana López" }, "email": { "type": "string", "format": "email", "example": "ana.lopez@empresa.com" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } } }, "responses": { "OrigenNoPermitido": { "description": "La petición no viene de un sitio `https://*.quro.com.mx` (cabecera `Origin`). Lo contesta el nginx, sin cuerpo JSON." }, "ErrorInterno": { "description": "Error inesperado del servicio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Error desconocido" } } } } } } }