Conectar o Motive: levar as localizações dos veículos ao rastreamento

Conclua o fluxo OAuth 2.0 do Motive fora deste sistema, cole o access token no Integration, deixe a URL base da API no padrão, salvo se usar um endpoint regional, teste, mapeie e ative.

O conector do Motive lê as localizações dos veículos da sua frota Motive (antes KeepTruckin) e as converte em eventos de rastreamento no TMS, para acompanhar um embarque em trânsito pela posição do 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 Motive. Uma conexão trabalha com um access token do Motive.

Pré-requisitos#

• Uma conta de frota do Motive com veículos que reportam localizações, e os veículos que você quer acompanhar já configurados no Motive.
• Uma forma de concluir o fluxo authorization_code do OAuth 2.0 do Motive fora deste sistema: autorizar em gomotive.com/oauth/authorize e trocar o código em gomotive.com/oauth/token. Esta conexão não tem botão de autorização dentro do sistema: você traz um access token já obtido e o cola.
• O token deve ter a permissão de localização de veículos. Sem essa permissão, o teste responde MISSING_SCOPE, então verifique as permissões do App no Motive Developer Portal antes de testar.
• Você sabe se sua frota usa o endereço de API padrão do Motive ou um endpoint regional. A maioria das frotas usa o endereço padrão e deixa base_url vazio.

Obter credenciais#

1. Inicie o fluxo OAuth 2.0 do Motive fora deste sistema: abra gomotive.com/oauth/authorize e aprove o acesso do seu App de frota, seguindo o fluxo authorization_code com o qual seu App do Motive foi configurado.
2. Troque o código de autorização em gomotive.com/oauth/token para obter o access token. O token é uma cadeia longa, no formato mostrado na etapa de preenchimento, começando com caracteres como eyJraWQiOiIyMDIwXzEi.
3. Copie o access token completo de uma vez e deixe-o pronto para colar. Não o encurte e não adicione espaços nem quebras de linha: um token cortado responde INVALID_TOKEN.
4. Lembre-se de que este token expira. Quando expira, esta conexão não pode renová-lo por você: você repete o mesmo fluxo authorization_code do OAuth e cola o token novo. Planeje essa renovação antes que a frota pare de reportar.

Preencher no Integration#

1. Abra Integration → Marketplace → Motive → Nova conexão.
2. token, obrigatório, OAuth2 access token: cole o access token completo que você trocou em gomotive.com/oauth/token, por exemplo uma cadeia longa começando com eyJraWQiOiIyMDIwXzEi. É um campo do tipo senha e é guardado como segredo.
3. base_url, opcional, URL base da API: deixe vazio para usar o padrão https://api.gomotive.com. Preencha apenas quando sua frota usar um endpoint regional da API do Motive e, nesse caso, preencha esse endereço de endpoint exatamente como o Motive o forneceu.

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}/v2/vehicle_locations com seu token como credencial Bearer, com limite de 12 segundos. Uma resposta 200 significa que o token é aceito e que o endpoint de localizações responde. Uma resposta 401 volta como INVALID_TOKEN: o token é inválido ou expirou. Uma resposta 403 volta como MISSING_SCOPE: o token não tem a permissão de localização de veículos. Uma solicitação que não responde a tempo volta como TIMEOUT. Corrija a causa indicada pelo código e teste novamente: o teste não altera nenhum dado no Motive.

Mapping / escolher modelo#

Escolha o mapping padrão do Motive. Ele pega cada localização de veículo devolvida para sua frota e a 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 aqui com o mesmo veículo no Motive. Se a posição coincidir, o mapping está certo e você pode ativar.

Ativar#

Após ativar, a conexão lê as localizações dos veículos do Motive com seu token e mantém o rastreamento do TMS atualizado com as últimas posições da frota. Acompanhe as primeiras leituras em Runs / Logs e compare alguns veículos com o Motive antes de deixar a conexão sem supervisão, e anote a data de expiração do token para renová-lo a tempo.

O que esta conexão não faz: não traz pedidos nem cargas do Motive, não cria nem altera despachos, não lê registros do motorista, horas de serviço nem registros de combustível, e não envia posições nem nenhum outro dado de volta ao Motive. Continue cuidando disso no próprio Motive ou nos sistemas onde o trabalho realmente acontece.

Perguntas frequentes#

O teste falha com INVALID_TOKEN (401)

O Motive recusou o token: ele é inválido ou expirou. Os access tokens do fluxo authorization_code do OAuth não duram para sempre, e um token cortado ao copiar é recusado do mesmo jeito: o teste não distingue um token cortado de um expirado.

Repita o fluxo authorization_code do OAuth do Motive (autorize em gomotive.com/oauth/authorize e troque o código em gomotive.com/oauth/token), copie o novo access token completo, cole no campo token, salve e teste novamente. Esta conexão não tem botão de renovar: um token novo sempre vem de uma nova volta do OAuth.

O teste falha com MISSING_SCOPE (403)

O token em si foi aceito, mas não tem a permissão de localização de veículos, então o Motive não permite que ele leia as localizações. Os valores que você preencheu não são o problema: a permissão não foi concedida ao App quando o token foi emitido.

Abra o Motive Developer Portal, verifique as permissões do App e garanta que o acesso às localizações de veículos está concedido; depois repita o fluxo OAuth para emitir um token com essa permissão, cole o token novo e teste novamente.

O teste falha com TIMEOUT

A solicitação de localizações não respondeu em 12 segundos. É um problema de alcance no caminho até a API do Motive (uma base_url incorreta, um endpoint regional que não responde para sua frota ou uma lentidão temporária da API do Motive), não uma prova de que o token está errado.

Verifique primeiro base_url: deixe vazio para o padrão https://api.gomotive.com, salvo se sua frota realmente usar um endpoint regional. Depois teste novamente. Se o timeout se repetir com o endereço padrão, aguarde um pouco e tente de novo, e guarde o horário da falha de Runs / Logs quando pedir ajuda.

Conectava antes, depois as localizações pararam de atualizar

A causa mais comum é o access token ter chegado à data de expiração. A conexão mantém o token antigo e não pode renová-lo sozinha, então as leituras começam a falhar, normalmente com INVALID_TOKEN nos registros, sem que nada mais tenha mudado na conexão.

Repita o fluxo authorization_code do OAuth, cole o novo access token no campo token, salve e teste. Quando o teste aprovar, as posições voltam. Desta vez, anote a nova data de expiração para que a próxima renovação aconteça antes de vencer.

Conectado, mas um veículo não mostra posição

A conexão devolve as localizações que o Motive tem da frota: se o próprio Motive não tiver uma localização 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 Motive não tem.

Verifique primeiro esse mesmo veículo no Motive. Se o Motive 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 Motive também não mostrar nada, corrija o reporte desse veículo no lado do Motive.

Por que nenhum pedido ou despacho chega pelo Motive?

Porque este conector só lê localizações de veículos. Pedidos, cargas e despachos não fazem parte do que ele pode ler do Motive, 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.