API WinkTracker (ApiServlet)

Documentação da API HTTP exposta pelo ApiServlet do projeto winktracker2.

Implementação: winktracker2/src/com/winksys/tracker/server/servlet/ApiServlet.java

---

Visão geral

Item	Valor
URL base	/api
Métodos HTTP	GET e POST
Roteamento	Parâmetro de query m seleciona a operação (estilo RPC)
Resposta padrão	application/json;charset=UTF-8
Exceção	m=gethist retorna text/html;charset=UTF-8 quando aplicável

Exemplo mínimo

GET /api?m=getlasthist&u=meuusuario&s=minhasenha&lastid=0
Authorization: Basic bWV1dXN1YXJpbzptaW5oYXNlbmhh

---

Índice

Fundamentos

• Autenticação — login, token, Basic Auth, sessão
• Convenções — formatos de data, paginação, rate limit, erros HTTP
• Códigos de resposta — códigos internos (Constants.java)

Referência

• Catálogo de endpoints — tabela resumo de todos os métodos m

Endpoints por domínio

Domínio	Documento
Posições e histórico	endpoints/posicoes-historico.md
Veículos, bloqueio e compartilhamento	endpoints/veiculos-comandos.md
Autenticação e senha	endpoints/autenticacao-senha.md
Cadastros (cliente, veículo, equipamento)	endpoints/cadastros.md
Jornada, viagem e linhas	endpoints/jornada-viagem.md
Manutenção, abastecimento e multas	endpoints/manutencao-frota.md
Relatórios e gerencial	endpoints/relatorios.md
Câmera, mensagens e ocorrências	endpoints/camera-mensagens.md
Consultas auxiliares	endpoints/consultas-auxiliares.md

---

Fluxo típico (cliente mobile / integração)

sequenceDiagram
    participant C as Cliente
    participant A as /api

    C->>A: GET ?m=auth&u=&s= (ou Basic Auth)
    A-->>C: 200 OK + sessão
    C->>A: GET ?m=getlasthist&lastid=0
    A-->>C: JSON array de posições
    C->>A: GET ?m=getVeiculos
    A-->>C: JSON array de veículos

1. Autenticar com u/s, header Authorization: Basic, ou token de acesso.
2. Chamar m=auth para registrar device token / obter permissões (opcional, mas comum no app).
3. Consumir endpoints de dados (getlasthist, getVeiculos, etc.) reutilizando a mesma sessão ou credenciais.

---

Parâmetros globais

Estes parâmetros são interpretados pelo ApiServlet e podem ser usados em qualquer chamada autenticada:

Parâmetro	Descrição
m	Obrigatório. Nome da operação
u	Login do usuário (alternativa ao Basic Auth)
s	Senha do usuário
token	Token de acesso (AccessToken) — bypass de autenticação por login/senha
closeSession	Se false, mantém a sessão HTTP após a requisição (padrão: invalida)

---

Respostas de erro HTTP

Código	Significado
404	Método m não encontrado
403	Autenticação falhou ou usuário sem permissão
500	Erro interno no handler

---

Manutenção desta documentação

Os métodos m foram extraídos dos handlers registrados em ApiServlet.handlers e das classes IRequestHandler em:

• winktracker2/src/com/winksys/tracker/server/servlet/api/
• winktracker2/src/com/winksys/tracker/server/servlet/ (handlers legados)

Ao adicionar um novo handler, atualize o catálogo e o documento de domínio correspondente.