Conectar o Samsara: levar o GPS dos veículos ao rastreamento
Gere um API Token no Samsara Dashboard em Settings → API Tokens com acesso de leitura a fleet, vehicles e stats, cole no Integration, escolha a URL base dos EUA ou da UE conforme sua região, teste, mapeie e ative.
O conector do Samsara lê o GPS dos veículos da sua frota Samsara (para cada veículo, o horário GPS, a latitude e a longitude, a direção, a velocidade e o nome do lugar consultado para aquela posição) e converte essas posições em eventos de rastreamento no TMS, para acompanhar um embarque em trânsito por veículo. Esse é o seu único trabalho: ele só lê localizações de veículos. Não traz pedidos, não cria despachos nem cargas, não lê registros do motorista nem horas de serviço e não escreve nada de volta no Samsara. Uma conexão trabalha com um API Token do Samsara.
Pré-requisitos#
- Uma conta de frota do Samsara com veículos que reportam GPS, e os veículos que você quer acompanhar já configurados no Samsara.
- Permissão no Samsara Dashboard para abrir Settings → API Tokens e gerar um token. Gerar um token é uma tarefa do lado do administrador: se você não conseguir ver essa página, peça ao seu administrador do Samsara para criar o token para você.
- O token deve ter acesso de leitura a fleet, vehicles e stats. Um token gerado sem o acesso de leitura a stats não consegue ler as stats GPS das quais esta conexão depende, e o teste e as leituras falharão por permissão.
- Você sabe a qual região sua conta do Samsara pertence. Contas dos EUA usam https://api.samsara.com; contas da UE usam https://api.eu.samsara.com. A região decide base_url, e a região errada não responderá para sua frota.
Obter credenciais#
- Entre no Samsara Dashboard com uma conta que possa gerenciar API tokens e abra Settings → API Tokens.
- Gere um novo API Token para esta integração. Ao gerá-lo, conceda acesso de leitura a fleet, vehicles e stats, os três, porque a conexão lê o GPS dos veículos a partir das stats da frota.
- Copie o token que o Samsara mostra, completo. Ele começa com samsara_api_ seguido de uma longa cadeia de caracteres. Copie no momento da geração e deixe pronto para colar: trate-o como uma senha a partir deste momento.
- Ao mesmo tempo, confirme mais uma vez sua região: EUA se sua conta estiver no lado americano, UE se estiver no lado europeu. Você usará essa resposta para base_url na próxima etapa.
Preencher no Integration#
- Abra Integration → Marketplace → Samsara → Nova conexão.
- api_token, obrigatório, API Token: cole o token completo que você gerou no Samsara Dashboard em Settings → API Tokens, começando com samsara_api_. É um campo do tipo senha e é guardado como segredo.
- base_url, opcional, Base URL: este campo é o seu seletor de região. Deixe vazio, ou preencha https://api.samsara.com, para uma conta dos EUA. Clientes da UE devem preencher https://api.eu.samsara.com: com um endereço dos EUA, uma frota da UE não responderá.
Testar a conexão#
Clique em Testar a conexão. Com um token preenchido, o teste envia uma solicitação real, somente leitura: GET {base_url}/fleet/vehicles/stats?types=gps com seu token como credencial Bearer, com limite de 12 segundos. Quando aprova, o resultado confirma em palavras: a autenticação com Bearer token passou e o endpoint de localizações de veículos responde. Uma resposta 401 ou 403 significa que o token foi recusado: ele está errado, não é mais válido ou falta o acesso de leitura que o endpoint precisa. Uma solicitação que não responde a tempo é reportada como timeout. Corrija a causa e teste novamente: o teste não altera nenhum dado no Samsara.
Mapping / escolher modelo#
Escolha o mapping padrão do Samsara. Ele pega cada registro GPS de veículo (horário, latitude e longitude, direção, velocidade e o nome do lugar da posição) e o converte em um evento de rastreamento do TMS para aquele veículo, de modo que as posições coincidam com o veículo e o embarque que você acompanha no TMS. Depois que o teste aprovar, execute uma leitura e compare um veículo que você sabe que está na estrada: confira sua última posição, direção e velocidade aqui com o mesmo veículo no Samsara. Se coincidirem, o mapping está certo e você pode ativar.
Ativar#
Após ativar, a conexão lê o GPS dos veículos do Samsara com seu token e mantém o rastreamento do TMS atualizado com as últimas posições, direções e velocidades da frota. Acompanhe as primeiras leituras em Runs / Logs e compare alguns veículos com o Samsara antes de deixar a conexão sem supervisão.
O que esta conexão não faz: não traz pedidos nem cargas do Samsara, não cria nem altera despachos, não lê registros do motorista, horas de serviço, registros de câmeras ou de sensores, e não envia posições nem nenhum outro dado de volta ao Samsara. Continue cuidando disso no próprio Samsara ou nos sistemas onde o trabalho realmente acontece.
Perguntas frequentes#
O teste falha com 401: o token é recusado
O Samsara não aceitou o valor de api_token. As causas habituais estão no próprio valor: ele foi colado só em parte, foi colado um token antigo que não é mais válido, ou foi colado no campo um valor que não é um API Token do Samsara.
Vá ao Samsara Dashboard → Settings → API Tokens, gere um token novo com acesso de leitura a fleet, vehicles e stats, copie completo (começa com samsara_api_), cole em api_token, salve e teste novamente.
O teste falha com 403: falta acesso de leitura ao token
O token chegou ao Samsara, mas não tem permissão para ler o que o teste pede. Esta conexão lê o GPS dos veículos a partir das stats da frota, então um token gerado sem acesso de leitura a fleet, vehicles e stats é recusado neste endpoint, mesmo que o token em si exista.
Gere um token novo no Samsara Dashboard → Settings → API Tokens e desta vez conceda acesso de leitura a fleet, vehicles e stats antes de copiar. Cole o token novo em api_token, salve e teste novamente: o token antigo não pode ser editado, seu acesso foi fixado quando foi gerado.
O teste esgota o tempo e nunca responde
A solicitação de stats GPS não respondeu em 12 segundos. É um problema de alcance no caminho até a API do Samsara, na maioria das vezes uma base_url apontando para a região errada da sua frota, ou uma lentidão temporária da API do Samsara, não uma prova de que o token está errado.
Verifique primeiro base_url em relação à sua região: https://api.samsara.com para os EUA, https://api.eu.samsara.com para a UE. Corrija se estiver apontando para a outra região e teste novamente. Se o timeout se repetir com a região certa, aguarde um pouco e tente de novo, e guarde o horário da falha de Runs / Logs quando pedir ajuda.
Frota da UE: tudo parece certo, mas o teste continua falhando
A conexão continua apontando para o endereço de API dos EUA. base_url usa por padrão https://api.samsara.com, e uma conta da UE não responde ali: o token e seu acesso podem estar perfeitos e mesmo assim a frota da UE não responderá no endereço americano.
Defina base_url como https://api.eu.samsara.com, salve e teste a mesma conexão novamente com o mesmo token: não gere um token novo nem altere mais nada antes.
Conectado, mas um veículo não mostra GPS
A conexão devolve o GPS que o Samsara tem da frota: se o próprio Samsara não tiver um GPS atual para aquele veículo (veículo desligado, fora de cobertura ou sem reportar), não há nada para este sistema mostrar para ele. Uma conexão saudável não pode inventar uma posição que o Samsara não tem.
Verifique primeiro esse mesmo veículo no Samsara. Se o Samsara mostrar uma posição atual e este sistema não, execute uma leitura manual, compare o veículo em Runs / Logs e teste a conexão novamente. Se o Samsara também não mostrar nada, corrija o reporte desse veículo no lado do Samsara.
Por que nenhum pedido ou despacho chega pelo Samsara?
Porque este conector só lê localizações GPS de veículos. Pedidos, cargas e despachos não fazem parte do que ele pode ler do Samsara, então uma lista de pedidos vazia aqui é o comportamento esperado, não uma conexão quebrada.
Continue criando e gerenciando pedidos e despachos nos sistemas onde esse trabalho acontece, e use esta conexão para o que ela faz: acompanhar no rastreamento do TMS os veículos que levam esses embarques, com posição, direção e velocidade.