{"openapi":"3.0.0","paths":{"/health":{"get":{"operationId":"AppController_getHealth","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Health check detalhado com status dos bancos","tags":["Health"]}},"/status":{"get":{"operationId":"AppController_getServiceStatus","parameters":[],"responses":{"200":{"description":""}},"summary":"Status básico da API (para health check Docker)","tags":["Health"]}},"/live":{"get":{"operationId":"AppController_getLiveness","parameters":[],"responses":{"200":{"description":""}},"summary":"Liveness probe - verifica se a aplicação está viva","tags":["Health"]}},"/ready":{"get":{"operationId":"AppController_getReadiness","parameters":[],"responses":{"200":{"description":""}},"summary":"Readiness probe - verifica se está pronta para tráfego","tags":["Health"]}},"/":{"get":{"operationId":"DocController_getPortal","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/docs":{"get":{"operationId":"DocController_getDocsAlias","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/docs/assets/{filename}":{"get":{"operationId":"DocController_getDocAsset","parameters":[{"name":"filename","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/swagger":{"get":{"operationId":"DocController_getSwagger","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/swagger/json":{"get":{"operationId":"DocController_getSwaggerJson","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/docs/guide":{"get":{"operationId":"DocController_getGuide","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/docs/guide.md":{"get":{"operationId":"DocController_getGuideMarkdown","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Doc"]}},"/auth/register":{"post":{"operationId":"AuthController_register","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthUserDto"}}}},"responses":{"201":{"description":"User registered successfully"},"400":{"description":"Invalid request data"}},"summary":"Register a new user and link them to a company","tags":["Auth"]}},"/auth/login":{"post":{"operationId":"AuthController_login","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginDto"}}}},"responses":{"200":{"description":"Login successful"},"401":{"description":"Invalid credentials"}},"summary":"Authenticate and return a JWT token","tags":["Auth"]}},"/auth/forgot-password":{"post":{"operationId":"AuthController_forgotPassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordDto"}}}},"responses":{"200":{"description":"Request processed successfully"}},"summary":"Request a password reset with a neutral security response","tags":["Auth"]}},"/auth/reset-password":{"post":{"operationId":"AuthController_resetPassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordDto"}}}},"responses":{"200":{"description":"Password reset successfully"},"401":{"description":"Invalid or expired token"}},"summary":"Reset a password with a temporary token","tags":["Auth"]}},"/auth/password":{"patch":{"operationId":"AuthController_update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeAuthPasswordDto"}}}},"responses":{"200":{"description":"Password changed successfully"},"401":{"description":"Unauthorized or old password is incorrect"}},"security":[{"JWT-auth":[]}],"summary":"Change the authenticated user password","tags":["Auth"]}},"/auth/{id}":{"delete":{"operationId":"AuthController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Authentication record inactivated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Inactivate an authentication record","tags":["Auth"]}},"/auth/refresh-token":{"get":{"operationId":"AuthController_refreshToken","parameters":[],"responses":{"200":{"description":"Token refreshed successfully"},"401":{"description":"Invalid or expired token"}},"security":[{"JWT-auth":[]}],"summary":"Refresh the user JWT token","tags":["Auth"]}},"/address":{"post":{"description":"Create a new address with a simple input payload.","operationId":"AddressController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimpleAddressDto"}}}},"responses":{"201":{"description":"Address created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create address","tags":["Address"]},"get":{"description":"Return all registered addresses.","operationId":"AddressController_findAll","parameters":[],"responses":{"200":{"description":"Address list"}},"security":[{"JWT-auth":[]}],"summary":"List addresses","tags":["Address"]}},"/address/user/{userID}":{"get":{"description":"Return the single address associated with a user.","operationId":"AddressController_findByUser","parameters":[{"name":"userID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"User address"}},"security":[{"JWT-auth":[]}],"summary":"Get a user address","tags":["Address"]}},"/address/company/{companyID}":{"get":{"description":"Return the single address associated with a company.","operationId":"AddressController_findByCompany","parameters":[{"name":"companyID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Company address"}},"security":[{"JWT-auth":[]}],"summary":"Get a company address","tags":["Address"]}},"/address/{id}":{"get":{"description":"Return a specific address by ID.","operationId":"AddressController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Address details"}},"security":[{"JWT-auth":[]}],"summary":"Get address","tags":["Address"]},"patch":{"description":"Update an existing address.","operationId":"AddressController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAddressDto"}}}},"responses":{"200":{"description":"Address updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update address","tags":["Address"]},"delete":{"description":"Delete an address by ID.","operationId":"AddressController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Address deleted successfully"}},"security":[{"JWT-auth":[]}],"summary":"Delete address","tags":["Address"]}},"/status-type":{"post":{"operationId":"StatusTypeController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStatusTypeDto"}}}},"responses":{"201":{"description":"Status type created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a new status type","tags":["Status"]},"get":{"operationId":"StatusTypeController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all status types","tags":["Status"]}},"/status-type/{id}":{"get":{"operationId":"StatusTypeController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a status type by ID","tags":["Status"]},"patch":{"operationId":"StatusTypeController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStatusTypeDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Update a status type","tags":["Status"]},"delete":{"operationId":"StatusTypeController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Delete a status type","tags":["Status"]}},"/user":{"post":{"operationId":"UserController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserDto"}}}},"responses":{"201":{"description":"User created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a new user","tags":["User"]},"get":{"operationId":"UserController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"User list"}},"security":[{"JWT-auth":[]}],"summary":"List all users with pagination","tags":["User"]}},"/user/{id}":{"get":{"operationId":"UserController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"User details"}},"security":[{"JWT-auth":[]}],"summary":"Get a user by ID","tags":["User"]},"patch":{"operationId":"UserController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserDto"}}}},"responses":{"200":{"description":"User updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update a user","tags":["User"]},"delete":{"operationId":"UserController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"User inactivated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Inactivate a user","tags":["User"]}},"/default-permissions":{"get":{"operationId":"DefaultPermissionsController_findAll","parameters":[],"responses":{"200":{"description":"Default permission profiles"}},"security":[{"JWT-auth":[]}],"summary":"List default permission profiles by role","tags":["Default Permissions"]}},"/default-permissions/{roleName}":{"get":{"operationId":"DefaultPermissionsController_findByRole","parameters":[{"name":"roleName","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Default role permissions"}},"security":[{"JWT-auth":[]}],"summary":"Get the default permissions for a system role","tags":["Default Permissions"]}},"/user-activity":{"get":{"description":"Return user activity logs with filters and pagination","operationId":"UserActivityController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}},{"name":"action","required":false,"in":"query","description":"Filter by a specific activity action","schema":{"type":"string","enum":["login","logout","register","authentication_failed","token_refresh","password_change","password_reset_request","password_reset","create","read","update","delete","api_key_regenerate","permission_denied","owner_access_denied","api_key_denied","device_assign","device_unassign","notification_send","notification_read","notification_read_all","fcm_token_register","fcm_token_delete","fcm_token_delete_all"]}},{"name":"category","required":false,"in":"query","description":"Filter by activity category","schema":{"type":"string","enum":["authentication","write","read","notification","security"]}},{"name":"statusCode","required":false,"in":"query","description":"Filter by HTTP status code","schema":{"type":"number"}},{"name":"startDate","required":false,"in":"query","description":"Start date in ISO 8601 format","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date in ISO 8601 format","schema":{"type":"string"}}],"responses":{"200":{"description":"User activity log list"}},"security":[{"JWT-auth":[]}],"summary":"List user activity logs","tags":["User Activity"]}},"/user-activity/user/{userID}":{"get":{"description":"Return user activity logs for a specific user","operationId":"UserActivityController_findByUser","parameters":[{"name":"userID","required":true,"in":"path","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"User activity log list"}},"security":[{"JWT-auth":[]}],"summary":"List logs for a specific user","tags":["User Activity"]}},"/user-company-register":{"post":{"operationId":"UserCompanyRegisterController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserCompanyRegisterDto"}}}},"responses":{"201":{"description":"Binding created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a user-company binding with role and type","tags":["User Company Register"]}},"/user-company-register/{id}/permissions":{"patch":{"operationId":"UserCompanyRegisterController_updatePermissions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserCompanyRegisterPermissionsDto"}}}},"responses":{"200":{"description":"Permissions updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Override or reset permissions for a user-company binding","tags":["User Company Register"]}},"/user-company-register/{id}":{"delete":{"operationId":"UserCompanyRegisterController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Binding inactivated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Inactivate a user-company binding","tags":["User Company Register"]}},"/parameters/default":{"get":{"operationId":"ParametersController_getDefaultParameters","parameters":[],"responses":{"200":{"description":"Default parameters"}},"security":[{"JWT-auth":[]}],"summary":"Return the system default parameters","tags":["Parameters"]}},"/parameters":{"get":{"operationId":"ParametersController_getUserParameters","parameters":[],"responses":{"200":{"description":"User parameters"}},"security":[{"JWT-auth":[]}],"summary":"Return the current user alert parameters","tags":["Parameters"]},"patch":{"operationId":"ParametersController_updateUserParameters","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertParametersDto"}}}},"responses":{"200":{"description":"Parameters updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update the current user alert parameters","tags":["Parameters"]}},"/user-role":{"post":{"operationId":"UserRoleController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRoleDto"}}}},"responses":{"201":{"description":"Role created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a company-scoped custom user role with permission template","tags":["User Role"]},"get":{"operationId":"UserRoleController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List roles visible in the authenticated user scope","tags":["User Role"]}},"/user-role/{id}":{"get":{"operationId":"UserRoleController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a role by id within the caller scope","tags":["User Role"]},"patch":{"operationId":"UserRoleController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRoleDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Rename a custom company role","tags":["User Role"]},"delete":{"operationId":"UserRoleController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Delete an unused custom company role","tags":["User Role"]}},"/user-role/{id}/permissions":{"put":{"description":"System role templates require master. Custom company roles can be managed by the company admin. Optional propagate updates non-override registers.","operationId":"UserRoleController_updatePermissions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRolePermissionsDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Update the permission template for a role","tags":["User Role"]}},"/fcm-token/register":{"post":{"operationId":"FcmTokenController_register","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterFcmTokenDto"}}}},"responses":{"201":{"description":"FCM token registered successfully"}},"security":[{"JWT-auth":[]}],"summary":"Register a new FCM token for push notifications","tags":["FCM Token"]}},"/fcm-token":{"delete":{"operationId":"FcmTokenController_delete","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFcmTokenDto"}}}},"responses":{"200":{"description":"FCM token removed successfully"}},"security":[{"JWT-auth":[]}],"summary":"Remove a specific FCM token","tags":["FCM Token"]}},"/fcm-token/all":{"delete":{"operationId":"FcmTokenController_deleteAll","parameters":[],"responses":{"200":{"description":"FCM tokens removed successfully"}},"security":[{"JWT-auth":[]}],"summary":"Remove all FCM tokens for the authenticated user","tags":["FCM Token"]}},"/event":{"get":{"operationId":"EventController_getEvents","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Paginated event list for all users in the company scope"}},"security":[{"JWT-auth":[]}],"summary":"List company events and notifications","tags":["Event"]}},"/binding":{"post":{"operationId":"DeviceCompanyRegisterController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeviceCompanyRegisterDto"}}}},"responses":{"201":{"description":"Device binding created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Assign one or more devices to a company","tags":["Device Company Register"]},"get":{"operationId":"DeviceCompanyRegisterController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all device-company bindings","tags":["Device Company Register"]}},"/binding/{id}":{"get":{"operationId":"DeviceCompanyRegisterController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"404":{"description":"Device binding not found"}},"security":[{"JWT-auth":[]}],"summary":"Get a device-company binding by ID","tags":["Device Company Register"]},"patch":{"operationId":"DeviceCompanyRegisterController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeviceCompanyRegisterDto"}}}},"responses":{"404":{"description":"Device binding not found"}},"security":[{"JWT-auth":[]}],"summary":"Update a device-company binding","tags":["Device Company Register"]},"delete":{"operationId":"DeviceCompanyRegisterController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Device binding removed successfully"},"404":{"description":"Device binding not found"}},"security":[{"JWT-auth":[]}],"summary":"Delete a device-company binding","tags":["Device Company Register"]}},"/device":{"post":{"operationId":"DeviceCrudController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeviceDto"}}}},"responses":{"201":{"description":"Device created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a new device","tags":["Device"]},"get":{"operationId":"DeviceCrudController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Device list"}},"security":[{"JWT-auth":[]}],"summary":"List all registered devices with pagination","tags":["Device"]}},"/device/by-id/{id}":{"get":{"operationId":"DeviceCrudController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a device by internal ID","tags":["Device"]}},"/device/{id}":{"patch":{"operationId":"DeviceCrudController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeviceDto"}}}},"responses":{"200":{"description":"Device updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update a device","tags":["Device"]},"delete":{"operationId":"DeviceCrudController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Device inactivated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Inactivate a device","tags":["Device"]}},"/device/change-activity-status/{id}":{"patch":{"operationId":"DeviceCrudController_changeActivityStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Change a device status","tags":["Device"]}},"/device/last-positions":{"get":{"operationId":"DeviceConsumerController_getConsumerDevicePositions","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start date (ISO 8601). Naive values are America/Sao_Paulo wall clock.","schema":{"format":"date-time","example":"2026-07-23T13:41","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO 8601). Naive values are America/Sao_Paulo wall clock.","schema":{"format":"date-time","example":"2026-07-24T13:41","type":"string"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get the latest known positions for customer devices","tags":["Device","Consumer"]}},"/device/unknown":{"get":{"operationId":"DeviceConsumerController_findAllUnknown","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List devices that sent packets but are not registered in the system","tags":["Device","Consumer"]}},"/device/tracking-report":{"get":{"description":"Requires deviceId or vehicleId (not both). Vehicle mode returns packets for all devices whose installation overlapped the period, in chronological order. No maximum period. Each row includes a compact dataSummary plus full packet data for diagnostics. Requires history:report (not only device:read / map access).","operationId":"DeviceConsumerController_getTrackingReport","parameters":[{"name":"deviceId","required":false,"in":"query","description":"External device id. Required when vehicleId is omitted.","schema":{"type":"string"}},{"name":"vehicleId","required":false,"in":"query","description":"Vehicle id. When set, returns packets for all devices whose installation overlapped the period.","schema":{"type":"number"}},{"name":"startDate","required":true,"in":"query","description":"Period start. Naive datetime-local values use America/Sao_Paulo.","schema":{"format":"date-time","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"Period end. Naive datetime-local values use America/Sao_Paulo.","schema":{"format":"date-time","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Page size. Ignored when `all=true`. No hard upper bound for report exports.","schema":{"default":50,"type":"number"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching packets for the period without pagination.","schema":{"default":false,"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","schema":{"default":"timestamp","type":"string","enum":["timestamp","deviceId","lat","lng","speed","moving","packetType"]}},{"name":"sortDir","required":false,"in":"query","schema":{"default":"asc","type":"string","enum":["asc","desc"]}},{"name":"packetTypes","required":false,"in":"query","description":"Comma-separated packet type codes (catalog id 0–34) to filter. Omitted = all types.","schema":{"type":"array","items":{"type":"number"}}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Tracking report from raw device packets","tags":["Device","Consumer"]}},"/device/route/{deviceId}":{"get":{"description":"startDate/endDate accept ISO 8601. Values without timezone are interpreted as America/Sao_Paulo wall clock (e.g. datetime-local `2026-07-24T13:41` → 13:41 BRT). Explicit `Z` or offsets are absolute instants.","operationId":"DeviceConsumerController_getDeviceRoute","parameters":[{"name":"deviceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","schema":{"type":"string"}},{"name":"endDate","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"cleanStops","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a device route history for a time range","tags":["Device","Consumer"]}},"/device/types":{"get":{"operationId":"DeviceTypesController_getDeviceTypes","parameters":[],"responses":{"200":{"description":"Device type list"}},"security":[{"JWT-auth":[]}],"summary":"Get all available device types","tags":["Device"]}},"/device/types/{id}":{"get":{"operationId":"DeviceTypesController_getDeviceType","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a device type by id","tags":["Device"]}},"/device/logistic-status":{"post":{"operationId":"DeviceLogisticStatusController_createLogisticStatusType","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeviceLogisticStatusTypeDto"}}}},"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Create a new device logistic status","tags":["Device"]},"get":{"operationId":"DeviceLogisticStatusController_geLogisticStatusTypes","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all device logistic statuses","tags":["Device"]}},"/device/logistic-status/{id}":{"get":{"operationId":"DeviceLogisticStatusController_getLogisticStatusTypeById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a device logistic status by ID","tags":["Device"]},"patch":{"operationId":"DeviceLogisticStatusController_updateLogisticStatusType","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeviceLogisticStatusTypeDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Update a device logistic status","tags":["Device"]},"delete":{"operationId":"DeviceLogisticStatusController_deleteLogisticStatusType","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Delete a device logistic status","tags":["Device"]}},"/device/manufacturers":{"get":{"operationId":"DeviceManufacturerController_findAllManufacturers","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all registered device manufacturers","tags":["Device"]}},"/device/manufacturers/{id}":{"get":{"operationId":"DeviceManufacturerController_findManufacturerById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a manufacturer by ID","tags":["Device"]}},"/device/device-models":{"get":{"operationId":"DeviceModelController_findAllDeviceModels","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all device models","tags":["Device"]}},"/device/device-models/{id}":{"get":{"operationId":"DeviceModelController_findDeviceModelsByManufacturer","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List device models by manufacturer","tags":["Device"]}},"/device/device-model/{id}":{"get":{"operationId":"DeviceModelController_findDeviceModelById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a device model by id","tags":["Device"]}},"/notification":{"get":{"operationId":"NotificationController_getNotifications","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}},{"name":"category","required":false,"in":"query","description":"Filter by notification category (event or system)","schema":{"type":"string","enum":["event","system"]}}],"responses":{"200":{"description":"Unread notification list"}},"security":[{"JWT-auth":[]}],"summary":"List unread notifications for the authenticated user","tags":["Notification"]}},"/notification/unread-counts":{"get":{"operationId":"NotificationController_getUnreadCounts","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Unread notification counts by category","tags":["Notification"]}},"/notification/notify":{"post":{"operationId":"NotificationController_sendTestNotification","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendNotificationDto"}}}},"responses":{"201":{"description":"Notification queued successfully"}},"security":[{"JWT-auth":[]}],"summary":"Send a test notification to the authenticated user","tags":["Notification"]}},"/notification/history":{"get":{"operationId":"NotificationController_getHistory","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}},{"name":"category","required":false,"in":"query","description":"Filter by notification category (event or system)","schema":{"type":"string","enum":["event","system"]}}],"responses":{"200":{"description":"Notification history"}},"security":[{"JWT-auth":[]}],"summary":"Get notification history for the authenticated user","tags":["Notification"]}},"/notification/read-all":{"patch":{"operationId":"NotificationController_markAllAsRead","parameters":[],"responses":{"200":{"description":"Notifications marked as read"}},"security":[{"JWT-auth":[]}],"summary":"Mark all notifications as read for the authenticated user","tags":["Notification"]}},"/notification/{id}/read":{"patch":{"operationId":"NotificationController_markAsRead","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Notification marked as read"}},"security":[{"JWT-auth":[]}],"summary":"Mark a specific notification as read","tags":["Notification"]}},"/activation-key/generate":{"get":{"operationId":"ActivationKeyController_generate","parameters":[],"responses":{"200":{"description":"Activation key generated"}},"security":[{"JWT-auth":[]}],"summary":"Generate a new activation key for the authenticated user","tags":["Activation Key"]}},"/activation-key/use":{"post":{"operationId":"ActivationKeyController_use","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseActivationKeyDto"}}}},"responses":{"200":{"description":"Activation key consumed"},"400":{"description":"Invalid or expired activation key"}},"security":[{"JWT-auth":[]}],"summary":"Validate and consume an activation key","tags":["Activation Key"]}},"/activation-key":{"get":{"operationId":"ActivationKeyController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all activation keys","tags":["Activation Key"]}},"/activation-key/{id}":{"get":{"operationId":"ActivationKeyController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"404":{"description":"Activation key not found"}},"security":[{"JWT-auth":[]}],"summary":"Get an activation key by ID","tags":["Activation Key"]},"delete":{"operationId":"ActivationKeyController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"404":{"description":"Activation key not found"}},"security":[{"JWT-auth":[]}],"summary":"Delete an activation key","tags":["Activation Key"]}},"/color":{"get":{"operationId":"ColorController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all colors","tags":["Color"]}},"/color/{id}":{"get":{"operationId":"ColorController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a color by id","tags":["Color"]}},"/vehicle":{"post":{"operationId":"VehicleController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVehicleDto"}}}},"responses":{"201":{"description":"Vehicle created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a vehicle","tags":["Vehicle"]},"get":{"operationId":"VehicleController_findAllPaginated","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Vehicle list"}},"security":[{"JWT-auth":[]}],"summary":"List vehicles with pagination","tags":["Vehicle"]}},"/vehicle/all":{"get":{"operationId":"VehicleController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List all vehicles without pagination","tags":["Vehicle"]}},"/vehicle/driver/{driverID}":{"get":{"operationId":"VehicleController_findByDriver","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List vehicles assigned to a driver","tags":["Vehicle"]}},"/vehicle/{id}":{"get":{"operationId":"VehicleController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Vehicle details"}},"security":[{"JWT-auth":[]}],"summary":"Get a vehicle by id","tags":["Vehicle"]},"patch":{"operationId":"VehicleController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVehicleDto"}}}},"responses":{"200":{"description":"Vehicle updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update a vehicle","tags":["Vehicle"]},"delete":{"operationId":"VehicleController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Vehicle inactivated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Inactivate a vehicle","tags":["Vehicle"]}},"/vehicle/{vehicleID}/available-devices":{"get":{"operationId":"VehicleController_findAvailableDevices","parameters":[{"name":"vehicleID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Available devices from the same company scope"}},"security":[{"JWT-auth":[]}],"summary":"List devices available to install on the vehicle","tags":["Vehicle"]}},"/vehicle-brand":{"get":{"operationId":"VehicleBrandController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List vehicle brands","tags":["Vehicle Brand"]}},"/vehicle-brand/{id}":{"get":{"operationId":"VehicleBrandController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a vehicle brand by id","tags":["Vehicle Brand"]}},"/vehicle-model":{"get":{"operationId":"VehicleModelController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List vehicle models","tags":["Vehicle Model"]}},"/vehicle-model/by-brand/{brandID}":{"get":{"operationId":"VehicleModelController_findByBrand","parameters":[{"name":"brandID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List models by brand","tags":["Vehicle Model"]}},"/vehicle-model/{id}":{"get":{"operationId":"VehicleModelController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a vehicle model by id","tags":["Vehicle Model"]}},"/vehicle-type":{"get":{"operationId":"VehicleTypeController_findAll","parameters":[],"responses":{"200":{"description":"Vehicle type list"}},"security":[{"JWT-auth":[]}],"summary":"List vehicle types","tags":["Vehicle Type"]}},"/vehicle-type/{id}":{"get":{"operationId":"VehicleTypeController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a vehicle type by id","tags":["Vehicle Type"]}},"/installation":{"post":{"operationId":"InstallationController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstallationDto"}}}},"responses":{"201":{"description":"Installation created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a new installation","tags":["Installation"]},"get":{"operationId":"InstallationController_findAll","parameters":[],"responses":{"200":{"description":"Installation list"}},"security":[{"JWT-auth":[]}],"summary":"List all installations","tags":["Installation"]}},"/installation/remove-from-vehicle":{"patch":{"operationId":"InstallationController_removeFromVehicle","parameters":[],"responses":{"200":{"description":"Device removed from the vehicle successfully"}},"security":[{"JWT-auth":[]}],"summary":"Remove a device from a vehicle","tags":["Installation"]}},"/installation/{id}":{"get":{"operationId":"InstallationController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Installation details"}},"security":[{"JWT-auth":[]}],"summary":"Get an installation by ID","tags":["Installation"]},"patch":{"operationId":"InstallationController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInstallationDto"}}}},"responses":{"200":{"description":"Installation updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update an installation","tags":["Installation"]},"delete":{"operationId":"InstallationController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Installation deleted successfully"}},"security":[{"JWT-auth":[]}],"summary":"Delete an installation","tags":["Installation"]}},"/installation-type":{"post":{"operationId":"InstallationTypeController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstallationTypeDto"}}}},"responses":{"201":{"description":"Installation type created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a new installation type","tags":["Installation Type"]},"get":{"operationId":"InstallationTypeController_findAll","parameters":[],"responses":{"200":{"description":"Installation type list"}},"security":[{"JWT-auth":[]}],"summary":"List all installation types","tags":["Installation Type"]}},"/installation-type/{id}":{"patch":{"operationId":"InstallationTypeController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInstallationTypeDto"}}}},"responses":{"200":{"description":"Installation type updated successfully"}},"security":[{"JWT-auth":[]}],"summary":"Update an installation type","tags":["Installation Type"]},"delete":{"operationId":"InstallationTypeController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Installation type deleted successfully"}},"security":[{"JWT-auth":[]}],"summary":"Delete an installation type","tags":["Installation Type"]}},"/user-type":{"get":{"operationId":"UserTypeController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Lista todos os tipos de usuários","tags":["User Type"]}},"/user-type/{id}":{"get":{"operationId":"UserTypeController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Busca um tipo de usuário por ID","tags":["User Type"]}},"/map/ws-docs":{"get":{"description":"\n      ### 1. Connection\n      - **Endpoint:** /location-stream namespace\n      - **Protocol:** Socket.io\n      - **Authentication:** Send a JWT via 'auth: { token: \"JWT\" }' or the 'Authorization' header\n      \n      ### 2. Events Received (Client <= Server)\n      - **location-update**: Receives incremental real-time updates for the subscribed target. Historical trail data must be loaded from the HTTP vehicle details endpoint.\n      - **subscribed**: Subscription confirmation { vehicleId } or { deviceId }\n      - **unsubscribed**: Unsubscription confirmation { vehicleId } or { deviceId }\n      - **error**: Socket or validation errors\n      \n      ### 3. Events Sent (Client => Server)\n      - **subscribe-vehicle**: { vehicleId: number, deviceIds?: string[], trailLimit?: number, trailMode?: 'points' | 'sinceIgnition', cleanStops?: boolean } for vehicles or { deviceId: string } for standalone devices\n      - **unsubscribe-vehicle**: { vehicleId: number, deviceIds?: string[], trailLimit?: number, trailMode?: 'points' | 'sinceIgnition', cleanStops?: boolean } for vehicles or { deviceId: string } for standalone devices\n    ","operationId":"MapController_getWsDocs","parameters":[],"responses":{"200":{"description":"WebSocket integration guide"}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Get the WebSocket connection guide for the live location stream","tags":["Map"]}},"/map/positions":{"get":{"operationId":"MapController_getPositions","parameters":[{"name":"startDate","required":false,"in":"query","description":"Start date (ISO 8601). Naive values are America/Sao_Paulo wall clock.","schema":{"format":"date-time","example":"2026-07-23T13:41","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO 8601). Naive values are America/Sao_Paulo wall clock.","schema":{"format":"date-time","example":"2026-07-24T13:41","type":"string"}},{"name":"vehiclesOnly","required":false,"in":"query","description":"When true, only aggregated vehicle positions are returned and standalone infrastructure points are omitted.","schema":{"default":true,"example":true,"type":"boolean"}}],"responses":{"200":{"description":"List of lightweight map overview positions for vehicles and standalone infrastructure points.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MapPositionsDto"}}}}}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Get map overview positions","tags":["Map"]}},"/map/vehicles/{vehicleId}":{"get":{"operationId":"MapController_getVehiclePosition","parameters":[{"name":"vehicleId","required":true,"in":"path","schema":{"type":"number"}},{"name":"deviceIds","required":false,"in":"query","description":"Optional device IDs used to restrict the returned vehicle trail and live positions.","schema":{"example":["tracker-1","shield-1"],"type":"array","items":{"type":"string"}}},{"name":"trailLimit","required":false,"in":"query","description":"Maximum number of trail points returned by the backend.","schema":{"minimum":1,"maximum":1000,"example":100,"type":"number"}},{"name":"cleanStops","required":false,"in":"query","description":"When true (default), collapses GPS jitter while the vehicle is stopped before returning the trail.","schema":{"default":true,"type":"boolean"}},{"name":"trailMode","required":false,"in":"query","description":"Trail window mode. `points` returns the latest N points in the default 24h window. `sinceIgnition` starts the trail at the last IGN. ON (packtype 1) within 7 days; if none is found, falls back to `points` and returns `ignitionOnAt: null`.","schema":{"default":"points","type":"string","enum":["points","sinceIgnition"]}}],"responses":{"200":{"description":"Detailed vehicle map payload with backend-computed trail, installed device positions, and lastRegisteredPosition independent of filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapVehicleDetailsDto"}}}}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Get a single vehicle map payload with backend-computed trail","tags":["Map"]}},"/command":{"get":{"operationId":"CommandController_getAllCommands","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Command list"}},"security":[{"JWT-auth":[]}],"summary":"List sent commands","tags":["Command"]},"post":{"operationId":"CommandController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommandDto"}}}},"responses":{"201":{"description":"Command queued successfully"}},"security":[{"JWT-auth":[]}],"summary":"Send a command to a device","tags":["Command"]}},"/command/cancel":{"post":{"operationId":"CommandController_cancel","parameters":[],"responses":{"200":{"description":"Command cancellation processed"}},"security":[{"JWT-auth":[]}],"summary":"Cancel a previously sent command","tags":["Command"]}},"/default-command":{"get":{"operationId":"DefaultCommandController_findAll","parameters":[{"name":"activeOnly","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List default command templates","tags":["Default Command"]}},"/default-command/{id}":{"get":{"operationId":"DefaultCommandController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a default command template by id","tags":["Default Command"]}},"/permissions/catalog":{"get":{"operationId":"PermissionsCatalogController_getCatalog","parameters":[],"responses":{"200":{"description":"Permission vocabulary used by role templates and overrides. `required` is always merged on save and JWT."}},"security":[{"JWT-auth":[]}],"summary":"List canonical permission modules, actions, and required grants","tags":["Permissions"]}},"/overview/home":{"get":{"operationId":"OverviewController_getHomeOverview","parameters":[{"name":"startDate","required":false,"in":"query","schema":{"example":"2026-04-07T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","schema":{"example":"2026-04-08T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"Aggregated dashboard overview scoped to the active company"}},"security":[{"JWT-auth":[]}],"summary":"Return the aggregated home overview payload","tags":["Overview"]}},"/sim-card":{"post":{"operationId":"SimCardController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimCardDto"}}}},"responses":{"201":{"description":"Sim card created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a sim card","tags":["SimCard"]},"get":{"operationId":"SimCardController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List sim cards for the caller scope","tags":["SimCard"]}},"/sim-card/stock":{"get":{"operationId":"SimCardController_findStock","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List stocked sim cards (not attached)","tags":["SimCard"]}},"/sim-card/available-for-device/{deviceID}":{"get":{"operationId":"SimCardController_findAvailableForDevice","parameters":[{"name":"deviceID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List stocked sim cards available to attach to a device (same company scope)","tags":["SimCard"]}},"/sim-card/assign-to-device":{"post":{"operationId":"SimCardController_assignToDevice","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignSimCardsToDeviceDto"}}}},"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Reconcile sim cards attached to a device (no ordering). Replaces the current set.","tags":["SimCard"]}},"/sim-card/{id}":{"get":{"operationId":"SimCardController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a sim card by id","tags":["SimCard"]},"patch":{"operationId":"SimCardController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSimCardDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Update a sim card","tags":["SimCard"]},"delete":{"operationId":"SimCardController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Soft-delete a sim card","tags":["SimCard"]}},"/sim-card/{id}/attach":{"post":{"operationId":"SimCardController_attach","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachSimCardDto"}}}},"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Attach a sim card to a device","tags":["SimCard"]}},"/sim-card/{id}/detach":{"post":{"operationId":"SimCardController_detach","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Detach a sim card from its device","tags":["SimCard"]}},"/sim-card-operator":{"get":{"operationId":"SimCardOperatorController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List sim card operators","tags":["SimCardOperator"]}},"/sim-card-operator/{id}":{"get":{"operationId":"SimCardOperatorController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a sim card operator by id","tags":["SimCardOperator"]}},"/sim-card-broker":{"get":{"operationId":"SimCardBrokerController_findAll","parameters":[],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List sim card brokers","tags":["SimCardBroker"]}},"/sim-card-broker/{id}":{"get":{"operationId":"SimCardBrokerController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get a sim card broker by id","tags":["SimCardBroker"]}},"/report-export":{"post":{"operationId":"ReportExportController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportExportDto"}}}},"responses":{"202":{"description":"Report export queued"}},"security":[{"JWT-auth":[]}],"summary":"Enqueue an asynchronous report export","tags":["Report Export"]},"get":{"operationId":"ReportExportController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List report exports for the current user","tags":["Report Export"]}},"/report-export/{id}":{"get":{"operationId":"ReportExportController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get report export status","tags":["Report Export"]}},"/report-export/{id}/file":{"get":{"operationId":"ReportExportController_download","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Download a ready report export file","tags":["Report Export"]}},"/speeding-report":{"get":{"operationId":"SpeedingReportController_getReport","parameters":[{"name":"deviceIds","required":true,"in":"query","schema":{"type":"string"}},{"name":"vehicleId","required":true,"in":"query","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","schema":{"type":"string"}},{"name":"endDate","required":true,"in":"query","schema":{"type":"string"}},{"name":"all","required":true,"in":"query","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get trajectory speed analysis with road speed limits","tags":["Speeding Report"]}},"/integration/me":{"get":{"description":"Retorna os dados da empresa autenticada pela integração.\n\nUse este endpoint para:\n- Validar que a API Key ou JWT estão configurados corretamente\n- Confirmar a identidade e o `companyId` da empresa antes de iniciar outros fluxos\n- Testar a conectividade no startup do serviço integrador\n\nAceita **API Key** (`X-Api-Key`) ou **JWT** (`Authorization: Bearer`).\nO `companyId` retornado deve ser usado como referência para correlacionar dados recebidos via map e WebSocket.","operationId":"IntegrationController_getMe","parameters":[],"responses":{"200":{"description":"Autenticação válida. Retorna os dados da empresa identificada.","content":{"application/json":{"schema":{"example":{"companyId":7,"companyName":"Transportadora Exemplo Ltda"},"properties":{"companyId":{"type":"number","description":"ID interno da empresa autenticada"},"companyName":{"type":"string","description":"Nome da empresa autenticada"}}}}}},"401":{"description":"Credencial ausente, inválida ou expirada."},"403":{"description":"Autenticado mas sem contexto de empresa resolvido."}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Verificar autenticação e conectividade da integração","tags":["Integration"]}},"/integration/devices/{deviceId}/trail":{"get":{"description":"Retorna o histórico de posições de um rastreador identificado pelo seu `deviceId` externo.\n\nUse este endpoint quando você conhece o `deviceId` do rastreador (ex: ID do hardware do dispositivo) mas não tem um `vehicleId` do knshield.\n\nO acesso é restrito automaticamente ao escopo da empresa autenticada — se o dispositivo existir mas pertencer a outra empresa, retorna `403`.\n\nAceita **API Key** (`X-Api-Key`) ou **JWT** (`Authorization: Bearer`).","operationId":"IntegrationController_getDeviceTrail","parameters":[{"name":"deviceId","required":true,"in":"path","description":"ID externo do dispositivo GPS (ex: `TK103_123456`, `tracker-1`)","schema":{"example":"tracker-1","type":"string"}},{"name":"trailLimit","required":false,"in":"query","description":"Maximum number of trail points returned.","schema":{"minimum":1,"maximum":1000,"default":200,"example":200,"type":"number"}},{"name":"startDate","required":false,"in":"query","description":"Start of the time window (ISO 8601). Defaults to 24 h before endDate.","schema":{"example":"2026-04-29T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End of the time window (ISO 8601). Defaults to now.","schema":{"example":"2026-04-29T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"Trail retornado com sucesso.","content":{"application/json":{"schema":{"example":{"deviceId":"tracker-1","trail":[{"deviceId":"tracker-1","timestamp":"2026-04-29T14:00:00.000Z","lat":-23.549,"lng":-46.631,"speed":38,"direction":175,"time":1745931600000}],"lastRegisteredPosition":{"deviceId":"tracker-1","timestamp":"2026-04-29T17:00:00.000Z","lat":-23.5505,"lng":-46.6333,"time":1745942400000,"speed":0}}}}}},"401":{"description":"API Key ausente, inválida ou revogada."},"403":{"description":"Dispositivo encontrado mas não pertence à empresa da chave autenticada."},"404":{"description":"Dispositivo não encontrado no sistema."}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Histórico de posições (trail) de um dispositivo GPS","tags":["Integration"]}},"/integration/events":{"get":{"description":"Retorna alertas de veículos da empresa autenticada, com os mesmos campos do `GET /event`.\n\nAceita **API Key** (`X-Api-Key`) ou **JWT** (`Authorization: Bearer`).\nUse `sinceId` para polling incremental (retorna apenas eventos com `id` maior que o informado).","operationId":"IntegrationController_getEvents","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Lista paginada de eventos operacionais da empresa."},"401":{"description":"Credencial ausente, inválida ou revogada."},"403":{"description":"Autenticado mas sem contexto de empresa resolvido."}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Listar eventos operacionais da empresa (integração B2B)","tags":["Integration"]}},"/integration/event-types":{"get":{"description":"Retorna os tipos de evento configuráveis no KNShield para filtros e exibição em integrações.\n\nAceita **API Key** (`X-Api-Key`) ou **JWT** (`Authorization: Bearer`).","operationId":"IntegrationController_getEventTypes","parameters":[],"responses":{"200":{"description":"Catálogo de tipos de alerta.","content":{"application/json":{"schema":{"example":{"events":[{"id":"6","name":"VEL. MAX","label":"Velocidade máxima","category":"driving_behavior"}]}}}}},"401":{"description":"Credencial ausente, inválida ou revogada."}},"security":[{"api-key":[]},{"JWT-auth":[]}],"summary":"Catálogo de tipos de alerta disponíveis","tags":["Integration"]}},"/driver":{"post":{"operationId":"DriverController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDriverDto"}}}},"responses":{"201":{"description":"Driver created successfully"}},"security":[{"JWT-auth":[]}],"summary":"Create a driver","tags":["Driver"]},"get":{"operationId":"DriverController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Ignored when `all=true`. No hard upper bound (report exports may request large pages).","schema":{"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Generic search term","schema":{"type":"string"}},{"name":"all","required":false,"in":"query","description":"When true, returns all matching items without pagination.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Driver list"}},"security":[{"JWT-auth":[]}],"summary":"List drivers with pagination","tags":["Driver"]}},"/driver/{driverID}":{"get":{"operationId":"DriverController_findOne","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Driver details"}},"security":[{"JWT-auth":[]}],"summary":"Get driver details","tags":["Driver"]},"patch":{"operationId":"DriverController_update","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDriverDto"}}}},"responses":{"200":{"description":"Driver updated"}},"security":[{"JWT-auth":[]}],"summary":"Update driver basic data","tags":["Driver"]}},"/driver/{driverID}/license":{"post":{"operationId":"DriverController_createLicense","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDriverLicenseDto"}}}},"responses":{"201":{"description":"License created"}},"security":[{"JWT-auth":[]}],"summary":"Create driver license","tags":["Driver"]},"patch":{"operationId":"DriverController_updateLicense","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDriverLicenseDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Update driver license","tags":["Driver"]}},"/driver/{driverID}/license/delete":{"post":{"operationId":"DriverController_deleteLicense","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Delete driver license","tags":["Driver"]}},"/driver/{driverID}/schedule":{"get":{"operationId":"DriverController_getSchedule","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Get driver weekly schedule","tags":["Driver"]},"put":{"operationId":"DriverController_replaceSchedule","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverScheduleBatchDto"}}}},"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Replace driver weekly schedule","tags":["Driver"]}},"/driver/{driverID}/vehicles":{"get":{"operationId":"DriverController_getVehicles","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"List vehicles assigned to driver","tags":["Driver"]}},"/driver/{driverID}/assign-vehicle":{"post":{"operationId":"DriverController_assignVehicle","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignVehicleDto"}}}},"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Assign vehicle to driver","tags":["Driver"]}},"/driver/{driverID}/unassign-vehicle/{vehicleRegisterID}":{"post":{"operationId":"DriverController_unassignVehicle","parameters":[{"name":"driverID","required":true,"in":"path","schema":{"type":"number"}},{"name":"vehicleRegisterID","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"security":[{"JWT-auth":[]}],"summary":"Unassign vehicle from driver","tags":["Driver"]}}},"info":{"title":"KNShield API - Sistema de Monitoramento e Controle","description":"\n  ### Bem-vindo à API KNShield\n\n  O KNShield é uma plataforma de controle e monitoramento de dispositivos, com visibilidade em tempo real e gestão de ativos.\n\n  #### Principais Funcionalidades:\n  *   **Monitoramento Multisectorial**: Suporte a diversos tipos de dispositivos como antenas, domos e rastreadores.\n  *   **Gestão de Frotas**: Veículos integrados com rastreadores para rastreamento no mapa.\n  *   **Arquitetura Multi-empresa (Multi-tenancy)**: Isolamento de dados entre empresas.\n  *   **Segurança Baseada em Roles (RBAC)**: Controle de acesso via JWT e permissões por papel de usuário.\n  *   **Autenticação por API Key**: Integrações server-to-server via header `X-Api-Key`, sem login, JWT ou refresh.\n  *   **Chaves de Ativação**: Desbloqueio de dispositivos via chaves geradas dinamicamente.\n  *   **Integração Operacional**: REST/JSON, OpenAPI e WebSocket para atualização em tempo real.\n  *   **Notificações Push**: Alertas e eventos para os canais suportados pela plataforma.\n\n  #### Autenticação — Resumo Rápido\n  | Cenário | Mecanismo | Header |\n  |---------|-----------|--------|\n  | Usuário autenticado (portal/app) | Bearer JWT | `Authorization: Bearer <token>` |\n  | Integração server-to-server | API Key | `X-Api-Key: <chave>` |\n  | WebSocket (realtime) | JWT ou API Key | `auth: { token }` ou `auth: { apiKey }` |\n\n  ---\n  *Desenvolvido por KNOV®*\n  \n\nPublic documentation view. Administrative OwnerOnly operations are hidden unless a master token is provided.","version":"1.16.393","contact":{}},"tags":[{"name":"Auth","description":"Autenticação e controle de acesso"},{"name":"Integration","description":"Conectividade e verificação de integrações externas"},{"name":"User","description":"Gestão de usuários do sistema"},{"name":"Device","description":"Gerenciamento e monitoramento de dispositivos"},{"name":"Activation Key","description":"Segurança e chaves de desbloqueio"},{"name":"Vehicle","description":"Gestão de veículos e ativos rastreados"},{"name":"Installation","description":"Vínculo entre dispositivos e veículos"},{"name":"Address","description":"Consulta de endereços e geocodificação"},{"name":"User Company Register","description":"Registro de usuários por empresa"},{"name":"User Activity","description":"Relatório de atividades dos usuários"},{"name":"FCM Token","description":"Token de notificação push"},{"name":"User Role","description":"Gerenciamento de permissões dos usuários"},{"name":"Device Company Register","description":"Registro de dispositivos por empresa"},{"name":"Color","description":"Cores"},{"name":"User Type","description":"Tipos de usuários"},{"name":"Map","description":"Mapas"}],"servers":[{"url":"http://localhost:3000","description":"Dev"},{"url":"https://api.knsh.com.br","description":"Production"}],"components":{"securitySchemes":{"JWT-auth":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Informe o token JWT"},"api-key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Chave de API da empresa para integrações server-to-server. Gerada e gerenciada pelo painel administrativo. Identifica e autoriza a empresa com escopo restrito aos dados dela."}},"schemas":{"CreateAuthUserDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"User Name"},"cpf":{"type":"string","example":"12345678901"},"phone":{"type":"string","example":"11999999999"},"email":{"type":"string","example":"user@knov.io"},"roleID":{"type":"number","example":2},"typeID":{"type":"number","example":3,"description":"User type. Cannot be 3 (driver) — use /driver endpoint instead."},"companyID":{"type":"number","example":1,"description":"Company to bind the user to. Required for access; master must pass explicitly."},"password":{"type":"string","example":"strongPassword123"},"authEmail":{"type":"string","example":"user@email.com","description":"Email for authentication"},"userID":{"type":"number","example":4}},"required":["name","cpf","phone","companyID","password","authEmail","userID"]},"LoginDto":{"type":"object","properties":{"email":{"type":"string","example":"example@email.com"},"password":{"type":"string","example":"strongPassword123"}},"required":["email","password"]},"ForgotPasswordDto":{"type":"object","properties":{"email":{"type":"string","example":"user@email.com","description":"User authentication email"}},"required":["email"]},"ResetPasswordDto":{"type":"object","properties":{"token":{"type":"string","example":"qf3xwS4j8n8L6x6nD8JdfJ9lSvQv9QfYgL2QhmnD8C8","description":"Password reset token received by email"},"password":{"type":"string","example":"NewStrongPassword123!","description":"New password (minimum 6 characters)"}},"required":["token","password"]},"ChangeAuthPasswordDto":{"type":"object","properties":{"oldPassword":{"type":"string","example":"oldPassword123","description":"Current password"},"password":{"type":"string","example":"newStrongPassword123","description":"New password (minimum 6 characters)"}},"required":["oldPassword","password"]},"CreateSimpleAddressDto":{"type":"object","properties":{"street":{"type":"string","example":"Rua das Flores","description":"Street name"},"number":{"type":"string","example":"100","description":"Street number"},"complement":{"type":"string","example":"Apto 201"},"district":{"type":"string","example":"Centro","description":"District name"},"city":{"type":"string","example":"Florianópolis","description":"City name"},"state":{"type":"string","example":"Santa Catarina","description":"State name"},"stateAbbr":{"type":"string","example":"SC","description":"State abbreviation"},"zipCode":{"type":"string","example":"88015-500","description":"ZIP code"},"country":{"type":"string","example":"Brasil","description":"Country name"},"latitude":{"type":"number","example":-27.5954,"description":"Address latitude"},"longitude":{"type":"number","example":-48.548,"description":"Address longitude"},"userID":{"type":"number","example":1,"description":"Associated user ID"},"companyID":{"type":"number","example":1,"description":"Associated company ID"}},"required":["street","district","city","state","zipCode"]},"UpdateAddressDto":{"type":"object","properties":{"street":{"type":"string","example":"Rua das Flores","description":"Street name"},"number":{"type":"string","example":"100","description":"Street number"},"complement":{"type":"string","example":"Apto 201"},"district":{"type":"string","example":"Centro","description":"District name"},"city":{"type":"string","example":"Florianópolis","description":"City name"},"state":{"type":"string","example":"Santa Catarina","description":"State name"},"stateAbbr":{"type":"string","example":"SC","description":"State abbreviation"},"zipCode":{"type":"string","example":"88015-500","description":"ZIP code"},"country":{"type":"string","example":"Brasil","description":"Country name"},"latitude":{"type":"number","example":-27.5954,"description":"Address latitude"},"longitude":{"type":"number","example":-48.548,"description":"Address longitude"},"userID":{"type":"number","example":1,"description":"Associated user ID"},"companyID":{"type":"number","example":1,"description":"Associated company ID"}}},"CreateStatusTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"active"}},"required":["name"]},"UpdateStatusTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"active"}}},"CreateUserDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"User Name"},"cpf":{"type":"string","example":"12345678901"},"phone":{"type":"string","example":"11999999999"},"email":{"type":"string","example":"user@knov.io"},"roleID":{"type":"number","example":1},"typeID":{"type":"number","example":2,"description":"User type. Cannot be 3 (driver) — use /driver endpoint instead."},"companyID":{"type":"number","example":1,"description":"Company to bind the user to. Required for access; master must pass explicitly."}},"required":["name","cpf","phone","companyID"]},"UpdateUserDto":{"type":"object","properties":{}},"UpsertDefaultPermissionsDto":{"type":"object","properties":{"permissions":{"type":"object","description":"Permissions map by module. Each module must contain an array of allowed actions.","example":{"company":["create","read"],"user":["read"]}}},"required":["permissions"]},"CreateUserCompanyRegisterDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"permissions":{"type":"object","example":{"company":["read","update"]}},"roleID":{"type":"number","example":1},"typeID":{"type":"number","example":1},"userID":{"type":"number","example":1},"companyID":{"type":"number","example":1}},"required":["roleID","typeID","userID","companyID"]},"UpdateUserCompanyRegisterPermissionsDto":{"type":"object","properties":{"reset":{"type":"boolean","description":"When true, resets permissions from the role template and clears the override flag.","example":true},"permissions":{"type":"object","description":"Custom permission map. Required when reset is not true. Sets permissionsOverride=true.","example":{"vehicle":["read"],"device":["read","update"]}}}},"AlertParametersDto":{"type":"object","properties":{}},"CreateUserRoleDto":{"type":"object","properties":{"name":{"type":"string","example":"fleet-manager"},"companyID":{"type":"number","description":"Target company for the custom role. Masters may set any company; admins always use their own company.","example":12},"permissions":{"type":"object","description":"Initial permission map. Empty object when omitted.","example":{"vehicle":["read"],"device":["read"]}},"cloneFromRoleID":{"type":"number","description":"Clone the permission template from an existing role id.","example":3}},"required":["name"]},"UpdateUserRoleDto":{"type":"object","properties":{"name":{"type":"string","example":"fleet-supervisor"}}},"UpdateUserRolePermissionsDto":{"type":"object","properties":{"permissions":{"type":"object","description":"Permissions map by module. Each module must contain an array of allowed actions.","example":{"vehicle":["read","update"],"device":["read"]}},"propagate":{"type":"boolean","description":"When true, updates registers that use this role and do not have a permissions override.","default":false}},"required":["permissions"]},"RegisterFcmTokenDto":{"type":"object","properties":{"token":{"type":"string","example":"fcm-token-value"},"deviceType":{"type":"string","example":"web"}},"required":["token"]},"DeleteFcmTokenDto":{"type":"object","properties":{"token":{"type":"string","example":"fcm-token-value"}},"required":["token"]},"CreateCompanyDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Example Company LLC"},"cnpj":{"type":"string","example":"12345678000199"},"email":{"type":"string","example":"company@knov.io"},"phone":{"type":"string","example":"+5511999999999"}},"required":["name","cnpj","phone"]},"UpdateCompanyDto":{"type":"object","properties":{"name":{"type":"string","example":"Example Company LLC"},"cnpj":{"type":"string","example":"12345678000199"},"email":{"type":"string","example":"company@knov.io"},"phone":{"type":"string","example":"+5511999999999"},"statusID":{"type":"number","example":1}},"required":["name","cnpj","phone"]},"CreateDeviceCompanyRegisterDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."}}},"ApiKeyListResponseDto":{"type":"object","properties":{"id":{"type":"number","example":1},"name":{"type":"string","example":"Example Company LLC"},"cnpj":{"type":"string","example":"12345678000199"},"hasApiKey":{"type":"boolean","example":true},"apiKeyPreview":{"type":"string","example":"knshield_abc...xyz","nullable":true},"createdAt":{"format":"date-time","type":"string","example":"2024-01-15T10:30:00Z"}},"required":["id","name","cnpj","hasApiKey","apiKeyPreview","createdAt"]},"ApiKeyInfoResponseDto":{"type":"object","properties":{"companyId":{"type":"number","example":1},"companyName":{"type":"string","example":"Example Company LLC"},"hasApiKey":{"type":"boolean","example":true},"apiKeyPreview":{"type":"string","example":"knshield_****...ab12cd34","nullable":true,"description":"Short hint confirming the key exists. The full plain key is only shown once at creation time."}},"required":["companyId","companyName","hasApiKey","apiKeyPreview"]},"ApiKeyResponseDto":{"type":"object","properties":{"apiKey":{"type":"string","example":"knshield_abc123..."},"companyId":{"type":"number","example":1},"companyName":{"type":"string","example":"Example Company LLC"},"generatedAt":{"format":"date-time","type":"string","example":"2024-01-15T10:30:00Z"}},"required":["apiKey","companyId","companyName","generatedAt"]},"UpdateDeviceCompanyRegisterDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."}}},"CreateDeviceDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"idDevice":{"type":"string","example":"865959064232320"},"version":{"type":"string","example":"1.0.0"},"timeInit":{"type":"string","example":"08:00:27:12:34:56"},"nickname":{"type":"string","example":"My Device"},"localID":{"type":"string","example":"local-001"},"latitude":{"type":"number","example":-27.595377},"longitude":{"type":"number","example":-48.54805},"logisticStatusID":{"type":"number","example":1},"modelID":{"type":"number","example":1},"typeID":{"type":"number","example":1},"companyID":{"type":"number","example":1,"description":"Company ID used to link the device"}},"required":["idDevice","version","timeInit","nickname","localID","latitude","longitude","logisticStatusID","modelID","typeID","companyID"]},"UpdateDeviceDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"idDevice":{"type":"string","example":"865959064232320"},"version":{"type":"string","example":"1.0.0"},"timeInit":{"type":"string","example":"08:00:27:12:34:56"},"nickname":{"type":"string","example":"My Device"},"localID":{"type":"string","example":"local-001"},"latitude":{"type":"number","example":-27.595377},"longitude":{"type":"number","example":-48.54805},"logisticStatusID":{"type":"number","example":1},"modelID":{"type":"number","example":1},"typeID":{"type":"number","example":1},"companyID":{"type":"number","example":1,"description":"Company ID used to link the device"}}},"CreateDeviceTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"shield"}},"required":["name"]},"UpdateDeviceTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"shield"}}},"CreateDeviceLogisticStatusTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"in_transit","enum":["in_transit","manufacturer_warehouse","client_warehouse","installer","installed","removed","maintenance"]}},"required":["name"]},"CreateManufacturerDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Manufacturer Name"}},"required":["name"]},"UpdateManufacturerDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Manufacturer Name"}}},"CreateDeviceModelDto":{"type":"object","properties":{"name":{"type":"string","example":"Model X100"},"manufacturerID":{"type":"number","example":1}},"required":["name","manufacturerID"]},"UpdateDeviceModelDto":{"type":"object","properties":{"name":{"type":"string","example":"Model X100"},"manufacturerID":{"type":"number","example":1}}},"SendNotificationDto":{"type":"object","properties":{"title":{"type":"string","example":"Vehicle alert"},"body":{"type":"string","example":"The vehicle has left the defined area."},"data":{"type":"object"},"deviceID":{"type":"string","example":"tracker-1"},"notificationType":{"type":"string","example":"manual"},"category":{"type":"string","enum":["event","system"],"example":"system"}},"required":["title","body"]},"UseActivationKeyDto":{"type":"object","properties":{"key":{"type":"string","example":"A1B2C3"}},"required":["key"]},"CreateColorDto":{"type":"object","properties":{"name":{"type":"string","example":"Blue"},"hex":{"type":"string","example":"#0D47A1"}},"required":["name","hex"]},"UpdateColorDto":{"type":"object","properties":{"name":{"type":"string","example":"Blue"},"hex":{"type":"string","example":"#0D47A1"}}},"CreateVehicleDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"plate":{"type":"string","example":"ABC1D23"},"year":{"type":"number","example":2024},"chassis":{"type":"string","example":"9BWZZZ377VT004251"},"document":{"type":"string","example":"12345678901"},"modelID":{"type":"number","example":3},"colorID":{"type":"number","example":5},"typeID":{"type":"number","example":1}},"required":["plate","year","chassis","document","modelID","colorID"]},"UpdateVehicleDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"plate":{"type":"string","example":"ABC1D23"},"year":{"type":"number","example":2024},"chassis":{"type":"string","example":"9BWZZZ377VT004251"},"document":{"type":"string","example":"12345678901"},"modelID":{"type":"number","example":3},"colorID":{"type":"number","example":5},"typeID":{"type":"number","example":1}}},"CreateVehicleBrandDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Volkswagen"}},"required":["name"]},"CreateVehicleModelDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Gol"},"brandID":{"type":"number","example":2}},"required":["name","brandID"]},"CreateVehicleTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"car"}},"required":["name"]},"UpdateVehicleTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"car"}}},"CreateInstallationDto":{"type":"object","properties":{}},"UpdateInstallationDto":{"type":"object","properties":{"typeID":{"type":"number","example":2},"order":{"type":"number","example":1},"assignedBy":{"type":"number","example":15}}},"CreateInstallationTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"tracker"}},"required":["name"]},"UpdateInstallationTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"tracker"}},"required":["name"]},"CreateUserTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"Standard"}},"required":["name"]},"UpdateUserTypeDto":{"type":"object","properties":{"name":{"type":"string","example":"Standard"}}},"MapPositionDeviceDto":{"type":"object","properties":{"id":{"type":"string","example":"tracker-1"},"order":{"type":"number","example":0},"isPrimary":{"type":"boolean","example":true},"type":{"type":"string","enum":["tracker","gateway","dome","handle_antenna","shield","tag"]},"deviceModel":{"type":"string","example":"TK103"},"lastUpdate":{"format":"date-time","type":"string","example":"2026-03-30T10:00:00.000Z"},"lat":{"type":"number","example":-23.5505},"lng":{"type":"number","example":-46.6333},"time":{"type":"number","example":1711792800000},"speed":{"type":"number","example":45},"moving":{"type":"boolean","example":true},"satellites":{"type":"number","example":8},"isPrecise":{"type":"boolean","example":true},"inputVoltCommon":{"type":"number","example":13.5},"batteryVoltCommon":{"type":"number","example":4.1},"signalStrength":{"type":"number","example":85},"networkType":{"type":"number","example":4},"hdopGps":{"type":"number","example":0.7},"snrGps":{"type":"number","example":72,"description":"Average GPS signal quality from the top satellites (0–100%)."},"registeredDeviceId":{"type":"number","example":123},"deviceVersion":{"type":"string","example":"v1.2.0"}},"required":["id","lastUpdate","lat","lng","speed","moving","satellites","isPrecise"]},"MapPositionsDto":{"type":"object","properties":{"vehicleId":{"type":"number","example":42},"time":{"type":"number","example":1711792800000},"identification":{"type":"string","example":"ABC-1234"},"deviceId":{"type":"string","example":"tracker-1"},"deviceType":{"type":"string","enum":["tracker","gateway","dome","handle_antenna","shield","tag"]},"deviceModel":{"type":"string","example":"TK103"},"lastUpdate":{"format":"date-time","type":"string","example":"2026-03-30T10:00:00.000Z"},"lat":{"type":"number","example":-23.5505},"lng":{"type":"number","example":-46.6333},"positionType":{"type":"string","enum":["vehicle","antenna"],"example":"vehicle","description":"Semantic map item type returned by the API. The wire format stays as a string code."},"moving":{"type":"boolean","example":true},"satellites":{"type":"number","example":8},"isPrecise":{"type":"boolean","example":true},"speed":{"type":"number","example":45},"direction":{"type":"number","example":180},"isOnline":{"type":"boolean","example":true},"plate":{"type":"string","example":"ABC-1234"},"vehicleType":{"type":"string","example":"car"},"vehicleColor":{"type":"string","example":"#1D4ED8"},"vehicleColorName":{"type":"string","example":"Blue"},"vehicleLabel":{"type":"string","example":"Volkswagen Gol"},"timestamp":{"type":"string","example":"2026-03-30T10:00:00.000Z"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/MapPositionDeviceDto"}},"rssi":{"type":"number","example":-68},"signalStrength":{"type":"number","example":90},"networkType":{"type":"number","example":4}},"required":["time","identification","deviceId","lat","lng","positionType"]},"MapColorReferenceDto":{"type":"object","properties":{"id":{"type":"number","example":1},"name":{"type":"string","example":"Blue"},"hex":{"type":"string","example":"#1D4ED8"}},"required":["id","name","hex"]},"MapEntityReferenceDto":{"type":"object","properties":{"id":{"type":"number","example":1},"name":{"type":"string","example":"Cargo"}},"required":["id","name"]},"MapVehicleTrailPointDto":{"type":"object","properties":{"deviceId":{"type":"string","example":"tracker-1"},"timestamp":{"format":"date-time","type":"string","example":"2026-03-30T10:00:00.000Z"},"lat":{"type":"number","example":-23.5505},"lng":{"type":"number","example":-46.6333},"speed":{"type":"number","example":45},"direction":{"type":"number","example":180},"time":{"type":"number","example":1711792800000},"deviceType":{"type":"string","enum":["tracker","gateway","dome","handle_antenna","shield","tag"]},"packetType":{"type":"string","example":"IGN. ON","description":"Protocol packet type string (`packtypestr`) when available."},"packetTypeCode":{"type":"number","example":1,"description":"Numeric protocol packet type (`packtype`) when available."},"packetParams":{"type":"string","example":"6,1729645000,-23.18506,-46.91299,80,1729645040,-23.18450,-46.91100,135","description":"Raw packparam from commomdt (event-specific parameters)."}},"required":["deviceId","timestamp","lat","lng","time"]},"MapVehicleLastRegisteredPositionDto":{"type":"object","properties":{"deviceId":{"type":"string","example":"tracker-1"},"deviceType":{"type":"string","enum":["tracker","gateway","dome","handle_antenna","shield","tag"]},"deviceModel":{"type":"string","example":"TK103"},"timestamp":{"type":"string","example":"2026-03-30T10:00:00.000Z"},"lastUpdate":{"format":"date-time","type":"string","example":"2026-03-30T10:00:00.000Z"},"lat":{"type":"number","example":-23.5505},"lng":{"type":"number","example":-46.6333},"time":{"type":"number","example":1711792800000},"speed":{"type":"number","example":45},"direction":{"type":"number","example":180},"moving":{"type":"boolean","example":true},"satellites":{"type":"number","example":8},"isPrecise":{"type":"boolean","example":true},"isOnline":{"type":"boolean","example":true}},"required":["deviceId","timestamp","lat","lng","time"]},"MapVehicleDetailsDto":{"type":"object","properties":{"vehicleId":{"type":"number","example":42},"time":{"type":"number","example":1711792800000},"identification":{"type":"string","example":"ABC-1234"},"deviceId":{"type":"string","example":"tracker-1"},"deviceType":{"type":"string","enum":["tracker","gateway","dome","handle_antenna","shield","tag"]},"deviceModel":{"type":"string","example":"TK103"},"lastUpdate":{"format":"date-time","type":"string","example":"2026-03-30T10:00:00.000Z"},"lat":{"type":"number","example":-23.5505},"lng":{"type":"number","example":-46.6333},"positionType":{"type":"string","enum":["vehicle","antenna"],"example":"vehicle","description":"Semantic map item type returned by the API. The wire format stays as a string code."},"moving":{"type":"boolean","example":true},"satellites":{"type":"number","example":8},"isPrecise":{"type":"boolean","example":true},"speed":{"type":"number","example":45},"direction":{"type":"number","example":180},"isOnline":{"type":"boolean","example":true},"plate":{"type":"string","example":"ABC-1234"},"vehicleType":{"type":"string","example":"car"},"vehicleColor":{"type":"string","example":"#1D4ED8"},"vehicleColorName":{"type":"string","example":"Blue"},"vehicleLabel":{"type":"string","example":"Volkswagen Gol"},"timestamp":{"type":"string","example":"2026-03-30T10:00:00.000Z"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/MapPositionDeviceDto"}},"rssi":{"type":"number","example":-68},"signalStrength":{"type":"number","example":90},"networkType":{"type":"number","example":4},"color":{"$ref":"#/components/schemas/MapColorReferenceDto"},"year":{"type":"string","example":"2024"},"chassis":{"type":"string","example":"9BWZZZ377VT004251"},"document":{"type":"string","example":"12345678901"},"model":{"$ref":"#/components/schemas/MapEntityReferenceDto"},"brand":{"$ref":"#/components/schemas/MapEntityReferenceDto"},"type":{"$ref":"#/components/schemas/MapEntityReferenceDto"},"trail":{"type":"array","items":{"$ref":"#/components/schemas/MapVehicleTrailPointDto"}},"lastRegisteredPosition":{"description":"Latest vehicle position considering all installed devices, regardless of any active device filter.","allOf":[{"$ref":"#/components/schemas/MapVehicleLastRegisteredPositionDto"}]},"trailMode":{"type":"string","enum":["points","sinceIgnition"],"example":"points","description":"Effective trail mode applied to the returned trail (may fall back to `points` when no ignition-on event is found)."},"ignitionOnAt":{"type":"string","example":"2026-03-30T08:15:00.000Z","description":"Timestamp of the last IGN. ON (packtype 1) used as the trail start when `trailMode` is `sinceIgnition`. Null when unavailable.","nullable":true}},"required":["time","identification","deviceId","lat","lng","positionType","trail"]},"CreateCommandDto":{"type":"object","properties":{}},"CreateDefaultCommandDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Request position"},"command":{"type":"string","example":"GETPOS"},"description":{"type":"string","example":"Requests the current device position"}},"required":["name","command"]},"UpdateDefaultCommandDto":{"type":"object","properties":{"statusID":{"type":"number","example":1,"default":1,"description":"Status ID to filter by (e.g., 1 for active). If not provided, no status filtering will be applied."},"name":{"type":"string","example":"Request position"},"command":{"type":"string","example":"GETPOS"},"description":{"type":"string","example":"Requests the current device position"}}},"CreateSimCardDto":{"type":"object","properties":{"iccid":{"type":"string","example":"8955051234567890123"},"phone":{"type":"string","example":"11999999999"},"operatorID":{"type":"number","example":1},"brokerID":{"type":"number","example":1},"companyID":{"type":"number","example":1,"description":"Required for master; ignored for company-scoped users"},"deviceID":{"type":"number","example":10,"description":"Optional device to attach on create"}},"required":["iccid","phone","operatorID","brokerID"]},"AssignSimCardsToDeviceDto":{"type":"object","properties":{"deviceID":{"type":"number","example":10},"simCardIDs":{"example":[1,2],"description":"Complete list of sim card IDs that must remain attached to the device. Missing IDs currently attached are detached to stock. Empty list detaches all.","type":"array","items":{"type":"number"}}},"required":["deviceID","simCardIDs"]},"UpdateSimCardDto":{"type":"object","properties":{"iccid":{"type":"string","example":"8955051234567890123"},"phone":{"type":"string","example":"11999999999"},"operatorID":{"type":"number","example":1},"brokerID":{"type":"number","example":1},"deviceID":{"type":"number","example":10,"description":"Optional device to attach on create"},"statusID":{"type":"number","example":1,"description":"Soft status (1=active, 2=inactive)"}}},"AttachSimCardDto":{"type":"object","properties":{"deviceID":{"type":"number","example":10}},"required":["deviceID"]},"CreateSimCardOperatorDto":{"type":"object","properties":{"name":{"type":"string","example":"Vivo"}},"required":["name"]},"UpdateSimCardOperatorDto":{"type":"object","properties":{"name":{"type":"string","example":"Vivo"}}},"CreateSimCardBrokerDto":{"type":"object","properties":{"name":{"type":"string","example":"Broker X"}},"required":["name"]},"UpdateSimCardBrokerDto":{"type":"object","properties":{"name":{"type":"string","example":"Broker X"}}},"ReportExportNotificationDto":{"type":"object","properties":{"readyTitle":{"type":"string","description":"Localized title when the export is ready","example":"Relatório pronto"},"readyBody":{"type":"string","description":"Localized body when ready. Placeholders: {fileName}, {rowCount}","example":"Seu export {fileName} está pronto ({rowCount} linhas)."},"failedTitle":{"type":"string","description":"Localized title when the export fails","example":"Falha no relatório"},"failedBody":{"type":"string","description":"Localized body when failed. Placeholder: {error}","example":"Não foi possível gerar o relatório: {error}"}}},"CreateReportExportDto":{"type":"object","properties":{"type":{"type":"string","enum":["tracking","events","commands","user_activity"]},"format":{"type":"string","enum":["xlsx","csv"]},"filters":{"type":"object","description":"Report filters (same shape as the interactive report query)"},"fields":{"description":"Optional field keys to include in the file","type":"array","items":{"type":"string"}},"lineLimit":{"type":"number","description":"Max rows to export. Omit or null for unlimited.","nullable":true},"notification":{"description":"Client-localized notification title/body (avoids English hardcoding on the API)","allOf":[{"$ref":"#/components/schemas/ReportExportNotificationDto"}]}},"required":["type","format","filters"]},"CreateDriverDto":{"type":"object","properties":{"name":{"type":"string","example":"Driver Name"},"cpf":{"type":"string","example":"12345678901"},"email":{"type":"string","example":"driver@knov.io"},"phone":{"type":"string","example":"11999999999"},"companyID":{"type":"number","example":1,"description":"Company to bind the driver to"},"roleID":{"type":"number","example":2,"description":"Role ID for the driver binding. Defaults to USER role."},"confirmExistingUser":{"type":"boolean","description":"Set to true to confirm reusing an existing user by CPF as a driver."}},"required":["name","cpf","phone","companyID"]},"UpdateDriverDto":{"type":"object","properties":{"name":{"type":"string","example":"Driver Name"},"email":{"type":"string","example":"driver@knov.io"},"phone":{"type":"string","example":"11999999999"}}},"CreateDriverLicenseDto":{"type":"object","properties":{"licenseNumber":{"type":"string","example":"12345678900"},"category":{"type":"string","example":"AB","enum":["A","B","C","D","E","AB","AC","AD","AE"]},"firstLicenseDate":{"format":"date-time","type":"string","example":"2015-03-15T00:00:00.000Z"},"expirationDate":{"format":"date-time","type":"string","example":"2027-03-15T00:00:00.000Z"},"observations":{"type":"string","example":"Additional notes"}},"required":["licenseNumber","category","firstLicenseDate","expirationDate"]},"UpdateDriverLicenseDto":{"type":"object","properties":{"licenseNumber":{"type":"string","example":"12345678900"},"category":{"type":"string","example":"AB","enum":["A","B","C","D","E","AB","AC","AD","AE"]},"firstLicenseDate":{"format":"date-time","type":"string","example":"2015-03-15T00:00:00.000Z"},"expirationDate":{"format":"date-time","type":"string","example":"2027-03-15T00:00:00.000Z"},"observations":{"type":"string","example":"Additional notes"}}},"DriverScheduleItemDto":{"type":"object","properties":{"dayOfWeek":{"type":"number","example":1,"description":"0=Sun, 1=Mon, ..., 6=Sat"},"startTime":{"type":"string","example":"08:00"},"endTime":{"type":"string","example":"18:00"},"isActive":{"type":"boolean","example":true}},"required":["dayOfWeek","startTime","endTime"]},"DriverScheduleBatchDto":{"type":"object","properties":{"items":{"description":"Complete weekly schedule. Omitted days are removed.","type":"array","items":{"$ref":"#/components/schemas/DriverScheduleItemDto"}}},"required":["items"]},"AssignVehicleDto":{"type":"object","properties":{"vehicleID":{"type":"number","example":1,"description":"Vehicle ID to assign"},"startDate":{"format":"date-time","type":"string","example":"2026-08-04T00:00:00.000Z","description":"Assignment start date. Defaults to now."}},"required":["vehicleID"]}}}}