Conectar o Terminal49: rastrear contêineres por contêiner, conhecimento de embarque ou reserva
Obtenha você mesmo uma Developer Key gratuita em app.terminal49.com/developers/api-keys, cole-a como único campo api_key no Integration, teste, mapeie e ative.
O conector do Terminal49 faz um único trabalho: rastreamento de contêineres para drayage. Você inicia o rastreamento com um número de contêiner, de conhecimento de embarque ou de reserva, e o conector devolve marcos, programações de navios e disponibilidade no terminal, incluindo o Last Free Day, as retenções (holds) e as taxas reportadas pelo terminal. 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 Terminal49. Uma conexão trabalha com uma API Key do Terminal49.
Pré-requisitos#
- Uma conta do Terminal49 com a qual você consiga entrar em app.terminal49.com, para abrir você mesmo a página de chaves de API para desenvolvedores. A chave é self-service: para começar, não é preciso falar com vendas nem esperar aprovação.
- Pelo menos um número de contêiner, de conhecimento de embarque ou de reserva que você realmente queira rastrear, para conferir os primeiros resultados com um embarque que conhece.
- Calcule seu volume de rastreamento antes de depender da chave gratuita: uma Developer Key gratuita rastreia até 100 contêineres. É mais do que suficiente para avaliar a conexão, mas planeje a chave de produção conforme o número de contêineres que você rastreia ao mesmo tempo.
Obter credenciais#
- Entre em app.terminal49.com e abra a página de chaves de API para desenvolvedores: app.terminal49.com/developers/api-keys.
- Crie uma chave nessa página. Uma Developer Key gratuita basta para conectar e avaliar: rastreia até 100 contêineres.
- Copie a API Key completa de uma vez e deixe-a pronta para colar. Não a encurte e não adicione nenhum prefixo: a chave sozinha é toda a credencial.
- Só há esta credencial. Não há usuário, senha, chave de sandbox nem segunda chave separada para coletar, e teste e produção usam o mesmo endereço do Terminal49: a mesma chave é a que você testa e a que fica em produção.
Preencher no Integration#
- Abra Integration → Marketplace → Terminal49 → Nova conexão.
- api_key, obrigatório, Terminal49 API Key: cole a chave completa que você copiou de app.terminal49.com/developers/api-keys. É o único campo desta conexão. É um campo do tipo senha e é guardado como segredo. Cole apenas a chave, sem a palavra "Token" nem "Bearer" na frente: o sistema adiciona sozinho o formato do cabeçalho.
- 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, 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://api.terminal49.com/v2/tracking_requests?page[size]=1, com sua chave enviada como "Authorization: Token <API_KEY>", com limite de 12 segundos. Ele só lê a primeira página das suas solicitações de rastreamento existentes, então não muda nada no Terminal49. Uma resposta aprovada volta como "Terminal49 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 Terminal49. Ele pega cada resultado de rastreamento que o Terminal49 devolve (marcos, programação do navio e disponibilidade no terminal, como Last Free Day, retenções e taxas) e o alinha com o registro do contêiner que você acompanha aqui no rastreamento de drayage. Depois que o teste aprovar, inicie o rastreamento de um contêiner, conhecimento de embarque ou reserva que você conheça e compare os marcos e as datas do terminal lado a lado com o que o Terminal49 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 (informe um dos três, mais o SCAC da transportadora quando o tiver) e a conexão mantém atualizados aqui os marcos, a programação do navio e a disponibilidade no terminal desses contêineres. As solicitações de rastreamento são limitadas a 100 por minuto do lado do Terminal49, então inícios em massa muito grandes são distribuídos em vez de disparados todos de uma vez. Acompanhe os primeiros resultados em Runs / Logs e compare alguns contêineres com o Terminal49 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 Terminal49. Além disso, ela só rastreia os contêineres para os quais você inicia o rastreamento: não descobre nem importa todo o seu histórico de embarques do Terminal49.
Perguntas frequentes#
O teste falha com HTTP_401
O Terminal49 recusou a chave enviada. As causas habituais são uma chave cortada ao copiar, uma palavra extra colada na frente, ou uma chave excluída ou substituída na sua conta do Terminal49 depois de copiada. O endereço e a conexão estão bem: este código trata apenas da chave.
Abra app.terminal49.com/developers/api-keys, crie uma chave nova, copie-a completa e sem nada na frente, cole no campo api_key, salve e teste novamente. Se você estava verificando a API manualmente, lembre que o formato do cabeçalho é "Authorization: Token <API_KEY>": uma verificação estilo Bearer falha mesmo com a chave certa.
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 de app.terminal49.com/developers/api-keys em api_key, salve a conexão e teste novamente.
O teste falha com CONNECTION_FAILED, ou expira após 12 segundos
A solicitação somente leitura à API do Terminal49 não pôde ser concluída a tempo. É um problema de alcance no caminho até api.terminal49.com, ou uma lentidão temporária do Terminal49: 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, para que a janela possa ser conferida com o lado do Terminal49.
Iniciar o rastreamento falha com INVALID_REQUEST
Nenhum identificador foi informado para a solicitação de rastreamento. O Terminal49 inicia o rastreamento a partir de um identificador (um número de contêiner, de conhecimento de embarque ou de reserva) e, sem nenhum dos três, não há nada para iniciar.
Inicie o rastreamento novamente com um dos três números desse embarque e adicione o SCAC da transportadora quando o tiver: isso ajuda o Terminal49 a associar a solicitação à transportadora certa.
Iniciar o rastreamento falha com HTTP_429 ao iniciar muitos contêineres de uma vez
Você atingiu o limite de taxa do Terminal49: as solicitações de rastreamento têm um teto de 100 por minuto. Não há nada de errado com a chave nem com os contêineres que falharam: eles foram apenas enviados mais rápido do que o Terminal49 os aceita.
Inicie novamente os contêineres que falharam em lotes menores, distribuídos por mais de um minuto, em vez de tentar de novo o conjunto todo de uma vez. Os que já começaram continuam sendo rastreados normalmente.
Novos contêineres param de ser rastreados depois de cerca de 100
Você está usando a Developer Key gratuita, que rastreia até 100 contêineres. A conexão e a chave estão funcionando (os primeiros cem provam isso), mas a chave gratuita não tem espaço para mais contêineres ao mesmo tempo.
Mude a conexão para uma chave do Terminal49 com um limite de contêineres compatível com seu volume real: crie ou obtenha essa chave na sua conta do Terminal49, cole em api_key no lugar da chave gratuita, salve e teste. O rastreamento já iniciado com a chave gratuita não é uma configuração deste sistema: verifique primeiro o limite da chave sempre que o volume crescer.