# 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: ```http Authorization: Bearer ``` 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.