Conectar o Mapbox: distância, duração e ETA de rotas para rotas TMS
Copie um Access Token em account.mapbox.com → Access Tokens, preencha esse único access_token no Integration, teste com uma chamada real à Directions, escolha o modelo de planejamento de rotas e ative: o TMS obterá distância, duração e rota para custo de rota e ETA.
O conector do Mapbox é uma fonte de dados de rotas para o TMS. Ele usa a Mapbox Directions API para calcular uma rota por vez (distância, duração e a própria rota), para que embarques e cotações no TMS usem esse resultado como base do custo de rota e do ETA. Esse é seu único trabalho: não traz nem envia pedidos, não sincroniza clientes nem estoque, não rastreia veículos e não calcula a melhor ordem de visita para muitas paradas. Uma conexão guarda um único Mapbox Access Token.
Pré-requisitos#
- Uma conta do Mapbox com a qual você consiga entrar em account.mapbox.com e acessar a página Access Tokens.
- Você entende que testar esta conexão gera uso: não há um endpoint de sondagem gratuito para a Directions API, então cada teste é uma chamada real de rota e usa uma cota. Não clique em testar repetidamente sem motivo.
- Suas rotas se encaixam no que a Directions API aceita por este conector: as coordenadas são enviadas na ordem longitude,latitude, e uma solicitação de rota leva no máximo 25 coordenadas.
- Permissão neste sistema para abrir o Integration e criar uma nova conexão.
Obter credenciais#
- Entre em account.mapbox.com e abra Access Tokens.
- Copie um token dessa página por completo. Os tokens mostrados para este conector começam com pk.… ou sk.…: copie o valor inteiro tal como exibido, sem cortar nada em nenhuma ponta e sem adicionar espaços.
- Guarde esse token como o único valor que você precisa trazer. Esta conexão envia o token ao Mapbox como o parâmetro de consulta access_token em cada solicitação à Directions, então não há outra chave, usuário nem senha para coletar nessa página.
Preencher no Integration#
- Abra Integration → Marketplace → Mapbox → Nova conexão.
- access_token, obrigatório, Mapbox Access Token: cole o token completo que você copiou de account.mapbox.com → Access Tokens. É um campo do tipo senha e é guardado como segredo. Este conector não tem um segundo campo: aqui não se preenche usuário, senha nem campo de conta.
- Salve a conexão antes de testar, para que o teste use exatamente o token que você acabou de inserir. O token será enviado como o parâmetro de consulta access_token na solicitação de teste.
Testar a conexão#
Clique em Testar a conexão. Com um token preenchido, o teste faz uma chamada real e mínima à Directions: envia uma solicitação GET para https://api.mapbox.com/directions/v5/mapbox/{profile}/{coordinates} com seu token como o parâmetro de consulta access_token. Aprovar significa que o access token é válido e que a Directions API está acessível, e a mensagem de sucesso diz isso com palavras: access token válido, Directions API acessível (a sondagem consome uma cota). Leia essa última parte ao pé da letra: esta sondagem é uma chamada real e usa uma cota toda vez que você a executa, então teste uma vez, corrija a causa se falhar e só então teste de novo.
Mapping / escolher modelo#
Escolha o modelo de planejamento de rotas, o único que este conector usa. Não há campos de pedidos nem de clientes para mapear. O que o modelo define é o perfil da Directions para cada modo de viagem pedido no TMS (driving, driving-traffic, walking e cycling vão ao Mapbox como o perfil de mesmo nome) e o formato da própria solicitação: coordenadas na ordem longitude,latitude, com no máximo 25 coordenadas numa rota. Depois que o teste aprovar, peça no TMS uma rota que você já conhece e compare a distância e a duração devolvidas com o que você espera para aquela rota, antes de ativar.
Ativar#
Após ativar, o TMS pode pedir uma rota a esta conexão quando um embarque ou uma cotação precisa de uma estimativa de rota: a conexão devolve distância, duração e a rota, e o TMS os usa como base do custo de rota e do ETA. Acompanhe as primeiras solicitações reais em Runs / Logs e compare algumas distâncias e durações devolvidas com rotas que você conhece, antes de deixar a conexão sem supervisão.
O que esta conexão não faz: ela só oferece planejamento de rotas pela Directions API. Não calcula a melhor ordem para visitar muitas paradas, não traz pedidos, não sincroniza clientes nem estoque e não acompanha um veículo enquanto ele se move. Se uma tela do TMS não mostrar pedidos novos após a ativação, é o esperado: os pedidos vêm dos seus canais de pedidos, e esta conexão só responde quando o TMS pergunta qual a distância, quanto tempo e qual a rota.
Perguntas frequentes#
O teste falha e diz que o access token não é válido
O valor em access_token não é um token completo e válido da sua conta do Mapbox: um caractere se perdeu ao copiar, um espaço a mais veio junto, ou o token foi copiado de outra conta, diferente da que você queria usar. O teste envia o token tal como está salvo, como o parâmetro de consulta access_token, então qualquer diferença basta para o Mapbox recusá-lo.
Entre em account.mapbox.com, abra Access Tokens, copie de novo um token dessa página de uma só vez, cole em access_token sem digitar nenhuma parte à mão, salve e teste uma vez.
O uso sobe mesmo que a conexão ainda não esteja ativada
Cada teste é uma chamada real. A Directions API não tem um endpoint de sondagem gratuito, então o teste só pode provar que o token funciona pedindo uma rota real, e essa solicitação usa uma cota, exatamente como diz a mensagem de sucesso: a sondagem consome uma cota. Testar repetidamente antes de ativar é uso real.
Teste uma vez. Se falhar, leia a falha, corrija essa única causa no token e só então teste de novo. Quando o teste aprovar, siga para o modelo e a ativação em vez de testar outra vez para reconfirmar.
Uma rota com muitas paradas falha ou volta sem resultado
O formato da solicitação não se encaixa na Directions API por este conector: uma rota leva no máximo 25 coordenadas, e as coordenadas devem ir na ordem longitude,latitude. Uma lista montada como latitude,longitude, ou uma rota carregada com mais coordenadas que o limite, não devolverá a rota que você esperava.
Verifique a lista de coordenadas dessa rota: coloque cada ponto na ordem longitude,latitude e mantenha a quantidade em 25 ou menos. Para uma viagem mais longa, divida-a em trechos de no máximo 25 coordenadas cada um e calcule os trechos um por um.
Distâncias e durações parecem erradas numa rota que você conhece bem
A rota foi calculada com um perfil da Directions diferente do que você esperava, ou com os dois números de um ponto trocados. O modelo envia driving, driving-traffic, walking e cycling como o perfil de mesmo nome, e os pontos vão na ordem longitude,latitude: um resultado a pé lido como resultado de carro, ou um ponto com a latitude primeiro, dá uma rota que parece errada mesmo que a chamada tenha funcionado.
Verifique duas coisas dessa rota: o perfil que a solicitação do TMS usou e a ordem de cada par de coordenadas. Corrija o perfil ou a ordem do par para corresponder à rota, recalcule e julgue o novo resultado só contra o mesmo perfil.
As paradas voltam na ordem dada, não na melhor ordem
Esse é o limite desta conexão. Ela calcula uma rota pelos pontos na ordem em que são dados, usando a Directions API. Calcular a melhor ordem de visita para muitas paradas é outro trabalho, e esta conexão não faz isso: a rota está correta para a ordem fornecida, só não é reordenada para você.
Decida você a ordem de visita no TMS antes de pedir a rota, e entregue os pontos a esta conexão nessa ordem. Julgue esta conexão só pela distância, pela duração e pela rota para a ordem que você forneceu.
Ativada, mas não aparecem pedidos nem rastreamento em lugar nenhum
Nada está quebrado. Esta conexão nunca transportou pedidos nem rastreamento: sua única capacidade é o planejamento de rotas, então ativar não adiciona uma fonte de pedidos nem posições de veículos, só permite que o TMS peça distância, duração e rota quando um embarque ou uma cotação precisa de uma estimativa de rota.
Use seus canais de pedidos para os pedidos e as ferramentas da transportadora para o rastreamento. Use esta conexão só onde um custo de rota ou um ETA é necessário, e confira seu trabalho no resultado de rota de um embarque ou uma cotação no TMS.