Rastreio em tempo real

O modelo

Rastreio veicular no mercado logístico se organiza em quatro camadas, e adotamos o mesmo vocabulário para quem já integra outros marketplaces não precisar traduzir nada:

Camada	O que é	Na Indústria 24h
transport	O veículo ou pessoa que transporta	A corrida, com origem, destino e status
device	O GPS, celular ou rastreador embarcado	O parceiro logístico atribuído à corrida
location	Latitude, longitude e o instante da leitura	Cada registro de posição da corrida
telemetry / event	Velocidade, odômetro, frenagem brusca	Não coletado hoje

O que existe hoje

O aplicativo do parceiro registra a posição durante a corrida, a partir do momento em que a carga é coletada e enquanto ela está em trânsito. Cada posição guarda latitude, longitude e data. Você lê isso pela ferramenta industria24_rastrear_corrida, que devolve as posições da mais recente para a mais antiga.

{
  "transport": {
    "id": "9f1c...",
    "status": "EmTransito",
    "origem": "Av. das Torres, 1200 - Manaus",
    "destino": "R. Recife, 45 - Manaus",
    "pedido_id": "3f9u..."
  },
  "device": {
    "external_entity_id": "b71a...",
    "external_entity_type": "PARCEIRO_LOGISTICO"
  },
  "locations": [
    {
      "latitude": -3.101944,
      "longitude": -60.025,
      "timestamp": 1768900861,
      "date": "2026-07-20T14:41:01.000Z"
    }
  ]
}

timestamp é em segundos desde 1970 (UTC), o formato usado pelos padrões de rastreio; date é o mesmo instante em ISO 8601, para quem preferir.

Estados da corrida

Posições só existem entre Coletada e Entregue. Antes disso a lista vem vazia, e isso não é erro.

Publicada → Aceita → Coletada → EmTransito → Entregue
                                    ↘ Cancelada

Frequência e uso

A cadência das posições depende do parceiro em rota; trate a lista como esparsa e use sempre o timestamp para saber a idade do dado.
Para acompanhar uma entrega, faça polling da corrida a cada poucos minutos. Não há webhook de posição hoje.
Para o rastreio comercial do pedido (código de rastreio, transportadora), use industria24_listar_registros na tabela entregas.

No roteiro

O padrão completo de rastreio veicular prevê ainda registro de dispositivo com marca e modelo, comandos de início e parada de monitoramento, envio de rotas planejadas com paradas e janelas, telemetria (velocidade, odômetro, combustível, bateria) e eventos de direção como frenagem brusca ou excesso de velocidade. Nada disso está implementado: só faz sentido quando houver frota instrumentada ou um contrato que exija esse nível de detalhe. O formato de resposta acima já foi desenhado para receber esses campos sem quebrar quem integrar agora.