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 aqui é exclusivamente em aspectos técnicos relevantes para integração B2B:

• modelo de autenticação
• isolamento multiempresa
• contratos e catálogos estáveis
• padrões de requisição e resposta
• canais de integração síncronos e fluxos assíncronos internos relevantes para a operação
• considerações operacionais para ambientes corporativos

Este documento não substitui a especificação OpenAPI publicada pela própria aplicação. Ele funciona como uma visão executiva e técnica para times de arquitetura, backend, integração, segurança e operação.

Visão Geral da Plataforma

A KNShield API é uma aplicação NestJS exposta via HTTP/JSON, com autenticação baseada em JWT e suporte a fluxos operacionais de monitoramento, gestão de ativos, usuários, empresas, dispositivos, instalações e eventos em tempo real.

Características técnicas relevantes:

• API REST com payloads JSON
• documentação OpenAPI/Swagger publicada pela própria aplicação
• autenticação principal por Bearer Token
• suporte a CORS, compression e helmet
• validação automática de payloads com transformação de tipos na borda HTTP
• arquitetura multiempresa com isolamento por companyID
• uso de Prisma como camada de persistência no banco operacional principal
• suporte complementar a telemetria/realtime e integrações internas por WebSocket e mensageria

Importante para clientes e integradores:

• RabbitMQ faz parte da infraestrutura interna da plataforma e não é exposto como contrato público direto para consumo externo
• quando um fluxo da plataforma depender de processamento assíncrono, o contrato público continua sendo a própria API HTTP/WebSocket e seus payloads documentados

Ambientes e Exposição

Configuração pública atual observada na aplicação:

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

A raiz pública da aplicação agora funciona como portal de documentação, enquanto o Swagger fica publicado em rota dedicada.

Implicação prática para integradores:

• o ponto de entrada recomendado para onboarding é o portal público de documentação
• a descoberta de endpoints e schemas deve começar pelo documento OpenAPI gerado pela aplicação
• o Swagger UI deve ser usado para autenticação manual, inspeção de payloads e testes exploratórios
• este guia deve ser usado para alinhar decisões de integração, segurança, tenancy e operação

Autenticação e Autorização

Autenticação

O mecanismo principal de autenticação é JWT via header Authorization.

Formato esperado:

Authorization: Bearer <jwt>

Fluxos públicos relevantes:

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

Fluxos autenticados relevantes:

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

Autorização

A autorização é orientada por permissões e papel do usuário autenticado.

Conceitos relevantes:

• usuários tenant-scoped: usuários limitados ao contexto da própria empresa
• permissões por módulo e ação: leitura, criação, atualização, exclusão ou ações específicas

Formato técnico atual de permissões emitidas e persistidas:

• permissions são representadas como mapa por módulo com arrays de ações permitidas
• exemplo: {"company": ["read", "update"], "user": ["read"]}
• a plataforma não depende mais de estruturas paralelas como { action, value } nem de mapas achatados específicos de frontend

Para clientes e parceiros, isso significa que autenticação válida não implica acesso global. O token recebido define escopo e permissões efetivos de operação.

Modelo Multiempresa

A KNShield API deve ser tratada como plataforma multi-tenant.

Regras de integração relevantes:

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

Consequência prática:

• integrações devem ser desenhadas assumindo segregação rígida de dados por empresa
• qualquer consumo de listagem, detalhe, atualização ou evento deve respeitar o tenant do token utilizado

Padrões de Payload e Validação

A aplicação usa validação e transformação na borda HTTP. Isso é relevante para clientes porque o backend normaliza determinados campos antes da persistência e da regra de negócio.

Exemplos já estabilizados na base atual:

• CPF é tratado como valor normalizado
• CNPJ corporativo também é tratado como valor normalizado
• email é tratado como identificador normalizado
• telefone é validado e normalizado
• CEP e UF são normalizados nos contratos de endereço
• statusID em criações pode ser opcional quando o recurso nasce ativo por padrão
• no módulo company, o documento da empresa é persistido em formato canônico

Recomendação para integradores:

• enviar dados semanticamente corretos, mesmo quando o backend normalize parte do conteúdo
• não depender de comportamento implícito não documentado fora do OpenAPI e das regras aqui descritas

Catálogos e Contratos Canônicos

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

StatusType

O catálogo status-type possui semântica canônica já amarrada na base atual:

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

Implicações para clientes:

• integrações podem tratar esses estados como catálogo funcional conhecido
• ainda assim, a API continua sendo a fonte oficial para leitura do catálogo
• o endpoint de status-type pode usar cache do lado do servidor para otimizar leitura repetida

UserRole

O catálogo user-role também possui contrato canônico alinhado à migration inicial e deve ser tratado como catálogo estável publicado pela própria API.

Implicações para clientes:

• integrações autenticadas podem tratar esses papéis como catálogo estável da plataforma
• a autorização efetiva continua dependente do token e das permissões emitidas para o usuário autenticado
• leituras repetidas desse catálogo podem ser servidas por cache do lado da API sem alterar a semântica funcional

UserType

O catálogo user-type também possui contrato canônico alinhado à migration inicial e deve ser consumido pela API como fonte de verdade para classificação operacional.

Implicações para clientes:

• integrações podem tratar esses tipos como catálogo estável para classificação operacional de usuários
• o catálogo continua sendo consultável pela própria API quando o cliente quiser sincronização explícita
• leituras repetidas desse catálogo também podem ser atendidas com cache no lado do servidor

Superfícies Atualmente Documentadas

Este guia deve registrar apenas capacidades já preenchidas durante a refatoração dos módulos expostos pela API. No estado atual, os principais blocos já descritos para consumo técnico são:

• auth: autenticação JWT, refresh de credenciais e escopo do usuário autenticado
• company: gestão empresarial com documento, email e telefone validados na borda
• user: identidade do usuário com dados normalizados e operações de gestão por empresa
• address: contrato de endereço único com normalização explícita de CEP e UF
• status-type, user-role e user-type: catálogos operacionais canônicos
• parameters e default-permissions: configuração técnica de eventos e permissões padrão por role
• activation-key: geração, consulta e consumo de chaves operacionais
• device: gestão do cadastro principal de dispositivos, lookup operacional de telemetria e separação entre catálogo interno e dados externos de posicionamento
• device-company-register e fcm-token: vínculos operacionais entre empresa, dispositivo e contexto de notificação
• vehicle: gestão do agregado principal de veículos e dos catálogos de marca, modelo e tipo, com escopo por empresa no agregado principal
• event, notification e command: leitura operacional, envio assíncrono e histórico de execução
• user-activity: trilha de auditoria para ações autenticadas e falhas de segurança associadas ao ator resolvido
• map: overview operacional e detalhe de ativos com trilha calculada no backend e consistência entre REST e realtime

Quando novos módulos forem concluídos durante a refatoração, este guia deve ser ampliado com o contrato externo correspondente, sem registrar histórico interno de migração.

Mensageria e Processamento Assíncrono

A plataforma utiliza mensageria internamente para alguns fluxos operacionais, especialmente em comandos e notificações.

Pontos relevantes para clientes:

• RabbitMQ não deve ser tratado como superfície pública de integração B2B da KNShield API
• o contrato externo continua sendo a API HTTP, a documentação OpenAPI e, quando aplicável, os canais de WebSocket publicados pela própria aplicação
• respostas assíncronas, histórico de comandos e efeitos observáveis de notificações devem ser acompanhados pelos endpoints e payloads expostos pela API, sem dependência direta das filas internas

Consequência prática:

• integradores não devem acoplar soluções externas a nomes de fila, topology AMQP, exchanges ou consumers internos da plataforma
• qualquer necessidade de processamento assíncrono deve ser tratada a partir dos endpoints oficiais e dos estados retornados pela API

Dispositivos

O módulo device expõe o cadastro principal de dispositivos e também endpoints operacionais que projetam telemetria externa já agregada pela API.

Comportamentos relevantes para integradores:

• o cadastro de dispositivos permanece no banco operacional principal da API, enquanto últimas posições, rotas e packet data entram por integrações internas dedicadas
• a listagem principal de dispositivos aplica escopo por empresa de acordo com o contexto autenticado do token
• criação e atualização de vínculo com empresa validam explicitamente a permissão do usuário sobre a empresa informada
• o endpoint de dispositivos desconhecidos retorna apenas emissores detectados pela telemetria externa que ainda não possuem cadastro local correspondente
• o histórico de rota diferencia dispositivos do tipo tag e dispositivos rastreadores, mantendo a decisão dentro da API

Implicações práticas:

• integrações devem tratar a API como fonte oficial do cadastro de dispositivos e de sua associação organizacional
• integrações de monitoramento devem consumir os endpoints HTTP da API para telemetria consolidada, em vez de depender diretamente do packet consumer
• identificadores externos de dispositivo devem ser tratados como case-insensitive para leitura operacional, mas o backend persiste o valor normalizado de forma consistente

Veículos

O módulo vehicle expõe tanto o agregado principal de veículos quanto os catálogos operacionais de marca, modelo e tipo.

Comportamentos relevantes para integradores:

• o agregado principal de veículos é tenant-scoped por empresa de acordo com o contexto autenticado do token
• criação de veículo aplica statusID = active por padrão quando o campo não é enviado
• a API mantém endpoints separados para vehicle, vehicle-brand, vehicle-model e vehicle-type, reduzindo ambiguidade entre cadastro operacional e catálogos auxiliares
• a leitura de última posição do veículo depende dos dispositivos instalados e da telemetria interna agregada pela API; o packet consumer não é exposto como contrato público externo
• o endpoint de dispositivos disponíveis para instalação respeita o escopo das empresas ativas vinculadas ao veículo

Implicações práticas:

• integrações de cadastro devem tratar o veículo como recurso principal com vínculo organizacional implícito no contexto autenticado
• integrações de catálogo podem sincronizar marcas, modelos e tipos separadamente, sem assumir que todos compartilham o mesmo ciclo de vida do agregado principal
• integrações de monitoramento devem consultar payloads da API, não tabelas ou serviços internos de telemetria

Permissões e Defaults

Os perfis default de permissão são controlados no backend por role operacional, usando o mesmo formato técnico de module -> action[] consumido por autenticação e autorização.

Consequências práticas para integradores:

• respostas autenticadas e payloads derivados de contexto do usuário carregam permissões já prontas para consumo por módulo e ação
• integrações não devem inferir permissões a partir de labels ou estruturas de UI; o contrato técnico é o payload retornado pela API
• mudanças estruturais de permissões passam por migrations versionadas, reduzindo deriva entre defaults persistidos e permissões efetivas emitidas no token

Observação atual sobre permissões:

• color agora é um módulo de permissão independente e não deve mais ser tratado como implicitamente coberto por vehicle
• clientes que armazenam em cache ou interpretam payloads de permissão devem verificar color explicitamente ao habilitar funcionalidades de gerenciamento do catálogo de cores

Parâmetros de Eventos e Alertas

Os parâmetros padrão e específicos por vínculo usuário/empresa foram consolidados em um módulo próprio de parameters.

Características relevantes para consumo técnico:

• o contrato atual usa events como coleção principal
• cada evento pode expor metadados como identificador, nome técnico, label, estado (value), categoria e visibilidade (show)
• o catálogo segue a semântica seeded por migrations, evitando divergência entre testes, defaults persistidos e payloads retornados pela API

Para integradores, isso reduz a chance de drift entre configurações default, personalizações por usuário e documentação operacional.

Integração em Tempo Real

A plataforma também possui canais de realtime via WebSocket em áreas operacionais específicas.

Pontos relevantes:

• há gateways dedicados para casos de uso em tempo real
• autenticação e autorização do canal não devem ser presumidas como equivalentes a uma chamada HTTP anônima
• payloads de localização e trilha podem ser compostos a partir de múltiplas fontes internas
• o módulo map consome posições persistidas e trilhas históricas por meio de integrações internas dedicadas, sem expor detalhes do consumer como contrato público da API
• leituras de telemetria usadas por device e fluxos correlatos também passam por integrações internas da API, mantendo o packet consumer como dependência de infraestrutura e não como contrato público externo

Recomendação:

• consumir realtime apenas quando o caso exigir latência baixa ou atualização contínua
• usar REST/OpenAPI como fonte principal para onboarding e integração inicial
• tratar realtime como canal especializado de operação, não como substituto universal da API HTTP

Tratamento de Erros

A API usa exceções HTTP e mapeamento centralizado de erros.

Na prática, clientes devem estar preparados para pelo menos:

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

Recomendação:

• implementar retry apenas para falhas transitórias apropriadas
• não usar retry cego para 4xx
• registrar correlação entre request, tenant, usuário técnico e resposta recebida

Requisitos para Integração Corporativa

Para implantação em clientes empresariais, recomenda-se que o integrador considere desde o início:

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

Boas Práticas de Consumo

• usar a documentação OpenAPI publicada pela aplicação como referência primária de endpoint, parâmetros e schema
• tratar catálogos operacionais como contratos conhecidos, mas sempre sincronizáveis pela própria API
• não acoplar integrações a comportamentos implícitos não documentados
• respeitar o modelo de escopo multiempresa em todas as integrações
• isolar credenciais por cliente, empresa ou ambiente sempre que possível
• revisar periodicamente permissões e superfícies expostas para cada integração

Recomendação de Onboarding para Empresas Integradoras

Sequência sugerida para adoção da API:

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

Observação Final

Este guia deve evoluir junto com a API. Sempre que um módulo relevante for concluído na refatoração e fizer parte da superfície pública, a documentação técnica correspondente deve ser adicionada ou ampliada com foco no contrato atual de consumo.