Portal Técnico KNShield

KNShield API - Sistema de Monitoramento e Controle

API corporativa para autenticação, multiempresa, gestão de ativos, monitoramento operacional e integração em tempo real.

Abrir Swagger UI Guia Técnico de Integração OpenAPI JSON

Versão publicada v1.3.10

Visibilidade atual Public view

OwnerOnly and master-specific business rules are hidden in this public documentation view.

Acesso rápido

Autenticação JWT com controle granular de permissões.
Autenticação por API Key para integrações server-to-server sem gerenciamento de sessão.
Isolamento multiempresa e escopo operacional por tenant.
Catálogos canônicos como status-type com semântica estável.
Monitoramento operacional, ativos, instalações e telemetria.
Integração REST, WebSocket (JWT e API Key) e fluxos administrativos de API key.
Mensageria interna tratada como infraestrutura da plataforma, não como contrato público externo.

Política de Exposição da Documentação

OwnerOnly and master-specific business rules are hidden in this public documentation view.

Ambientes Conhecidos

Dev http://localhost:3000
Production https://api.knsh.com.br

Artefatos de Documentação

Swagger UI Interface interativa para descoberta de endpoints, autenticação e testes manuais.
OpenAPI JSON Contrato técnico para automação, geração de SDKs e validação de schema.
Guia Técnico HTML Visão orientada a empresas integradoras, arquitetura e operação da API.
Guia Técnico Markdown Versão textual para distribuição, versionamento e revisão documental.

Fluxo Recomendado de Onboarding

01 Comece pelo portal público para entender o mapa geral da plataforma.
02 Use o Swagger UI para autenticar e validar os endpoints reais publicados.
03 Consuma o OpenAPI JSON em automações, SDKs e testes de contrato.
04 Para integrações server-to-server, use API Key no header X-Api-Key — verifique com GET /integration/me.
05 Use o guia técnico para alinhar tenancy, segurança e operação com o cliente.

Portal de Documentação

Ponto de entrada para clientes, integradores e times técnicos navegarem entre visão executiva, guia técnico e contrato OpenAPI.

/swagger

Swagger UI

Interface interativa para autenticação, exploração de endpoints e validação manual de requests.

/swagger/json

OpenAPI JSON

Contrato estruturado para geração de SDKs, automação de testes e validação de schema.

/docs/guide

Guia Técnico HTML

Leitura orientada a arquitetura, segurança, tenancy e operação para integrações corporativas.

Integração Server-to-Server (API Key)

Sistemas externos como o knaccess autenticam via `X-Api-Key` no header — sem login, JWT ou sessão. A chave identifica a empresa e restringe o acesso aos dados dela. Endpoints disponíveis: `GET /integration/me`, `GET /integration/devices/:deviceId/trail`, `GET /map/positions`, `GET /map/vehicles/:vehicleId` e WebSocket `/location-stream`. Use `GET /integration/me` para validar a conectividade.

Autenticação e Segurança

A plataforma suporta dois mecanismos de autenticação: Bearer Token JWT para usuários autenticados (com autorização por papel e permissões por módulo), e API Key via header `X-Api-Key` para integrações server-to-server sem necessidade de sessão. Ambos têm escopo restrito à empresa identificada.

Modelo Multiempresa

A API deve ser tratada como plataforma multi-tenant. O backend é a fonte de verdade para escopo, posse e autorização, e clientes não devem inferir acesso global a partir de IDs conhecidos.

Contratos Estáveis

Os módulos auth, user, address, status-type, map, device, installation e company concentram a parte mais estável da superfície técnica atual para integrações corporativas.

Canais de Integração

A plataforma oferece REST/JSON para integrações primárias, OpenAPI para descoberta de schema e WebSocket para cenários de atualização operacional em tempo real. Fluxos assíncronos internos continuam encapsulados pela própria API.