Referência da API Fleetmap
Consulte posições ao vivo, relatórios de viagens e paradas, dispositivos e cercas virtuais, e envie comandos aos rastreadores. Fotos e clips da câmera usam um segundo prefixo.
https://api.pinme.io/As rotas REST começam com /api e aceitam bearer token, Basic auth ou cookie de sessão. As rotas de câmera começam com /pinmeapi e só aceitam o cookie de sessão.
Enviado como Authorization: Bearer ao testar um endpoint. Login e rotas de câmera usam o cookie de sessão. O token fica nesta aba do navegador, e cada pedido vai para a API ao vivo.
2026-11-17T08:00:00ZAutenticação
Todo endpoint, exceto as chamadas de sessão, precisa de credenciais. Sem elas a resposta é 401 Unauthorized. Escolha um método:
1. Token da API (recomendado para integrações)
Chame POST /api/session com e-mail e senha. O usuário retornado inclui um token (criado no primeiro login se a conta ainda não tinha). Envie esse valor como bearer token nas próximas chamadas:
curl https://api.pinme.io/api/devices \
-H "Authorization: Bearer YOUR_TOKEN"O token tem pelo menos 16 caracteres (letras, dígitos e hífens). GET /api/session devolve o mesmo usuário e o mesmo token enquanto a sessão estiver ativa. O “Testar” desta página preenche o campo acima após um login bem-sucedido.
2. HTTP Basic
O e-mail e a senha de login do Fleetmap. É simples, mas envia a senha em toda chamada — prefira um token para integrações de longa duração.
curl -u "you@company.com:password" https://api.pinme.io/api/devices3. Cookie de sessão
Chame POST /api/session uma vez e reutilize o cookie JSESSIONID. É o que o WebSocket, o app web e as rotas de câmera usam. A mesma resposta inclui o token do usuário (criado se faltar), que você pode enviar como bearer token no lugar do cookie.
curl -c cookies.txt -d "email=you@company.com&password=secret" \
https://api.pinme.io/api/session
curl -b cookies.txt https://api.pinme.io/api/devicesreadonly não pode criar, alterar nem apagar nada.Convenções
Parâmetros de query repetidos
Filtros com vários valores repetem o nome: ?deviceId=12&deviceId=15&groupId=3.
Códigos de status
| Código | Significado |
|---|---|
| 200 | Sucesso. O corpo traz o objeto ou a lista. |
| 202 | Comando aceito e enfileirado. O dispositivo está offline e recebe ao reconectar. |
| 204 | Sucesso, sem corpo (exclusões, logout, relatórios por e-mail). |
| 400 | Pedido entendido, mas recusado: parâmetro inválido, sem permissão, limite de dispositivos ou usuário somente leitura. O corpo traz o motivo em texto. |
| 401 | Credenciais ausentes ou incorretas. |
| 404 | Objeto não encontrado, ou sem sessão ativa em GET /api/session. |
Atributos
A maioria dos objetos traz um mapa attributes com dados extras. Em posições ficam os sensores do rastreador; em dispositivos, usuários e grupos, as configurações. Chaves desconhecidas são mantidas.
Atualizações em tempo real (WebSocket)
Para acompanhar veículos ao vivo, abra um WebSocket em vez de fazer polling em /api/positions.
wss://api.pinme.io/api/socketAutentique de uma destas formas:
- Cookie de sessão: chame
POST /api/sessionprimeiro e abra o socket com o mesmo cookieJSESSIONID. - Token: abra o socket sem cookie e envie o token da API como a primeira mensagem de texto.
O servidor envia primeiro a última posição de cada veículo e depois uma mensagem quando algo muda. Cada mensagem é um objeto JSON com uma ou mais destas chaves:
{
"positions": [ { "deviceId": 1042, "fixTime": "2026-11-17T09:12:03.000+00:00",
"latitude": 38.7223, "longitude": -9.1393, "speed": 23.2, ... } ],
"devices": [ { "id": 1042, "status": "online", "lastUpdate": "..." } ],
"events": [ { "type": "geofenceEnter", "deviceId": 1042, "geofenceId": 77, ... } ]
}// Browser or Node (ws) example
const ws = new WebSocket("wss://api.pinme.io/api/socket");
ws.onopen = () => ws.send("YOUR_TOKEN");
ws.onmessage = (m) => {
const data = JSON.parse(m.data);
(data.positions || []).forEach(p => console.log(p.deviceId, p.latitude, p.longitude));
};Modelos de dados
Os principais objetos devolvidos pela API. Todo objeto também tem um id (número) e um mapa attributes.
Atributos comuns de posição
O que aparece em position.attributes depende do modelo do rastreador. Estas são as chaves mais comuns:
| Chave | Significado |
|---|---|
| ignition | Ignição ligada (true) ou desligada |
| motion | Veículo em movimento |
| totalDistance | Odômetro calculado pela plataforma, metros |
| odometer | Odômetro reportado pelo veículo (CAN/OBD), metros |
| distance | Distância desde a posição anterior, metros |
| hours | Horas de motor, milissegundos |
| power | Tensão de alimentação do veículo, volts |
| batteryLevel | Bateria interna, percentual |
| fuel | Nível de combustível, litros (com sensor) |
| sat / rssi | Satélites GPS em uso / sinal GSM |
| driverUniqueId | Identificação do motorista (iButton, RFID, cartão) |
| input / output | Estados de entrada e saída digitais |
| blocked | Imobilizador do motor ativo |
| alarm | Alarme nesta posição (veja abaixo) |
| adasAlarmType / dmsAlarmType | Tipo de alarme da câmera (ADAS / monitoramento do motorista), ex.: fadiga, distração, celular, fumo |
| adasAlarmLevel / dmsAlarmLevel | Nível de severidade reportado pela câmera com esse alarme |
| alarmIdentifier | Id único de um alarme de câmera (hex). Use para buscar fotos e vídeo do alarme |
| videoResources | Resposta a um comando videoList: string JSON com as gravações (veja Comandos de vídeo) |
Valores de alarme
Tipos de evento
Usados por /api/reports/events?type=, notificações e events do WebSocket.
Tipos de comando
Nem todo rastreador aceita todos os comandos. Passe um destes valores como type em POST /api/commands/send.
Comandos de vídeo (câmeras)
Enviados com POST /api/commands/send; os parâmetros vão em attributes. Um 200 só significa que o comando foi enviado à câmera. A resposta chega depois, como nova posição do dispositivo, via WebSocket ou GET /api/positions.
| Tipo | Atributos | O que faz |
|---|---|---|
| videoList | index (channel, 0 = all), startTime, endTime (ISO 8601), alarmFlag (0 = all recordings) | Lista as gravações no cartão SD da câmera. A resposta é o atributo de posição videoResources. |
| videoStart | server, port, index (channel) | Inicia stream ao vivo para server:port. |
| videoStop | index (channel) | Para o stream ao vivo naquele canal. |
| videoPlayback | server, port, index, startTime, endTime, resourceType, streamType, storageType | Reproduz uma gravação para server:port. Pegue os três últimos valores no item de videoResources. |
videoResources é uma string JSON com um array. Cada item tem channel, startTime e endTime (milissegundos desde 1970, UTC), alarmFlag, resourceType, streamType, storageType e fileSize (bytes).
videoStart e videoPlayback fazem a câmera enviar vídeo no protocolo JT/T 1078 para o servidor e porta indicados. Esse servidor precisa entender JT/T 1078; não é um arquivo baixado desta API. Para fotos e clips de alarme, use Mídia da câmera.Dúvidas sobre acesso à API: suporte Fleetmap.