KNShield API - Guia Técnico para Clientes e Integradores

Objetivo

Este documento apresenta a base técnica da KNShield API para empresas que irão consumir, integrar, distribuir ou operar soluções sobre a plataforma.

O foco é o contrato público de integração:

• autenticação e autorização
• isolamento multiempresa
• catálogos e payloads estáveis
• padrões de requisição e resposta
• canais HTTP e WebSocket publicados pela API
• considerações operacionais para ambientes corporativos

Este documento não substitui a especificação OpenAPI. Use-o como visão técnica de onboarding; use o OpenAPI como referência de endpoints, parâmetros e schemas.

Visão Geral da Plataforma

A KNShield API é uma API REST/JSON para monitoramento, gestão de ativos, usuários, empresas, dispositivos, instalações e atualizações em tempo real.

Características relevantes para integração:

• API REST com payloads JSON
• documentação OpenAPI/Swagger publicada pela própria aplicação
• autenticação por JWT Bearer e por API Key
• validação de payloads na entrada da API
• isolamento multiempresa por empresa autenticada
• telemetria e posição disponíveis via endpoints HTTP e WebSocket documentados

O contrato público de integração é a API HTTP/WebSocket e seus payloads. Processamentos assíncronos, quando existirem, continuam encapsulados por esses endpoints e estados retornados.

Ambientes e Exposição

Ambientes e rotas públicas:

• ambiente local: http://localhost:3000
• ambiente produtivo: https://api.knsh.com.br
• portal de documentação: /
• Swagger UI: /swagger
• OpenAPI JSON: /swagger/json
• guia técnico HTML: /docs/guide
• guia técnico Markdown: /docs/guide.md

Recomendações de onboarding:

• comece pelo portal de documentação
• descubra endpoints e schemas pelo OpenAPI
• use o Swagger UI para autenticação manual e testes exploratórios
• use este guia para alinhar autenticação, tenancy e operação

Autenticação e Autorização

Mecanismos de Autenticação

A plataforma aceita dois mecanismos de autenticação:

Regras de precedência:

• Se Authorization: Bearer estiver presente, a autenticação é JWT. Token inválido retorna 401 imediatamente, sem tentar API Key.
• Se apenas X-Api-Key estiver presente, a autenticação é por API Key.
• Se nenhum dos dois estiver presente, a API retorna 401 Unauthorized.
• Endpoints públicos não exigem autenticação.

Autenticação JWT

Formato esperado:

Authorization: Bearer <jwt>

Fluxos públicos:

• POST /auth/login
• POST /auth/forgot-password
• POST /auth/reset-password

Fluxos autenticados:

• PATCH /auth/password
• GET /auth/refresh-token

Autorização

A autorização usa o papel e as permissões do usuário autenticado.

Conceitos relevantes:

• usuários de empresa operam apenas no escopo da própria empresa
• permissões são organizadas por módulo e ação (leitura, criação, atualização, exclusão e ações específicas)
• autenticação por API Key identifica a empresa e restringe o acesso aos dados dela, sem papéis ou permissões granulares de usuário

Formato de permissions no contexto autenticado:

• mapa por módulo com arrays de ações permitidas
• exemplo: {"company": ["read", "update"], "user": ["read"], "color": ["read"]}

Autenticação válida não implica acesso global. O token define o escopo e as permissões efetivas da operação.

Autenticação por API Key para Integrações

Integrações server-to-server podem autenticar apenas com X-Api-Key, sem login, JWT ou refresh.

Como funciona

X-Api-Key: knshield_<chave_da_empresa>

• A chave identifica a empresa e restringe o acesso aos dados dela
• Não é necessário enviar Authorization: Bearer
• A chave plana é exibida apenas no momento da geração; depois disso não é recuperável
• A plataforma não armazena a chave em texto plano

Verificar conectividade

GET /integration/me
X-Api-Key: knshield_<chave>

Resposta 200:

{ "companyId": 7, "companyName": "Transportadora Exemplo Ltda" }

Use esse endpoint no startup da integração para validar a configuração.

Endpoints acessíveis via API Key

A API Key cobre monitoramento e integração. Endpoints de gestão (usuários, veículos, dispositivos etc.) exigem JWT com permissões.

Tentativas de acessar endpoints de gestão com API Key retornam 403 Forbidden.

Escopo da API Key

Com API Key, a integração opera no escopo da empresa identificada pela chave. Operações que dependem de usuário, papel ou permissões granulares exigem JWT.

Segurança e boas práticas

• Nunca expor a API Key em frontend ou repositório público
• Armazenar em variáveis de ambiente ou gerenciadores de secrets
• Rotacionar periodicamente em produção
• Em caso de comprometimento, revogar e regenerar pelo painel administrativo

Modelo Multiempresa

A KNShield API é multi-tenant.

Regras relevantes:

• empresas clientes acessam apenas os próprios recursos
• recursos administrativos globais permanecem restritos a contextos com permissão apropriada
• clientes não devem inferir ou forçar escopo apenas por IDs enviados no request
• a API é a fonte de verdade para escopo, posse e autorização

Consequência prática:

• desenhe integrações com segregação rígida de dados por empresa
• listagens, detalhes, atualizações e eventos devem respeitar o tenant do token utilizado

Padrões de Payload e Validação

A API valida e normaliza campos na entrada. Isso importa porque valores como documento, email e telefone podem ser persistidos em formato canônico.

Exemplos estabilizados:

• CPF, CNPJ, email e telefone são normalizados
• CEP e UF são normalizados nos contratos de endereço
• em criações, statusID pode ser omitido quando o recurso nasce ativo por padrão
• o documento da empresa é persistido em formato canônico

Recomendações:

• envie dados semanticamente corretos, mesmo quando a API normalize parte do conteúdo
• não dependa de comportamentos não documentados fora do OpenAPI e deste guia

Convenção de Timestamps

Para datas e horas serializadas pela API:

• timezone padrão: America/Sao_Paulo
• formato de saída: ISO 8601 com offset explícito
• exemplo: 2026-04-07T12:35:00.000-03:00

Entrada (startDate / endDate em query)

• com offset ou Z → instante absoluto (2026-07-24T16:41:00.000Z, 2026-07-24T13:41:00.000-03:00)
• sem timezone (ex.: 2026-07-24T13:41) → horário de parede em America/Sao_Paulo
• clientes web no Brasil podem enviar o valor do input local sem converter para UTC

Implicações:

• não assumir saída em UTC com sufixo Z
• interpretar sempre o offset retornado pela API
• evitar parsing baseado em substring fixa de timezone

Quando um campo temporal estiver presente em payloads de leitura operacional, trate-o como horário já formatado no timezone padrão da API, salvo documentação específica em contrário.

Catálogos e Contratos Canônicos

Alguns catálogos operacionais devem ser tratados como contratos estáveis.

StatusType

Semântica canônica de status-type:

• 1 = active
• 2 = inactive
• 3 = pending

Implicações:

• integrações podem tratar esses estados como catálogo conhecido
• a API continua sendo a fonte oficial para leitura do catálogo

UserRole

Papéis canônicos de sistema: master, admin e user. Também existem papéis custom por empresa.

Modelo de autorização:

• papéis de sistema são globais; o template de permissões deles só pode ser alterado por master
• papéis custom pertencem a uma empresa; admin da empresa (e master) podem criar, renomear, editar o template e remover quando não estiver em uso
• nomes master / admin / user são reservados
• permissões efetivas do usuário ficam no vínculo usuário-empresa; permissionsOverride=true indica override manual
• alterações de permissão passam a valer no JWT após novo login ou refresh
• GET /permissions/catalog devolve modules, actions e required (conjunto base: auth.login, device.read, self.read). Esses grants base devem ser tratados como travados em UIs de gestão
• o módulo event autoriza a listagem de eventos (GET /event); notifications cobre push e histórico de notificações

Endpoints relevantes:

Implicações:

• trate os papéis canônicos como catálogo estável
• a autorização efetiva continua dependente do token e das permissões emitidas
• em gestão de acesso, prefira roleID e /user-role/:id/permissions

UserType

O catálogo user-type classifica usuários operacionalmente e deve ser consumido pela API como fonte de verdade.

Implicações:

• trate esses tipos como catálogo estável
• sincronize pela API quando precisar de cópia local explícita

Superfícies Públicas Principais

Principais áreas da superfície pública:

• auth: autenticação JWT, refresh e escopo do usuário autenticado
• integration: conectividade e autenticação server-to-server via API Key
• company: gestão empresarial
• user: identidade e gestão de usuários por empresa
• address: endereço com normalização de CEP e UF
• status-type, user-role e user-type: catálogos operacionais
• parameters, default-permissions e permissions/catalog: eventos e vocabulário/templates de permissão
• activation-key: geração, consulta e consumo de chaves operacionais
• device: cadastro de dispositivos e leitura operacional de telemetria
• device-company-register e fcm-token: vínculos empresa/dispositivo e notificação push
• sim-card: inventário de chips por empresa e vínculo opcional a dispositivos
• vehicle: veículos e catálogos de marca, modelo e tipo
• event, notification e command: leitura operacional, envio e histórico
• user-activity: auditoria de ações autenticadas
• overview: visão consolidada da home operacional
• map: posições, detalhe de ativos e trilha
• driver: motoristas, CNH, escala de trabalho e vínculo com veículos

Consulte sempre o OpenAPI para a lista completa e atualizada de endpoints.

Driver

O módulo driver gerencia motoristas como um tipo especializado de usuário (typeID=3),

com dados de CNH, escala semanal e atribuição de veículos.

Segregação User/Driver:

• GET /user não retorna motoristas (filtra typeID !== 3)
• GET /driver retorna apenas motoristas (typeID === 3)
• Motoristas são criados exclusivamente via POST /driver, não via /user

Vínculo duplo (admin + motorista):

Uma mesma pessoa pode ter dois vínculos na mesma empresa:

um como usuário administrativo e outro como motorista.

A API trata isso como dois registros UserCompanyRegister distintos

(@@unique([userID, companyID, typeID])).

Motorista não tem acesso à plataforma:

O registro de motorista não cria credenciais de autenticação (Auth).

O e-mail é opcional para motoristas.

CNH (DriverLicense):

Escala de trabalho (DriverSchedule):

Escala semanal recorrente com dias da semana (0=Dom, 6=Sáb) e horários.

Alertas de vencimento da CNH:

Um job diário (08:00) verifica CNHs com vencimento em 30, 15, 7 e 1 dias

e notifica os administradores da empresa via push (FCM).

O tipo de notificação é driver_license_expiry (categoria system).

Endpoints principais:

Overview Operacional

O módulo overview expõe a visão consolidada da home operacional.

Pontos relevantes:

• o endpoint aceita período explícito para telemetria agregada
• campos temporais públicos seguem a convenção de timestamp da API (America/Sao_Paulo)
• generatedAt, period.startDate, period.endDate e campos como happenedAt são ISO 8601 com offset
• a timeline e a distribuição de tipos de pacote do período representam contagem de registros válidos no intervalo consultado
• indicadores de snapshot representam o estado mais recente conhecido dos dispositivos, separados da leitura histórica do período

Processamento Assíncrono

Alguns fluxos, como comandos, notificações e exportações, podem concluir de forma assíncrona.

Para o integrador:

• acompanhe o resultado pelos endpoints e estados públicos da API
• use o status/histórico documentados no OpenAPI

Dispositivos

O módulo device cobre o cadastro de dispositivos e leituras operacionais de telemetria.

Pontos relevantes:

• a listagem de dispositivos respeita o escopo da empresa autenticada
• GET /device e GET /device/by-id/:id incluem packetData com última telemetria processada (GPS, sinal, bateria e isOnline)
• limiares de online: tracker 5 min; demais tipos 30 min
• criação e atualização de vínculo com empresa validam a permissão sobre a empresa informada
• dispositivos desconhecidos são emissores detectados na telemetria que ainda não possuem cadastro correspondente
• identificadores externos de dispositivo são tratados como case-insensitive na leitura operacional

Rotas, trilhas e relatórios

• GET /device/tracking-report retorna pacotes de telemetria para diagnóstico; exige permissão history:report
• informe exatamente um de deviceId (id externo) ou vehicleId
• com vehicleId, a consulta considera os dispositivos cuja instalação no veículo cobriu o período informado
• paginação via page/limit, ou all=true para o período completo
• ordenação opcional via sortBy (timestamp | deviceId | lat | lng | speed | moving | packetType) e sortDir (asc | desc); default timestamp asc
• filtro opcional packetTypes com códigos de tipo de pacote separados por vírgula (catálogo 0–34, ex.: packetTypes=3,4,20); omitido = todos os tipos
• cada linha traz campos resumidos (timestamp, coords, speed, moving, packetType), dataSummary e data completo
• moving segue a mesma regra do mapa: commomdt.movdt > 0 ou spdgps > 0 (km/h) — alguns firmwares deixam movdt em 0 mesmo em movimento
• GET /device/route/:deviceId aceita cleanStops (default true) para reduzir oscilação GPS enquanto o ativo está parado
• GET /map/vehicles/:vehicleId aceita cleanStops (default true) na trilha retornada
• GET /map/vehicles/:vehicleId aceita trailMode (points | sinceIgnition, default points)
• em points, a trilha usa a janela padrão de pontos
• em sinceIgnition, a trilha começa no último evento de ignição ligada encontrado na janela suportada; a resposta inclui trailMode efetivo e ignitionOnAt (ISO ou null quando houver fallback)
• sem deviceIds, a trilha considera a cadeia de instalações do veículo na janela consultada, inclusive dispositivos já substituídos; a posição ao vivo continua baseada apenas em instalações ativas
• pontos da trilha podem incluir packetType / packetTypeCode quando disponíveis
• o WebSocket subscribe-vehicle aceita o mesmo trailMode

Exportações e notificações

• exportações grandes: POST /report-export (job assíncrono)
• tipos: tracking, events, commands, user_activity
• formatos: xlsx, csv
• para tracking, filters.cleanStops (default true) reduz oscilação em pontos parado antes de gerar o arquivo
• status em GET /report-export/:id; download em GET /report-export/:id/file
• ao concluir, a API emite notificação de sistema (category=system, notificationType=report_export_ready)
• o create aceita notification (readyTitle/readyBody/failedTitle/failedBody) com placeholders {fileName}, {rowCount}, {error}
• GET /notification aceita filtro category=event|system
• GET /notification/unread-counts retorna contagens de não lidas

Chips (SimCard)

O módulo sim-card gerencia o inventário de chips SIM da empresa e o vínculo opcional com dispositivos.

Pontos relevantes:

• campos obrigatórios: iccid (único), phone, operatorID, brokerID e companyID (resolvido pelo contexto autenticado; master deve informar companyID)
• deviceID opcional: null = estoque; preenchido = vinculado ao dispositivo
• um dispositivo pode ter vários chips ativos ao mesmo tempo
• POST /sim-card/:id/attach vincula sem desativar outros chips do device
• POST /sim-card/:id/detach devolve o chip ao estoque
• GET /sim-card/stock lista chips ativos sem dispositivo
• GET /sim-card/available-for-device/:deviceID lista estoque elegível para o device
• POST /sim-card/assign-to-device define o conjunto completo de chips do device ({ deviceID, simCardIDs[] }): IDs omitidos são desvinculados; lista vazia remove todos
• exclusão é lógica (statusID = inactive) e desvincula o dispositivo
• catálogos auxiliares: sim-card-operator e sim-card-broker
• o payload de device inclui simCards[] com os chips ativos vinculados
• usuários de empresa operam apenas chips da própria empresa; attach/assign exige device na mesma empresa do chip

Implicações práticas:

• trate chip como recurso de inventário independente do cadastro de device
• para vínculo device↔SIM, prefira available-for-device + assign-to-device
• sincronize operadora e broker pelos endpoints de catálogo antes de criar o chip

Veículos

O módulo vehicle cobre o cadastro de veículos e os catálogos de marca, modelo e tipo.

Pontos relevantes:

• veículos são tenant-scoped pela empresa do contexto autenticado
• criação aplica statusID = active por padrão quando o campo é omitido
• endpoints separados para vehicle, vehicle-brand, vehicle-model e vehicle-type
• a última posição do veículo depende dos dispositivos instalados e da telemetria consolidada pela API
• dispositivos disponíveis para instalação respeitam o escopo das empresas ativas vinculadas ao veículo

Implicações práticas:

• trate o veículo como recurso principal com escopo organizacional no token
• sincronize marcas, modelos e tipos como catálogos auxiliares
• consuma monitoramento pelos endpoints públicos da API

Permissões e Defaults

Perfis default de permissão usam o formato module -> action[].

Consequências práticas:

• respostas autenticadas carregam permissões prontas para consumo por módulo e ação
• não infira permissões a partir de labels de UI; o contrato é o payload da API
• color é um módulo de permissão próprio; funcionalidades do catálogo de cores exigem grants explícitos em color
• mutações de catálogos de plataforma (color, marcas/modelos/tipos de veículo, fabricantes/tipos/modelos de dispositivo, operadoras/brokers de SIM, cargos/tipos de usuário e default-command) exigem contexto master, além das permissões de módulo
• papéis canônicos de sistema não podem ser renomeados ou removidos; papéis custom por empresa são gerenciáveis via API
• tipos canônicos de user-type não podem ser atualizados nem removidos via API

Comandos Padrão (default-command)

Catálogo de templates para seleção ao enviar comando a um dispositivo.

Contrato:

• GET /default-command e GET /default-command/:id — leitura para quem possui default-command:read, command:read ou command:send
• query opcional activeOnly=true retorna apenas templates ativos
• POST /default-command, PATCH /default-command/:id, DELETE /default-command/:id — mutações restritas a master; delete inativa o registro
• payload de criação/atualização: name, command, description?, statusID?
• o envio operacional continua em POST /command com o campo command já resolvido

Parâmetros de Eventos e Alertas

O módulo parameters concentra parâmetros padrão e específicos por vínculo usuário/empresa.

Pontos relevantes:

• o contrato usa events como coleção principal
• cada evento pode expor identificador, nome técnico, label, estado (value), categoria e visibilidade (show)
• sincronize o catálogo pela API para evitar drift entre defaults e personalizações

Integração em Tempo Real

A plataforma publica canais WebSocket para atualização operacional.

Pontos relevantes:

• autenticação do canal é obrigatória
• o gateway /location-stream aceita no handshake Socket.io:
• JWT: auth: { token: '<jwt>' } ou header Authorization: Bearer <jwt>
• API Key: auth: { apiKey: '<chave>' }
• payloads de localização e trilha são entregues já consolidados pela API

Recomendações:

• use realtime quando precisar de baixa latência ou atualização contínua
• use REST/OpenAPI como base de onboarding e integração inicial
• com API Key, conecte o WebSocket com auth: { apiKey } no handshake

Tratamento de Erros

Clientes devem estar preparados para:

• 400 Bad Request — payload inválido ou regra de domínio violada
• 401 Unauthorized — autenticação inválida, ausente ou expirada
• 403 Forbidden — operação fora da permissão ou escopo
• 404 Not Found — recurso inexistente
• 409 Conflict — violação de unicidade
• 5xx — falha interna ou indisponibilidade temporária

Recomendações:

• retry apenas para falhas transitórias apropriadas
• não usar retry cego para 4xx
• correlacionar request, tenant e resposta recebida

Requisitos para Integração Corporativa

Considere desde o início:

• gestão segura de JWT e chaves de API
• separação entre homologação e produção
• observabilidade de chamadas, erros e latência
• rotação de credenciais
• gestão de escopo por empresa e por papel
• versionamento do cliente para payloads consumidos
• testes automatizados de contrato nos endpoints críticos

Boas Práticas de Consumo

• use o OpenAPI como referência primária de endpoint, parâmetros e schema
• trate catálogos operacionais como contratos conhecidos e sincronizáveis pela API
• não acoplar integrações a comportamentos não documentados
• respeite o modelo multiempresa em todas as integrações
• isole credenciais por cliente, empresa ou ambiente
• revise periodicamente permissões e superfícies expostas

Recomendação de Onboarding para Empresas Integradoras

1. validar acesso ao ambiente e à documentação OpenAPI
2. alinhar autenticação e credenciais técnicas
3. mapear o tenant e o escopo funcional da integração
4. integrar catálogos e cadastros-base
5. integrar fluxos operacionais e, por fim, realtime quando necessário
6. formalizar monitoramento, rotação de credenciais e testes de regressão

Observação Final

Este guia deve evoluir com a API. Sempre que uma superfície pública relevante mudar, atualize a documentação com o contrato atual de consumo.