Autenticação
Toda operação com needAuth() == true exige autenticação prévia. O ApiServlet valida credenciais antes de delegar ao handler.
Fonte: ApiServlet.auth()
Formas de autenticação
1. Sessão HTTP (recomendado após primeiro login)
Após autenticação bem-sucedida, o atributo usuario (UsuarioDTO) fica na sessão. Requisições subsequentes na mesma sessão são aceitas sem reenviar senha.
Use closeSession=false na query string para não invalidar a sessão ao final da requisição:
GET /api?m=getlasthist&lastid=0&closeSession=false
Cookie: JSESSIONID=...
2. Basic Auth (header)
GET /api?m=getVeiculos
Authorization: Basic base64(usuario:senha)
O header deve começar com Basic (com espaço). Credenciais inválidas ou malformadas retornam 403.
3. Query string u e s
GET /api?m=getlasthist&u=login&s=senha&lastid=0
Ambos são obrigatórios, trimados, e não podem ser vazios.
4. Token de acesso (token)
GET /api?m=getDownload&id=123&token=abc123...
Valida contra a entidade AccessToken via GetTokenAction. Usado para links públicos temporários (ex.: compartilhamento de veículo).
Validação de usuário
Além de login/senha corretos, o sistema verifica:
- Usuário com
status=0(ativo) - Cliente com
nivelBloqueio=0 - Nenhum cliente master na hierarquia com
nivelBloqueio=2(bloqueio em cascata)
Usuários bloqueados recebem 403.
Endpoints públicos (sem autenticação)
m | Descrição |
|---|---|
loginByToken | Login via código/token de recuperação |
solicitaCodigo | Solicita código de recuperação de senha por e-mail |
changepwdbycode | Altera senha usando código recebido |
Detalhes: endpoints/autenticacao-senha.md
Endpoint auth (pós-login)
Após autenticação, m=auth confirma a sessão, registra tokens de push e retorna dados do usuário.
GET /api?m=auth&format=json&deviceToken=...&t=...&closeSession=false
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
format | Não | json para resposta JSON estruturada; omitir retorna OK em texto |
deviceToken | Não | Token APNS (iOS) |
t | Não | Token FCM (Firebase) |
r | Não | URL de redirect (em vez de JSON) |
Resposta JSON (format=json):
{
"code": 200,
"message": "OK",
"id": 1,
"login": "usuario",
"senhaProvisoria": false,
"habilitaMapa": true,
"cliente": { "id": 1, "path": "1", "razaoSocial": "...", "email": "..." },
"permissoes": [ { "id": 1, "nome": "..." } ]
}
Permissões especiais
Alguns endpoints verificam permissões adicionais na sessão:
| Operação | Requisito |
|---|---|
block / unblock | usuario.permiteBloqueio == true |
passwd | Só altera senha do próprio usuário logado (id no body) |
Rate limiting
O filtro ApiRateLimitFilter protege /api com limites por IP (hora) e por usuário+rota (minuto). Configuração em /WEB-INF/rate-limit.properties.
Rota = valor de m (minúsculas). Usuário = parâmetro u ou login do Basic Auth.
Ver Convenções.