Conectar o Vizion: rastrear contêineres com marcos a partir de uma API key emitida por vendas
A API Key do Vizion é emitida pelas vendas do Vizion na abertura da sua conta: não há cadastro self-service. Cole a chave como único campo api_key no Integration, teste, mapeie e ative.
O conector do Vizion faz um único trabalho: rastreamento de contêineres para drayage. Você inicia um rastreamento (uma referência) com um número de contêiner, de conhecimento de embarque ou de reserva, e o conector devolve as atualizações de marcos desse embarque: cada marco traz um horário planejado (uma estimativa, ETA) ou um horário real (ATA), para você ver tanto o esperado quanto o que realmente aconteceu. Esse é todo o escopo: não traz pedidos, não cria embarques nem despachos, não agenda horários no terminal e não escreve nada de volta no Vizion. Uma conexão trabalha com uma API Key do Vizion.
Pré-requisitos#
- Uma conta do Vizion aberta com as vendas do Vizion, com acesso à API incluído. A API Key é emitida pelas vendas do Vizion na abertura da conta: não há página de cadastro self-service, então, se você ainda não tem uma chave, obtê-la com as vendas do Vizion é o passo zero, antes de qualquer coisa neste sistema.
- A API Key em si, exatamente como as vendas do Vizion a emitiram para você. Guarde a mensagem ou o documento original em que ela chegou: se a chave for perdida ou recusada, só as vendas do Vizion podem reemiti-la; não dá para consultá-la nem regenerá-la numa página de configurações.
- Pelo menos um número de contêiner, de conhecimento de embarque ou de reserva que você realmente queira rastrear, para conferir os primeiros marcos com um embarque que conhece. Quando tiver o código da transportadora (SCAC) desse embarque, deixe-o pronto também: o Vizion pode identificar a transportadora automaticamente, mas sua própria orientação é fornecer o código da transportadora sempre que puder.
Obter credenciais#
- Entre em contato com as vendas do Vizion e abra sua conta do Vizion com acesso à API, se ainda não o fez. A API Key é emitida pelas vendas do Vizion como parte da abertura da conta.
- Receba a API Key das vendas do Vizion. Não há cadastro self-service nem página de desenvolvedores onde você possa criar uma: se uma página ou uma pessoa oferecer "registrar" uma chave do Vizion fora do processo de abertura da conta, não é assim que esta chave é emitida.
- Copie a chave completa de uma vez, exatamente como foi emitida (as chaves desta conexão começam com vizion_), e deixe-a pronta para colar. Não a encurte e não adicione nenhum prefixo.
- Só há esta credencial, e só um endereço do Vizion para conhecer: https://prod.vizionapi.com. Não há um endereço de sandbox separado para configurar: a chave que foi emitida para você é testada e executada nesse mesmo endereço.
Preencher no Integration#
- Abra Integration → Marketplace → Vizion → Nova conexão.
- api_key, obrigatório, Vizion API Key: cole a chave completa que as vendas do Vizion emitiram para você, começando com vizion_. É o único campo desta conexão. É um campo do tipo senha e é guardado como segredo. Cole apenas a chave, exatamente como foi emitida: o sistema a envia sozinho como cabeçalho X-API-Key.
- Salve a conexão e execute o teste antes de mudar qualquer outra coisa: com um único campo, um teste que falha é sobre essa chave ou sobre se a conta por trás dela está ativa, não sobre descobrir qual de muitos campos está errado.
Testar a conexão#
Clique em Testar a conexão. Com sua chave preenchida, o teste envia uma solicitação real, somente leitura: GET https://prod.vizionapi.com/references?limit=1, com sua chave enviada como cabeçalho X-API-Key, com limite de 12 segundos. Ele só lista suas referências ativas, limitadas a uma, então não muda nada no Vizion. Uma resposta aprovada volta como "Vizion authentication passed". Se a chave for recusada, o teste reporta HTTP_401. Se api_key estiver vazio, para com MISSING_CREDENTIALS. Uma solicitação que não pode ser concluída reporta CONNECTION_FAILED. Corrija a causa indicada pelo resultado e teste novamente.
Mapping / escolher modelo#
Escolha o mapping padrão do Vizion. Ele pega cada atualização de marco que o Vizion devolve para uma referência e a alinha com o registro do contêiner que você acompanha aqui no rastreamento de drayage, mantendo a distinção que o próprio Vizion faz: um marco marcado como planejado traz um horário estimado (ETA), e um que não está marcado traz o horário real (ATA). Depois que o teste aprovar, inicie o rastreamento de um contêiner, conhecimento de embarque ou reserva que você conheça e compare os primeiros marcos (evento, lugar, e se cada horário é planejado ou real) com o que o Vizion mostra para o mesmo embarque. Se coincidirem, o mapping está certo e você pode ativar.
Ativar#
Após ativar, você pode iniciar o rastreamento a partir de um número de contêiner, de conhecimento de embarque ou de reserva, e a conexão mantém as atualizações de marcos dessas referências chegando aqui ao rastreamento de drayage. Ao iniciar uma referência, aplicam-se duas regras do Vizion: informe o conhecimento de embarque ou o número de reserva, nunca os dois juntos (uma solicitação com os dois é rejeitada), e adicione o código da transportadora (SCAC) sempre que o tiver, porque a identificação automática da transportadora é o recurso de reserva, não o caminho preferido. As atualizações de uma referência também podem chegar como notificações enviadas, no mesmo formato das atualizações obtidas, então o que você vê aqui permanece consistente nos dois casos. Acompanhe as primeiras referências em Runs / Logs e compare alguns embarques com o Vizion antes de deixar a conexão sem supervisão.
O que esta conexão não faz: não traz pedidos nem embarques de nenhum outro sistema, não cria despachos nem cargas, não agenda nem altera horários no terminal e não envia dados de rastreamento de volta ao Vizion. Além disso, ela só rastreia as referências que você inicia: não importa um histórico de embarques criado em outro lugar.
Perguntas frequentes#
O teste falha com HTTP_401
O Vizion recusou a chave enviada. As causas habituais são uma chave cortada ao copiar, um caractere diferente do original emitido, ou uma chave que o Vizion já substituiu ou ainda não ativou na sua conta. Esta conexão envia a chave como cabeçalho X-API-Key, exatamente como a documentação oficial especifica, então o formato de envio não é a variável: o valor da chave é.
Compare a chave colada caractere por caractere com o original que as vendas do Vizion emitiram para você, corrija qualquer diferença, salve e teste novamente. Se a chave colada coincidir exatamente com o original e o teste continuar reportando HTTP_401, entre em contato com as vendas do Vizion e peça que confirmem se a chave está ativa na sua conta ou que a reemitam: só as vendas do Vizion podem fazer isso, não há nenhuma página onde você possa redefini-la sozinho.
O teste para com MISSING_CREDENTIALS
O campo api_key está vazio, então não há chave para enviar e o teste não pode verificar nada. Esta conexão tem exatamente um campo, então a credencial não pode estar escondida em outro lugar.
Cole a chave completa que as vendas do Vizion emitiram para você em api_key, salve a conexão e teste novamente. Se você ainda não tem uma chave, obtenha-a primeiro com as vendas do Vizion: não há página de cadastro para criar uma.
Não há página de cadastro: de onde vem uma API Key do Vizion?
Isso é assim por design do lado do Vizion: a API Key não é self-service. As chaves são emitidas pelas vendas do Vizion quando uma conta do Vizion é aberta, então deliberadamente não há nenhuma página pública que crie uma, e este sistema também não pode gerar uma para você.
Entre em contato com as vendas do Vizion, abra a conta com acesso à API e receba a chave deles. Depois volte a esta conexão, cole a chave em api_key, salve e teste. Se sua empresa já tem uma conta do Vizion, pergunte ao colega que a abriu onde a chave emitida ficou registrada, antes de abrir uma segunda conta.
Iniciar o rastreamento falha com INVALID_REQUEST: conhecimento de embarque e reserva juntos
O Vizion valida os dois números como alternativas: uma solicitação de rastreamento pode trazer um conhecimento de embarque ou um número de reserva, mas uma solicitação com os dois juntos é rejeitada por essa validação. É uma regra do lado do Vizion, não um erro de nenhum dos números: cada um sozinho é aceitável.
Inicie o rastreamento novamente com apenas um dos dois números: mantenha o conhecimento de embarque ou o número de reserva e remova o outro. Como alternativa, você pode informar um número de contêiner como identificador. Adicione também o código da transportadora (SCAC) quando o tiver.
Iniciar o rastreamento falha com INVALID_REQUEST: nenhum identificador
Nenhum identificador foi informado para a referência. O Vizion inicia o rastreamento a partir de um identificador (um número de contêiner (container_id), de conhecimento de embarque ou de reserva) e, sem nenhum dos três, não há nada para o que abrir uma referência.
Inicie o rastreamento novamente com um dos três números desse embarque, e lembre a regra de combinação: se usar o conhecimento de embarque, não adicione também o número de reserva. Adicione o código da transportadora (SCAC) quando o tiver, para o Vizion não precisar identificar a transportadora automaticamente.
O teste falha com CONNECTION_FAILED, ou expira após 12 segundos
A solicitação somente leitura a prod.vizionapi.com não pôde ser concluída a tempo. É um problema de alcance no caminho até a API do Vizion, ou uma lentidão temporária do Vizion: não é prova de que a chave está errada, porque a chave só é julgada quando a API realmente responde.
Aguarde um pouco e teste novamente sem mudar a chave. Se continuar falhando, anote o horário da falha de Runs / Logs quando pedir ajuda, e diga ao suporte do Vizion que a solicitação vai para https://prod.vizionapi.com com a chave no cabeçalho X-API-Key, para que possam conferir a mesma janela do lado deles.
O horário de um marco parece errado: está no futuro, ou mudou
Esse marco é muito provavelmente um planejado. Nos dados do Vizion, um marco marcado como planned=true traz um horário estimado (uma ETA), que por natureza está no futuro e é revisado conforme o embarque avança; um marco com planned=false traz o horário real (uma ATA), que fica fixo depois que acontece. A estimativa mudar é os dados funcionando como devem, não o rastreamento estar errado.
Leia o marco junto com sua marca de planejado antes de agir sobre o horário: planeje em torno dos horários planejados (ETA) e trate apenas os horários reais (ATA) como histórico. Se um horário marcado como real discordar do que a transportadora ou o terminal mostram para o mesmo evento, anote a referência e o evento quando pedir ao suporte do Vizion que verifique.