Convenções da API
Formato de requisição
Query string vs body
| Tipo | Uso |
|---|---|
| Query string | Maioria dos endpoints GET e alguns POST |
| Body JSON | Cadastros (cadcli, cadvei, cadequi), passwd, addManutencao, changepwdbycode, salvajornadamotorista |
| Body form/query | cadabastecimento (parâmetros na query ou form) |
Para POST com body JSON, enviar Content-Type: application/json.
Formatos de data
| Formato | Exemplo | Endpoints |
|---|---|---|
ddMMyyyyHHmmss | 07062025143000 | gethist, getdet, getTemperatura, getRelVisitas, getRelSensores, viagens |
yyyy-MM-dd | 2025-06-07 | getGerencial |
yyyy-MM-dd HH:mm:ss (parse flexível) | 2025-06-07 14:30:00 | getGerencial2 |
| Epoch millis (string) | 1717770600000 | cadabastecimento, listamultas, manutenções, ocorrências (dtGMT) |
yyyy-MM-dd'T'HH:mm:ss | ISO-like | addManutencao (body JSON) |
Paginação
Padrões variam por endpoint:
| Parâmetro | Significado comum |
|---|---|
limit | Máximo de registros |
first / firstResult / offset | Offset inicial |
page / p | Página (1-based ou 0-based — ver endpoint) |
lastid | Cursor por ID (posições, mensagens, POIs) |
Content-Type de resposta
m | Content-Type |
|---|---|
| Maioria | application/json;charset=UTF-8 |
gethist (GET) | text/html;charset=UTF-8 quando format não é JSON |
getperm | Texto plano (lista de nomes separados por vírgula) |
getDownload | Binário / stream do arquivo |
Parâmetro format
Vários endpoints aceitam format=json para resposta JSON estruturada. Sem format, alguns retornam texto simples (OK, códigos de status).
Exemplos: auth, block, unblock, getcomm, getpois, getocorr, getdet.
Sessão e closeSession
Por padrão, o ApiServlet invalida a sessão ao final de cada requisição, exceto quando:
- O handler define
req.setAttribute("closeSession", false)(ex.:auth), ou - O cliente envia
closeSession=falsena query string.
Apps mobile devem usar closeSession=false em todas as chamadas após o login.
Rate limit
Configuração: war/WEB-INF/rate-limit.properties
| Propriedade | Descrição |
|---|---|
default.per.minute | Limite padrão por usuário+rota por minuto |
default.ip.per.hour | Limite padrão por IP por hora |
route.<nome> | Limite específico para o valor de m |
Resposta quando excedido: HTTP 429 Too Many Requests.
CORS
O CorsFilter está mapeado para /* — requisições cross-origin são permitidas conforme configuração do filtro.
Hierarquia de clientes
Muitos endpoints filtram dados pelo ClienteDTO do usuário logado, incluindo sub-clientes via path LIKE 'X.%'. Veículos e posições respeitam essa árvore hierárquica.
Identificação de veículo
| Parâmetro | Tipo | Uso |
|---|---|---|
v | int (ID) | Histórico, comandos, relatórios |
idVeiculo | int | Viagens, mensagens, trajetos |
veiculo | int/string | Varia por endpoint |
placa | string | Compartilhamento (share) |