{ "openapi": "3.1.0", "info": { "title": "WORKS SERVICES — API de integración Pegasus v1 (MSS / financieras)", "version": "1.1.0", "description": "POST /commands recibe IMEI y acción. La llave debe tener control habilitado y el IMEI debe pertenecer, de forma única y recíproca, a un vehículo de una agencia autorizada. La polaridad sale del modelo de GPS o de una certificación opcional del mismo vehículo. Consultas MSS conservadas. HTTP 202 no acredita efecto externo. Manual: PEGASUS_INTEGRATION_API.md." }, "servers": [ { "url": "https://inventario-works-service.pages.dev/api/integrations/pegasus/v1", "description": "API pública a través del proxy; capacidades según clave y ambiente" } ], "security": [ { "MssApiKey": [] } ], "paths": { "/vehicles": { "get": { "operationId": "listMssVehicles", "summary": "Consultar sólo vehículos del grupo asignado a la API key", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "Número de página" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Tamaño máximo 100" }, { "name": "plate", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 }, "description": "Placa exacta, sin distinguir guiones/espacios/mayúsculas" }, { "name": "imei", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{15}$" }, "description": "IMEI exacto" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Versión obtenida en la página 1. 409 si cambió; reiniciar paginación." } ], "responses": { "200": { "description": "Copia autorizada de Pegasus; revisar meta.stale. Sin datos de Inventario.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleList" } } } }, "400": { "description": "Filtros inválidos/no permitidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "API key inválida, ausente, vencida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Vehículo ausente/ajeno o API deshabilitada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "La copia cambió", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Cuota excedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Segundos hasta el próximo minuto.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } } }, "503": { "description": "No hay copia vigente de Pegasus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "head": { "operationId": "headMssVehicles", "summary": "Misma autorización y cuota de GET, sin cuerpo", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "description": "Número de página" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Tamaño máximo 100" }, { "name": "plate", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 }, "description": "Placa exacta, sin distinguir guiones/espacios/mayúsculas" }, { "name": "imei", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{15}$" }, "description": "IMEI exacto" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Versión obtenida en la página 1. 409 si cambió; reiniciar paginación." } ], "responses": { "200": { "description": "Consulta autorizada" }, "400": { "description": "Filtros inválidos/no permitidos" }, "401": { "description": "API key inválida, ausente, vencida o revocada" }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes" }, "404": { "description": "Vehículo ausente/ajeno o API deshabilitada" }, "409": { "description": "La copia cambió" }, "429": { "description": "Cuota excedida" }, "503": { "description": "No hay copia vigente de Pegasus" } } } }, "/vehicles/{id}": { "get": { "operationId": "getMssVehicle", "summary": "Consultar sólo vehículos del grupo asignado a la API key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,120}$" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Versión obtenida en la página 1. 409 si cambió; reiniciar paginación." } ], "responses": { "200": { "description": "Copia autorizada de Pegasus; revisar meta.stale. Sin datos de Inventario.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDetail" } } } }, "400": { "description": "Filtros inválidos/no permitidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "API key inválida, ausente, vencida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Vehículo ausente/ajeno o API deshabilitada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "La copia cambió", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Cuota excedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Segundos hasta el próximo minuto.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } } }, "503": { "description": "No hay copia vigente de Pegasus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "head": { "operationId": "headMssVehicle", "summary": "Misma autorización y cuota de GET, sin cuerpo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,120}$" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Versión obtenida en la página 1. 409 si cambió; reiniciar paginación." } ], "responses": { "200": { "description": "Consulta autorizada" }, "400": { "description": "Filtros inválidos/no permitidos" }, "401": { "description": "API key inválida, ausente, vencida o revocada" }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes" }, "404": { "description": "Vehículo ausente/ajeno o API deshabilitada" }, "409": { "description": "La copia cambió" }, "429": { "description": "Cuota excedida" }, "503": { "description": "No hay copia vigente de Pegasus" } } } }, "/location": { "get": { "operationId": "getMssLastLocation", "summary": "Última posición por placa o IMEI dentro del grupo autorizado", "description": "Enviar exactamente plate o imei. Si la última localización es inválida consulta el historial, ordenado por fecha GPS descendente, para la misma identidad vehículo/IMEI. Búsqueda limitada a 15 meses calendario y datos conservados por Pegasus; meta.history contiene el intervalo exacto. locationOrigin distingue latest/history; una posición histórica no implica ubicación actual. Sin GPS asignado o sin posición válida en el intervalo: location=null. Proveedor no verificable/fallido: 503.", "parameters": [ { "name": "plate", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z0-9 -]+$" } }, { "name": "imei", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{15}$" } } ], "responses": { "200": { "description": "Última posición válida del reporte reciente o historial acotado; revisar meta.locationOrigin, meta.history, eventTime y stale. location=null solo por ausencia comprobada.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" } } } }, "400": { "description": "Filtros inválidos/no permitidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "API key inválida, ausente, vencida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Vehículo ausente/ajeno o API deshabilitada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Placa o asociación GPS ambigua", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Cuota excedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Segundos hasta el próximo minuto.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } } }, "503": { "description": "Proveedor no disponible, cartera incompleta, identidad no verificable o configuración cambiada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/monthly-report": { "get": { "operationId": "getMssMonthlyReport", "summary": "Instalaciones y bajas del corte mensual revisado de MSS", "parameters": [ { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])$" } } ], "responses": { "200": { "description": "Corte histórico revisado. physicalConfirmed consulta la bitácora común actual de servicios e Inventario, sin duplicados. Una propuesta no confirma retiro físico.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReport" } } } }, "400": { "description": "Filtros inválidos/no permitidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "API key inválida, ausente, vencida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Alcance/cartera/cliente/organización no vigentes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Sin corte revisado para mes y alcance, o API deshabilitada. No equivale a cero retiros.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Cuota excedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Segundos hasta el próximo minuto.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } } }, "503": { "description": "Proveedor no disponible, cartera incompleta, identidad no verificable o configuración cambiada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/vehicles": { "post": { "operationId": "receiveFinancialVehicle", "summary": "Recibir un vehículo de la financiera", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{7,119}$" }, "description": "ID estable de evento, reutilizar con mismos datos ante respuesta perdida; otros datos con mismo ID: 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialVehicleInput" } } } }, "responses": { "202": { "description": "Estado persistido, sin datos financieros ni secretos. 202 no confirma efecto externo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/commands": { "post": { "operationId": "requestRelayControl", "summary": "Solicitar IMMOBILIZE o ENABLE por IMEI", "description": "El cliente envía el IMEI y la acción. No declara vehículo, comando, salida ni polaridad. El IMEI debe estar asociado a un vehículo de una agencia autorizada para la llave. Un IMEI de otra agencia recibe el mismo 403 que un IMEI desconocido. La ventana de envío es de 120 segundos.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{7,119}$" }, "description": "ID estable de evento, reutilizar con mismos datos ante respuesta perdida; otros datos con mismo ID: 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlInput" } } } }, "responses": { "202": { "description": "Estado persistido, sin datos financieros ni secretos. 202 no confirma efecto externo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/operations/{id}": { "get": { "operationId": "getPegasusOperation", "summary": "Consultar una operación de la misma clave y su historial", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Estado persistido, sin datos financieros ni secretos. 202 no confirma efecto externo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/operations/{id}/reconcile": { "post": { "operationId": "reconcilePegasusOperation", "summary": "Adelantar conciliación por lectura, sin reenviar escrituras", "description": "Sin cuerpo ni filtros. Solo SENT/UNKNOWN se programan. No cancela ni libera bloqueos manualmente.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Estado persistido, sin datos financieros ni secretos. 202 no confirma efecto externo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error de formato, autenticación, autorización, alcance, idempotencia, cuota o disponibilidad. Ver manual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "MssApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Credencial privada de backend vinculada al alcance en servidor; cuota 60/minuto." } }, "schemas": { "Vehicle": { "type": "object", "additionalProperties": false, "required": [ "id", "imei", "plate", "make", "model", "year", "vin", "color", "fuelType", "installationDate", "installer", "support", "installationStartedAt", "installationCompletedAt", "customerName", "customerDocument", "customerPhone", "appraisalDate", "appraisalId", "vehicleType", "engineNumber", "engineDisplacement", "odometer", "purchaseOrigin", "transmission", "traction", "cabin", "loanType", "appraiser", "appraisalComments", "creditApproved", "installationAuthorized", "leaseApproved", "vehicleReceivedAt", "signatures", "orderReadyAt", "gpsInstalled", "monitoringVerified" ], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,120}$" }, "imei": { "type": [ "string", "null" ], "pattern": "^[0-9]{15}$" }, "plate": { "type": [ "string", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "year": { "type": [ "string", "null" ] }, "vin": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "fuelType": { "type": [ "string", "null" ] }, "installationDate": { "type": [ "string", "null" ], "format": "date" }, "installer": { "type": [ "string", "null" ] }, "support": { "type": [ "string", "null" ] }, "installationStartedAt": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "installationCompletedAt": { "type": [ "string", "null" ], "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "customerName": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "customerDocument": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "customerPhone": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "appraisalDate": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "appraisalId": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "vehicleType": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "engineNumber": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "engineDisplacement": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "odometer": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "purchaseOrigin": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "transmission": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "traction": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "cabin": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "loanType": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "appraiser": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "appraisalComments": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "creditApproved": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "installationAuthorized": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "leaseApproved": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "vehicleReceivedAt": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "signatures": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1." }, "orderReadyAt": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1. No se infiere instalación física o verificación de monitoreo." }, "gpsInstalled": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1. No se infiere instalación física o verificación de monitoreo." }, "monitoringVerified": { "type": "null", "description": "No disponible en la fuente verificada de Pegasus para v1. No se infiere instalación física o verificación de monitoreo." } } }, "SourceMeta": { "type": "object", "additionalProperties": false, "required": [ "source", "version", "observedAt", "lastAttemptAt", "stale", "refreshIntervalSeconds", "unavailableFields" ], "properties": { "source": { "type": "string", "const": "Pegasus" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "observedAt": { "type": "string", "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "stale": { "type": "boolean" }, "refreshIntervalSeconds": { "type": "integer", "const": 300 }, "unavailableFields": { "type": "array", "items": { "type": "string", "enum": [ "customerName", "customerDocument", "customerPhone", "appraisalDate", "appraisalId", "vehicleType", "engineNumber", "engineDisplacement", "odometer", "purchaseOrigin", "transmission", "traction", "cabin", "loanType", "appraiser", "appraisalComments", "creditApproved", "installationAuthorized", "leaseApproved", "vehicleReceivedAt", "signatures", "orderReadyAt", "gpsInstalled", "monitoringVerified" ] } } } }, "ListMeta": { "type": "object", "additionalProperties": false, "required": [ "source", "version", "observedAt", "lastAttemptAt", "stale", "refreshIntervalSeconds", "unavailableFields", "total", "page", "pageSize", "pages" ], "properties": { "source": { "type": "string", "const": "Pegasus" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "observedAt": { "type": "string", "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "stale": { "type": "boolean" }, "refreshIntervalSeconds": { "type": "integer", "const": 300 }, "unavailableFields": { "type": "array", "items": { "type": "string", "enum": [ "customerName", "customerDocument", "customerPhone", "appraisalDate", "appraisalId", "vehicleType", "engineNumber", "engineDisplacement", "odometer", "purchaseOrigin", "transmission", "traction", "cabin", "loanType", "appraiser", "appraisalComments", "creditApproved", "installationAuthorized", "leaseApproved", "vehicleReceivedAt", "signatures", "orderReadyAt", "gpsInstalled", "monitoringVerified" ] } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "pages": { "type": "integer", "minimum": 0 } } }, "Problem": { "type": "object", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "VehicleList": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "VehicleDetail": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "meta": { "$ref": "#/components/schemas/SourceMeta" } } }, "LocationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "plate", "imei", "location" ], "properties": { "id": { "type": "string" }, "plate": { "type": [ "string", "null" ] }, "imei": { "type": [ "string", "null" ] }, "location": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "latitude", "longitude", "eventTime", "receivedTime", "ageSeconds", "stale" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "eventTime": { "type": "string", "format": "date-time" }, "receivedTime": { "type": [ "string", "null" ], "format": "date-time" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "stale": { "type": "boolean" } } } } }, "meta": { "type": "object", "additionalProperties": false, "required": [ "source", "queriedAt", "status", "staleAfterSeconds", "locationOrigin", "history" ], "properties": { "source": { "const": "Pegasus" }, "queriedAt": { "type": "string", "format": "date-time" }, "status": { "enum": [ "available", "no_valid_position" ] }, "staleAfterSeconds": { "const": 300 }, "locationOrigin": { "enum": [ "latest", "history", null ] }, "history": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "from", "to", "lookbackMonths" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "lookbackMonths": { "const": 15 } } } } } } }, "MonthlyReport": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "scope", "month", "observedAt", "reviewReference", "evidenceSha256", "version", "source", "physicalConfirmed", "summary", "byAgency", "installations", "rows" ], "properties": { "schemaVersion": { "const": 1 }, "scope": { "type": "object", "additionalProperties": false, "required": [ "groupId" ], "properties": { "groupId": { "type": "string" } } }, "month": { "type": "string", "pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])$" }, "observedAt": { "type": "string" }, "reviewReference": { "type": "string" }, "evidenceSha256": { "type": "string" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source": { "const": "reviewed_pegasus_history" }, "physicalConfirmed": { "type": "integer", "minimum": 0 }, "summary": { "type": "object", "additionalProperties": false, "required": [ "inPegasus", "proposed", "additional", "reconstructedProposed", "auditedDeletions" ], "properties": { "inPegasus": { "type": "integer", "minimum": 0 }, "proposed": { "type": "integer", "minimum": 0 }, "additional": { "type": "integer", "minimum": 0 }, "reconstructedProposed": { "type": "integer", "minimum": 0 }, "auditedDeletions": { "type": "integer", "minimum": 0 } } }, "byAgency": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "inPegasus", "proposed", "additional", "reconstructedProposed", "segmentId", "agency" ], "properties": { "inPegasus": { "type": "integer", "minimum": 0 }, "proposed": { "type": "integer", "minimum": 0 }, "additional": { "type": "integer", "minimum": 0 }, "reconstructedProposed": { "type": "integer", "minimum": 0 }, "segmentId": { "type": "integer", "minimum": 0 }, "agency": { "type": "string" } } } }, "installations": { "type": "array", "maxItems": 20000, "items": { "type": "object", "additionalProperties": false, "required": [ "vehicleId", "segmentId", "agency", "plate", "vin", "imei", "activatedAt" ], "properties": { "vehicleId": { "type": "string" }, "segmentId": { "type": [ "integer", "null" ] }, "agency": { "type": "string" }, "plate": { "type": [ "string", "null" ] }, "vin": { "type": [ "string", "null" ] }, "imei": { "type": [ "string", "null" ] }, "activatedAt": { "type": [ "string", "null" ] } } } }, "rows": { "type": "array", "maxItems": 5000, "items": { "type": "object", "additionalProperties": false, "required": [ "vehicleId", "segmentId", "agency", "plate", "vin", "imei", "activatedAt", "status", "unlinkedAt", "deletedAt", "deletionLogId", "unlinkLogId", "currentVehicleIds", "currentImeiVehicleIds" ], "properties": { "vehicleId": { "type": "string" }, "segmentId": { "type": [ "integer", "null" ] }, "agency": { "type": "string" }, "plate": { "type": [ "string", "null" ] }, "vin": { "type": [ "string", "null" ] }, "imei": { "type": [ "string", "null" ] }, "activatedAt": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "proposed", "additional", "same_vehicle", "unidentified", "never_activated", "invalid_identity" ] }, "unlinkedAt": { "type": [ "string", "null" ] }, "deletedAt": { "type": "string" }, "deletionLogId": { "type": "string" }, "unlinkLogId": { "type": [ "string", "null" ] }, "currentVehicleIds": { "type": "array", "items": { "type": "string" } }, "currentImeiVehicleIds": { "type": "array", "items": { "type": "string" } } } } } } }, "FinancialVehicleInput": { "type": "object", "additionalProperties": false, "description": "Un registro, nueve campos obligatorios como claves, usando nombre técnico o alias Excel por campo, nunca ambos. El perfil fija valores requeridos además de agencia/contrato/placa. Máximo 16.000 bytes de cuerpo.", "properties": { "cliente": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 191, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "CLIENTE": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 191, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "telefono": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 40, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "TELÉFONO": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 40, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "agencia": { "type": "string", "minLength": 1, "maxLength": 191, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "AGENCIA": { "type": "string", "minLength": 1, "maxLength": 191, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "contratoVigente": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Código de contrato, como texto; conserva ceros iniciales. Nunca booleano." }, "CONTRATO VIGENTE": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Código de contrato, como texto; conserva ceros iniciales. Nunca booleano." }, "placa": { "type": "string", "minLength": 1, "maxLength": 30, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite.", "pattern": "^(?=.*[A-Za-z0-9])[A-Za-z0-9 -]+$" }, "PLACA": { "type": "string", "minLength": 1, "maxLength": 30, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite.", "pattern": "^(?=.*[A-Za-z0-9])[A-Za-z0-9 -]+$" }, "marca": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "MARCA": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "modelo": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "MODELO": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "anio": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite. Entre 1900 y año actual + 1.", "pattern": "^[0-9]{4}$" }, "AÑO": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite. Entre 1900 y año actual + 1.", "pattern": "^[0-9]{4}$" }, "color": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 80, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." }, "COLOR": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 80, "description": "No vacío ni caracteres de control. Null solo si el perfil explícito del emisor lo permite." } }, "allOf": [ { "oneOf": [ { "required": [ "cliente" ], "not": { "required": [ "CLIENTE" ] } }, { "required": [ "CLIENTE" ], "not": { "required": [ "cliente" ] } } ] }, { "oneOf": [ { "required": [ "telefono" ], "not": { "required": [ "TELÉFONO" ] } }, { "required": [ "TELÉFONO" ], "not": { "required": [ "telefono" ] } } ] }, { "oneOf": [ { "required": [ "agencia" ], "not": { "required": [ "AGENCIA" ] } }, { "required": [ "AGENCIA" ], "not": { "required": [ "agencia" ] } } ] }, { "oneOf": [ { "required": [ "contratoVigente" ], "not": { "required": [ "CONTRATO VIGENTE" ] } }, { "required": [ "CONTRATO VIGENTE" ], "not": { "required": [ "contratoVigente" ] } } ] }, { "oneOf": [ { "required": [ "placa" ], "not": { "required": [ "PLACA" ] } }, { "required": [ "PLACA" ], "not": { "required": [ "placa" ] } } ] }, { "oneOf": [ { "required": [ "marca" ], "not": { "required": [ "MARCA" ] } }, { "required": [ "MARCA" ], "not": { "required": [ "marca" ] } } ] }, { "oneOf": [ { "required": [ "modelo" ], "not": { "required": [ "MODELO" ] } }, { "required": [ "MODELO" ], "not": { "required": [ "modelo" ] } } ] }, { "oneOf": [ { "required": [ "anio" ], "not": { "required": [ "AÑO" ] } }, { "required": [ "AÑO" ], "not": { "required": [ "anio" ] } } ] }, { "oneOf": [ { "required": [ "color" ], "not": { "required": [ "COLOR" ] } }, { "required": [ "COLOR" ], "not": { "required": [ "color" ] } } ] } ], "example": { "cliente": "Cliente de ejemplo", "telefono": "+50500000000", "agencia": "AGENCIA AUTORIZADA", "contratoVigente": "000012-A", "placa": "QA123", "marca": "Marca de ensayo", "modelo": "Modelo de ensayo", "anio": "2024", "color": "BLANCO" } }, "ControlInput": { "type": "object", "additionalProperties": false, "required": [ "imei", "action" ], "properties": { "imei": { "type": "string", "pattern": "^[0-9]{15}$", "description": "IMEI del GPS ya asociado al vehículo. No amplía el alcance de la llave." }, "action": { "type": "string", "enum": [ "IMMOBILIZE", "ENABLE" ] } }, "example": { "imei": "900000000000001", "action": "IMMOBILIZE" } }, "OperationData": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "state", "resultCode", "vehicleId", "imei", "providerCommandId", "createdAt", "updatedAt", "expiresAt", "deviceOutputConfirmed", "engineStateVerified" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "VEHICLE", "CONTROL" ] }, "state": { "type": "string", "enum": [ "RECEIVED", "PROCESSING", "DISPATCHING", "SUCCEEDED", "EXISTING", "SENT", "OUTPUT_CONFIRMED", "BLOCKED", "FAILED", "EXPIRED", "UNKNOWN" ] }, "resultCode": { "type": [ "string", "null" ] }, "vehicleId": { "type": [ "string", "null" ] }, "imei": { "type": [ "string", "null" ] }, "providerCommandId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "deviceOutputConfirmed": { "type": "boolean", "description": "Salida reportada después del envío; no confirma motor físico." }, "engineStateVerified": { "type": "boolean", "const": false } } }, "OperationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OperationData" }, "history": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "state", "code", "createdAt" ], "properties": { "state": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }