Rastreamento ao vivo
O rastreamento ao vivo mostra nos seus mapas publicados onde seus veículos estão e onde param hoje: o trajeto de um food truck, um circuito de shuttle, uma clínica móvel. Os visitantes veem cada veículo em turno se mover no mapa, as paradas de hoje com Aqui agora, Aberto agora ou Fechado hoje, e uma estimativa de quanto falta até a próxima parada. Veja o layout ao vivo para saber o que um visitante vê.
Ele tem três partes, todas no Kaleidr Studio:
| Parte | O que é |
|---|---|
| Uma coleção de Paradas | O horário: cada parada, seu endereço e suas janelas de atendimento semanais. Uma coleção da Biblioteca de locais como qualquer outra. |
| Uma frota | Seus veículos, seus turnos e com que precisão os visitantes os veem. Gerenciada em Dados, Frota. |
| Posições | Onde está cada veículo, a partir de uma de quatro fontes: o link de check-in de um motorista, um telefone no modo motorista, um rastreador seu, ou um conector com seu provedor de telemática. |
As posições só são mostradas enquanto um veículo está em turno. Uma posição registrada fora de todos os turnos do veículo é descartada ao chegar: nunca é armazenada nem mostrada, apenas contada. Veja Turnos.
Frotas
Em Dados, escolha a aba Frota e depois Nova Frota. Dê a ela um nome e um fuso horário, e escolha a Coleção de Paradas se tiver uma. O Studio cria uma coleção de Veículos com o mesmo nome: essa coleção é a frota nos seus mapas, e você a adiciona a um mapa como qualquer coleção. Ela não contém locais importados; seus veículos são os da frota.
Adicionar Veículo, na página da frota, adiciona um:
| Campo | Visível para os visitantes | Uso |
|---|---|---|
| Nome | Sim | O rótulo do veículo no mapa e no painel, como "Caminhão 1". Único na frota. |
| Tipo | Sim | Caminhão, van, carro, ônibus, shuttle, barco, carrinho ou bicicleta. |
| Cor | Sim | A cor do veículo no mapa. |
| Descrição | Sim | Uma linha curta no cartão, de até 200 caracteres. |
| ID externo | Não | Seu próprio id, usado pelos conectores e pela coluna Veículo das suas paradas. |
| Horário de turnos | Não | As horas semanais que os turnos de uma frota com horário programado seguem. Veja Turnos. |
Um veículo desativado nunca é mostrado, e suas posições são descartadas. A página da frota desenha um mapa ao vivo dela, com precisão total, só para você.
Proprietários, administradores e membros gerenciam frotas e veículos; leitores podem vê-los. Só proprietários e administradores excluem uma frota, apagam o histórico de um veículo e gerenciam conectores. Excluir Frota exclui a frota, seus veículos, dispositivos, links, turnos, histórico e conectores, e depois a coleção de Veículos.
Horários das paradas
O horário é uma coleção de Paradas. Cada parada é um local com nome e endereço ou coordenadas, e estes campos definem quando ela é atendida:
| Campo | Significado |
|---|---|
| Horário | As janelas de atendimento semanais da parada, escritas como um horário de funcionamento: até quatro janelas por dia. Uma janela pode passar da meia-noite e pertence ao dia em que começa. |
| Fuso Horário | O fuso em que as janelas estão escritas. Vazio, o da coleção. |
| Status | paused tira a parada de todos os dias. Qualquer outro valor, ou nenhum, a mantém. |
| Veículo | O nome ou o ID externo do veículo que atende a parada. Vazio, qualquer veículo da frota. |
| Datas de atendimento | Datas no formato YYYY-MM-DD, separadas por vírgulas ou espaços. Quando existem, a parada funciona apenas nessas datas. |
Em uma data qualquer, as janelas de uma parada são:
- nenhuma se o status for
paused, ou se o fuso horário não for válido; - nenhuma se ela tiver Datas de atendimento e a data não estiver entre elas;
- sem Horário: o dia inteiro se as Datas de atendimento incluírem a data; caso contrário, nenhuma;
- caso contrário, o Horário daquele dia da semana.
Uma parada está aberta agora quando uma janela de hoje contém a hora local, ou quando uma janela de ontem que passa da meia-noite a contém. "Hoje" é a data no fuso horário da frota.
| Parada | Consulta | Janelas | Aberta |
|---|---|---|---|
| Horário segunda 11:00–14:00 | Segunda 12:00 | 11:00–14:00 | Sim |
| A mesma | Segunda 15:00 | 11:00–14:00 | Não |
A mesma, com Datas de atendimento 2026-11-02 | Segunda 2026-11-09, 12:00 | Nenhuma | Não |
Datas de atendimento 2026-11-02, sem horário | 2026-11-02, 09:00 | O dia inteiro | Sim |
Horário segunda 11:00–14:00, Status Paused | Segunda 12:00 | Nenhuma | Não |
| Horário sexta 22:00–02:00 | Sábado 01:00 | A de sexta, 22:00–02:00 | Sim |
| Horário segunda 11:00–14:00, fuso horário inválido | Segunda 12:00 | Nenhuma | Desconhecido |
Datas de atendimento 2026-11-02, 2026-11-03 2026-11-04, horário segunda 11:00–14:00 | Terça 2026-11-03 | O horário de terça: nenhuma | Não |
O modelo Location do criador de modelos e Baixar planilha de exemplo dão a você uma coleção de Paradas já preenchida para começar.
Links de check-in
Um link de check-in permite que um motorista marque o veículo em uma parada pelo navegador de qualquer telefone, sem app e sem conta.
Crie um na página da frota: um veículo, Link de Check-In, Criar Link. O Studio mostra o link uma única vez, com Copiar Link e um QR code para ler. Ele tem esta forma: https://map-embed.kaleidr.com/checkin.html#….
- Um link por veículo, válido por 180 dias. Substituir Link emite um novo e encerra o antigo na hora; use quando um telefone for perdido ou um motorista sair. Revogar Link o encerra. Depois, o Studio mostra apenas os quatro últimos caracteres do link, quando ele expira e quando foi usado pela última vez.
- O link é uma chave. Qualquer pessoa que o tenha, perto de uma parada, pode fazer o check-in do veículo. Compartilhe apenas com o motorista.
- Abra-o em um navegador. A página não funciona dentro do frame de outra página.
A página do motorista mostra o veículo, as paradas de hoje e o status delas:
- Estou aqui agora lê a localização do telefone uma vez e faz o check-in na parada ao alcance: 250 metros mais a precisão da leitura, que precisa ser de 100 metros ou melhor. Quando há mais de uma parada ao alcance, ou nenhuma, a página lista as paradas de hoje e o motorista escolhe uma, que precisa estar a até 2.000 metros. Uma frota com Permitir check-in fora das paradas ativado também oferece Não é uma parada programada.
- Fechado hoje marca as paradas restantes do veículo hoje como Fechado hoje e encerra o turno. Reabrir hoje, no mesmo dia, remove essas marcações; não inicia um turno.
Um check-in abre um turno até 30 minutos depois do fim da janela da parada, e mostra o veículo na posição da própria parada, não na do telefone. A localização do telefone é usada para encontrar a parada e depois descartada. Um check-in fora de uma parada mostra o veículo na posição do telefone por quatro horas, arredondada para cerca de 10 metros, ou mais quando a precisão pública da frota é menor.
Telefones no modo motorista
O telefone de um motorista com o app da Kaleidr compartilha a posição do veículo enquanto o turno do motorista está ativo. Na página da frota, em um veículo, Parear Telefone, Mostrar Código de Pareamento mostra um QR code e um código de oito caracteres, válido por 10 minutos e uma única vez. O motorista lê o QR com a câmera do telefone, ou digita o código no app. Veja Modo motorista para a parte do motorista.
Dispositivos lista os telefones e rastreadores de cada veículo. Desfazer Pareamento remove um na hora: a próxima chamada dele é recusada, e um turno que ele iniciou termina.
Rastreadores e a API de posições
Um rastreador é qualquer dispositivo ou sistema seu que envia posições: uma unidade GPS com um cliente HTTP, ou o seu próprio software de despacho. Na página da frota, em um veículo, escolha Adicionar Rastreador, dê um nome a ele, e o Studio mostra a chave uma única vez. A chave pertence a esse veículo.
curl https://api.kaleidr.com/live-api/v1/positions \
-H "Authorization: Bearer YOUR_DEVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"positions": [
{ "lat": 40.74110, "lng": -73.98970, "heading": 90, "speed": 8.3, "accuracy": 12,
"recorded_at": "2026-10-22T15:04:05Z" }
],
"sent_at": "2026-10-22T15:04:06Z"
}'
| Campo | Regra |
|---|---|
positions | De 1 a 100 pontos, em qualquer ordem. O corpo tem no máximo 64 KiB. |
lat, lng | Obrigatórios. Dentro do intervalo, e não ambos 0. |
heading | Graus a partir do norte. |
speed | Metros por segundo. |
accuracy | Metros. Um ponto com precisão pior que 100 metros é descartado. |
recorded_at | Obrigatório. Quando a posição foi medida: RFC 3339, ou milissegundos desde 1970. |
sent_at | Quando o lote foi enviado, pelo relógio do dispositivo. Se ele diferir do relógio da Kaleidr em mais de 5 segundos e menos de um dia, cada recorded_at é corrigido pela diferença; com um dia ou mais, o lote é recusado. |
A resposta:
{
"accepted": 1,
"dropped": { "off_shift": 0, "stale": 0, "future": 0, "inaccurate": 0, "rate": 0, "duplicate": 0 },
"shift": { "id": "…", "state": "on", "ends_at": "2026-10-23T03:04:05Z" },
"min_interval_s": 10
}
| Descartado como | Por quê |
|---|---|
off_shift | Registrado fora de todos os turnos do veículo, ou o veículo está inativo. Nunca armazenado. |
stale | Registrado há mais de 12 horas. |
future | Registrado mais de 30 segundos à frente do relógio da Kaleidr. |
inaccurate | Precisão pior que 100 metros, ou velocidade ou precisão negativa. |
rate | Mais próximo no tempo do ponto anterior do veículo do que o intervalo de atualização do seu plano. |
duplicate | Um ponto com o mesmo recorded_at já foi mantido. |
GET /live-api/v1/device responde com o dispositivo, o veículo dele, a frota e o turno aberto. POST /live-api/v1/device/shift com { "action": "start" } ou { "action": "end" } inicia ou encerra o turno do veículo a partir do dispositivo.
| Status | error | Significado |
|---|---|---|
| 400 | invalid_request | O corpo está malformado; field indica a parte. |
| 400 | clock_invalid | sent_at está a um dia ou mais do relógio da Kaleidr. |
| 401 | unauthorized | Sem chave, ou com uma chave desconhecida. |
| 401 | device_revoked | O dispositivo foi removido no Studio. Pare de enviar. |
| 409 | off_shift | O lote tinha pontos, nenhum caiu em um turno, e nenhum turno está aberto. Pare de enviar até que um turno comece. |
| 413 | batch_too_large | Mais de 100 pontos, ou mais de 64 KiB. |
| 429 | rate_limited | Mais de 12 solicitações por minuto deste dispositivo. Aguarde os segundos de Retry-After. |
Os erros são { "error": <code>, "message": <sentence> }. Envie a cada 10 a 30 segundos durante o deslocamento: um lote de pontos é melhor do que uma solicitação por ponto.
Conectores
Um conector traz posições de um sistema de telemática ao qual seus veículos já reportam. Proprietários e administradores adicionam um na página da frota, em Conectores, Adicionar Conector. Os conectores estão disponíveis nos planos Pro e Enterprise.
| Conector | O que você fornece | Como as posições chegam |
|---|---|---|
| Samsara | Um Token de API com acesso de leitura às localizações dos veículos | A Kaleidr pede à Samsara novas posições a cada intervalo de Consultar a Cada. |
| Geotab | Servidor (um host geotab.com), Banco de Dados, Usuário, Senha | A Kaleidr pede à Geotab novos registros a cada intervalo de Consultar a Cada. |
| Traccar | Nada: o Studio mostra uma URL de ingestão e um segredo | Seu servidor Traccar encaminha cada posição. |
| Webhook | Nada: o Studio mostra uma URL de ingestão e um segredo | Seu sistema envia lotes assinados. |
- As credenciais são somente gravação. O Studio verifica uma credencial da Samsara ou da Geotab com uma chamada antes de salvá-la, e nunca mais a mostra. Substituir Credenciais a troca.
- O segredo de ingestão é mostrado uma vez. Renovar Segredo emite um novo; o antigo continua funcionando por 24 horas.
- Associar Por define como um veículo do provedor encontra o seu: ID Externo (o padrão) ou Nome. Um veículo do provedor sem correspondência aparece em Veículos não associados, com Adicionar como Veículo; as posições dele são descartadas.
- Consultar a Cada é de pelo menos 30 segundos, e nunca menor que o intervalo de atualização do seu plano.
- Status: Ativo; Pausado, por você ou porque seu plano permite menos conectores; Com Falhas após cinco consultas com falha seguidas, continuando a tentar; Inválido quando o provedor recusa a credencial, até você substituí-la. Um conector Traccar ou webhook pausado ou inválido recusa o que é enviado a ele.
As posições dos conectores também passam pela regra de turnos.
Traccar
Adicione estas linhas ao arquivo de configuração do seu servidor Traccar, traccar.xml, com a URL e o segredo que o Studio mostrou, e reinicie o Traccar:
<entry key='forward.enable'>true</entry>
<entry key='forward.url'>https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/traccar</entry>
<entry key='forward.json'>true</entry>
<entry key='forward.header'>X-Kaleidr-Connector-Secret: YOUR_CONNECTOR_SECRET</entry>
Um dispositivo do Traccar é associado a um veículo pelo id único (ID Externo) ou pelo nome. Uma posição que o Traccar marca como inválida é descartada.
Webhook
Envie até 100 pontos por solicitação para a URL de ingestão, assinados com o segredo do conector:
import { createHmac } from 'node:crypto';
const body = JSON.stringify({
positions: [
{ vehicle: 'TRUCK-1', lat: 40.7411, lng: -73.9897, heading: 90, speed: 8.3, accuracy: 12,
recorded_at: '2026-10-22T15:04:05Z' },
],
});
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.KALEIDR_CONNECTOR_SECRET).update(`${t}.${body}`).digest('hex');
await fetch('https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/webhook', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Kaleidr-Signature': `t=${t},v1=${v1}` },
body,
});
Kaleidr-Signatureét=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, o esquema dos webhooks de reserva no sentido inverso.tprecisa estar a até 5 minutos do relógio da Kaleidr, e a assinatura precisa cobrir exatamente os bytes que você envia.vehicleé o ID externo ou o nome do veículo, conforme Associar Por.speedé em metros por segundo,accuracyem metros, erecorded_atem RFC 3339 ou milissegundos desde 1970.- Uma assinatura incorreta é recusada com 401
signature_invalid.
Turnos
Um turno é o período em que um veículo pode ser mostrado. Cada veículo tem no máximo um aberto, que dura no máximo 16 horas. Ele abre e fecha de uma de quatro formas:
| Aberto por | Termina |
|---|---|
| Iniciar Turno no modo motorista | Encerrar Turno, ou 16 horas depois |
| Um check-in | 30 minutos depois do fim da janela da parada, Fechado hoje, ou 16 horas depois |
| Iniciar Turno no veículo no Studio | Encerrar Turno no Studio, ou 16 horas depois |
| O horário de turnos do veículo, em uma frota cujo Modo de Turno é Horários Programados | O fim desse horário |
- Fora do turno, nada é publicado nem mantido. Uma posição registrada fora de todos os turnos é descartada ao chegar. Só a contagem de posições descartadas é mantida, para a seção Uso.
- Encerrar um turno tira o veículo dos seus mapas na próxima atualização deles.
- Conectores e rastreadores reportam o tempo todo, então quem decide é o turno. Em uma frota Manual, as posições deles só passam enquanto houver um turno aberto por um motorista, um check-in ou o Studio. Em uma frota com Horários Programados, o horário de turnos do veículo abre e fecha os turnos dele.
- Remover um dispositivo encerra o turno que ele iniciou.
Precisão pública
Privacidade e Exibição, na página da frota, define com que precisão os visitantes veem seus veículos:
| Precisão pública | Os visitantes veem | Direção e velocidade |
|---|---|---|
| Exata | A posição com cerca de 1 metro de precisão | Mostradas |
| Rua, Cerca de 100 m (o padrão) | A posição arredondada para cerca de 100 metros | Mostradas |
| Área, Cerca de 1 km | A posição arredondada para cerca de 1 quilômetro | Omitidas |
- Um veículo com check-in em uma parada é mostrado na posição da própria parada.
- Marcar como Desatualizado Após (de 30 a 900 segundos; 120 por padrão): um veículo que não reporta por mais tempo mostra Visto há 5 min.
- Ocultar Após (de 60 a 3.600 segundos; 900 por padrão): um veículo que não reporta por mais tempo não é mostrado.
- Os visitantes veem apenas o nome, o tipo, a cor, a descrição, o status, a posição arredondada e há quanto tempo cada veículo informou pela última vez, além da direção e da velocidade, exceto em Área, Cerca de 1 km. Dispositivos, IDs externos e histórico nunca são publicados.
Histórico e retenção
Você vê o trajeto de cada veículo em um dia em Histórico, com precisão total. O histórico mantém no máximo um ponto a cada 30 segundos, ou a cada intervalo de atualização do seu plano quando ele for maior, além de qualquer ponto a 200 metros ou mais do último mantido. Os pontos são excluídos depois dos dias de histórico do seu plano, e nunca mantidos por mais de 90 dias.
- Apagar Histórico (proprietários e administradores) exclui de uma vez todas as posições e turnos encerrados de um veículo.
- Excluir um veículo ou uma frota exclui o histórico junto. Desfazer o pareamento de um dispositivo mantém o histórico do veículo.
- Um plano com menos dias de histórico remove o histórico excedente na próxima limpeza diária.
Os motoristas não são contas Kaleidr. Nada aqui identifica uma pessoa além dos nomes de dispositivo que você digita.
Estimativas de chegada
O layout ao vivo mostra quanto tempo um veículo levaria até a próxima parada, ou até um visitante que pergunta Quanto tempo até mim?. Cada um desses tempos é uma Estimativa:
- Ela é calculada a partir da distância por estrada e de velocidades típicas. O trânsito não é considerado, e o trajeto real do veículo pode ser outro.
- Ela parte da posição que os visitantes veem, na precisão pública da frota.
- É mostrada como uma duração, Cerca de 12 min, nunca como horário de chegada. Sem percurso por estrada, Sem estimativa.
- A localização de um visitante é usada apenas para essa estimativa, e nunca é armazenada nem registrada.
- Os percursos por estrada são construídos com dados do OpenStreetMap, © colaboradores do OpenStreetMap, sob a ODbL.
As estimativas são limitadas a 20 por minuto para um visitante e 2.000 por dia para um mapa. Elas não contam para o seu uso da Kaleidr AI.
Apenas em mapas da Kaleidr
Os veículos ao vivo são desenhados em mapas que usam o mapa base próprio da Kaleidr: todos os viewers incorporados e o Studio. O Kaleidr Map não desenha os veículos de uma frota enquanto mostra o mapa de outro provedor. Nenhuma posição de veículo é enviada a um provedor de mapas terceiro.
Limites
| Limite | Free | Pro | Enterprise |
|---|---|---|---|
| Veículos ativos em toda a organização | 2 | 25 | Definido no seu contrato |
| Dias de histórico de posições | 1 | 30 | 90 |
| Intervalo mínimo entre os pontos de um veículo | 30 segundos | 10 segundos | 5 segundos |
| Conectores | Nenhum | 3 | Definido no seu contrato |
Uma frota tem no máximo 500 veículos. Um limite só impede trabalho novo: uma organização acima de um limite mantém o que tem, exceto o histórico além dos dias do plano e os conectores além do plano, que ficam pausados.
Uso, na página da frota, mostra as contagens de hoje: posições aceitas, posições descartadas e o motivo, leituras de visitantes e estimativas.