DeclaTrack — Guia de Integração da API

01 Escopo & segurança

A API é naturalmente restrita ao usuário dono do token. Toda requisição é resolvida no contexto do usuário identificado pelo user_api_hash, e o servidor consulta apenas os dispositivos daquele usuário. Não há como um token enxergar veículos de outro usuário — o isolamento é garantido no back-end, não depende de filtro do cliente.

• Cada usuário possui um api_hash único (campo exibido em Editar → API → “Hash da API”).
• O hash pode ter data de expiração (api_hash_expire). Para integração contínua, use um hash sem expiração ou renove-o via login.
• Todas as chamadas devem trafegar sobre HTTPS. Como o token vai na querystring, evite registrá-lo em logs de acesso.

02 Autenticação

Autentique enviando o parâmetro user_api_hash em toda requisição (via query string em GET ou no corpo em POST). Se você já tem o hash da tela do usuário, pode usá-lo diretamente e pular o login.

{
  "status": 1,
  "user_api_hash": "$2y$10$cGz...YIBKu",
  "permissions": { ... }
}

03 Veículos + posição atual

Este é o endpoint principal da integração. Retorna a frota do usuário agrupada, com a posição atual, ignição, sensores, serviços e status de cada veículo em uma única chamada.

curl -G "https://gps.declatrack.com.br/api/get_devices" \
     --data-urlencode "user_api_hash=SEU_TOKEN" \
     --data-urlencode "lang=pt"

// A resposta é uma LISTA de grupos; cada grupo tem "items" (veículos).
// Os campos de posição vêm no NÍVEL do veículo (não aninhados).
[
  {
    "id": 0, "title": "Desagrupados",
    "items": [
      {
        "id": 170907,
        "name": "RMM2G18 GARRA",
        "online": "stopped",     // moving | stopped | offline
        "lat": -7.11532,
        "lng": -34.8641,
        "speed": 0,
        "course": 218,
        "altitude": 12,
        "time": "2026-07-06 18:33:45",
        "address": "Av. Governador...",
        "protocol": "gt06",
        "engine_status": false,    // ignição (booleano)
        "engine_hours": "ignition", // fonte do horímetro
        "stop_duration": "2mes 5d 15h",
        "total_distance": 5084.76, // hodômetro (km)
        "unit_of_distance": "km",
        "tail": [ {"lat":"-21.8404", "lng":"-43.3742"} /* rastro */ ],
        "sensors": [
          { "type": "ignition", "name": "Ignição", "value": "Ligado", "val": "True" },
          { "type": "battery", "name": "Bat. Veículo", "value": "14.42 v", "val": "14.42" }
        ]
      }
    ]
  }
]

04 Atualizações recentes (polling leve)

Versão enxuta para atualização frequente do mapa. Retorna um envelope { items, events, time, version } com as mudanças desde a última consulta — mais leve que get_devices. Para o retrato completo da frota, use get_devices; para atualizar, faça polling deste.

curl -G "https://gps.declatrack.com.br/api/get_devices_latest" \
     --data-urlencode "user_api_hash=SEU_TOKEN"

05 Histórico de trajeto

Retorna as posições registradas de um veículo em um intervalo — usado para reconstruir trajetos, distância percorrida e tempo de ignição ao longo do período.

curl -G "https://gps.declatrack.com.br/api/get_history" \
     --data-urlencode "user_api_hash=SEU_TOKEN" \
     --data-urlencode "device_id=170907" \
     --data-urlencode "from_date=2026-07-01" \
     --data-urlencode "from_time=00:00" \
     --data-urlencode "to_date=2026-07-01" \
     --data-urlencode "to_time=23:59"

06 Eventos

Lista os eventos gerados pelos veículos do usuário (ignição ligada/desligada, entrada/saída de cerca, excesso de velocidade, etc.) — útil para calcular tempo de ignição ligado/desligado e alertas.

07 Dicionário de campos

Campos retornados por veículo em get_devices (validados na resposta real, app v3.7.7). Atenção: os campos de posição ficam no nível principal do veículo — não há bloco position aninhado.

Identificação & estado

Posição (nível do veículo)

Array sensors[]

08 Erros & boas práticas

Respostas de erro também trazem "status": 0 e uma mensagem no corpo. Sempre verifique status antes de consumir os dados.

Checklist de integração

• Use sempre HTTPS e trate o token como segredo.
• Prefira credencial secundária por cliente, revogável.
• Para tempo real, faça polling de get_devices_latest (≥ 10–15 s). Para telemetria instantânea, consulte a equipe DeclaTrack sobre o canal WebSocket.
• Guarde o id de cada veículo para cruzar com get_history e get_events.
• Implemente retry com espera em caso de falha de rede — não em rajada.