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.

URL basehttps://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.

Token da API

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.

FormatoJSON na entrada e na saída
DatasISO 8601 UTC, ex. 2026-11-17T08:00:00Z
Velocidadenós (× 1,852 = km/h)
Distânciametros

Autenticaçã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:

Exemplo
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.

Exemplo
curl -u "you@company.com:password" https://api.pinme.io/api/devices

3. 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.

Exemplo
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/devices
Use um usuário de API dedicado, só com os veículos que a integração precisa. Todo endpoint de lista devolve apenas o que esse usuário pode ver, e um usuário readonly 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ódigoSignificado
200Sucesso. O corpo traz o objeto ou a lista.
202Comando aceito e enfileirado. O dispositivo está offline e recebe ao reconectar.
204Sucesso, sem corpo (exclusões, logout, relatórios por e-mail).
400Pedido 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.
401Credenciais ausentes ou incorretas.
404Objeto 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.

Exemplo
wss://api.pinme.io/api/socket

Autentique de uma destas formas:

  • Cookie de sessão: chame POST /api/session primeiro e abra o socket com o mesmo cookie JSESSIONID.
  • 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:

Exemplo
{
  "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, ... } ]
}
Exemplo
// 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));
};
A conexão fecha após 10 minutos sem tráfego. Reconecte automaticamente e espere o snapshot completo de posições de novo a cada reconexão.

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:

ChaveSignificado
ignitionIgnição ligada (true) ou desligada
motionVeículo em movimento
totalDistanceOdômetro calculado pela plataforma, metros
odometerOdômetro reportado pelo veículo (CAN/OBD), metros
distanceDistância desde a posição anterior, metros
hoursHoras de motor, milissegundos
powerTensão de alimentação do veículo, volts
batteryLevelBateria interna, percentual
fuelNível de combustível, litros (com sensor)
sat / rssiSatélites GPS em uso / sinal GSM
driverUniqueIdIdentificação do motorista (iButton, RFID, cartão)
input / outputEstados de entrada e saída digitais
blockedImobilizador do motor ativo
alarmAlarme nesta posição (veja abaixo)
adasAlarmType / dmsAlarmTypeTipo de alarme da câmera (ADAS / monitoramento do motorista), ex.: fadiga, distração, celular, fumo
adasAlarmLevel / dmsAlarmLevelNível de severidade reportado pela câmera com esse alarme
alarmIdentifierId único de um alarme de câmera (hex). Use para buscar fotos e vídeo do alarme
videoResourcesResposta 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.

TipoAtributosO que faz
videoListindex (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.
videoStartserver, port, index (channel)Inicia stream ao vivo para server:port.
videoStopindex (channel)Para o stream ao vivo naquele canal.
videoPlaybackserver, port, index, startTime, endTime, resourceType, streamType, storageTypeReproduz 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.