1. O que é rastreamento de logística

O rastreamento de logística é uma ferramenta crucial para monitorar o processo de transporte, permitindo que os usuários rastreiem rotas de transporte, exceções e grandes mudanças de status.

Os principais recursos da API de rastreamento incluem:

• Monitoramento automático: depois que um número de rastreamento é registrado, ele é monitorado automaticamente com os resultados da consulta sendo enviados sem consumir cotas adicionais. Observação: esse recurso opera de forma assíncrona e não é adequado para páginas da web front-end, miniprogramas ou aplicativos.
• Capacidade de nível empresarial: a API de rastreamento oferece recursos de processamento de dados de nível empresarial, permitindo o registro de 400.000 números de rastreamento por hora.
• Integração com operadora global: a API de rastreamento oferece suporte à integração com mais de 2.000 operadoras globais, fornecendo métodos de chamada unificados, estruturas de resposta e nós de status, reduzindo efetivamente os custos de desenvolvimento.
• Melhores práticas de gerenciamento de dados: é altamente recomendável armazenar informações de logística em seu servidor ou serviço de armazenamento.
• Identificação exclusiva de dados: cada pedaço de dados é identificado exclusivamente por meio da combinação de número de rastreamento + operadora.
• Visão geral do processo operacional: O processo operacional inclui Assinatura de remessa > Rastreamento periódico > Exame de alterações no status da remessa > Envio de resultados.

2. Antes de usar

2.1 Crie uma conta 17TRACK

As contas de API não são específicas do ambiente. É recomendável manter contas de API separadas para ambientes de teste e produção para garantir configurações específicas do ambiente e integridade de dados. Visite 17TRACK-Api para abrir uma conta.

 

2.2 Número de rastreamento e código da transportadora

• Visite 17TRACK para verificar a disponibilidade do número de rastreamento preparado
• Visite Carriers para verificar as transportadoras suportadas
• O que é um código de transportadora? O código da transportadora é uma especificação de parâmetro desenvolvida especificamente para uso com a API de rastreamento. Você pode encontrar mais informações em Código da transportadora. Por exemplo, o código da transportadora para USPS é 21051.

3. Guia de Integração

3.1 Integração de sistemas não terceirizados

Target User

O guia de integração a seguir é específico para provedores de logística, comerciantes, provedores de serviços e provedores de sistemas líderes que têm seus próprios sistemas proprietários e equipes de desenvolvimento de TI.

Etapa 1

(Para um teste rápido, você pode verificar o envio via https://webhook.site)

1. Certifique-se de que seu servidor esteja acessível da rede pública para receber atualizações de rastreamento. Isso pode exigir o ajuste das configurações de firewall e gateway para permitir conexões de entrada dos servidores da 17TRACK.
2. Desenvolva uma interface que possa receber informações de rastreamento e garanta que ela possa lidar com várias solicitações simultâneas. É aconselhável distribuir dados usando serviços independentes, como filas ou caches, para melhor escalabilidade.
3. Implemente a verificação de assinatura em sua interface de recebimento de informações para confirmar a autenticidade e a integridade dos dados recebidos da 17TRACK. Consulte Verificar a assinatura para obter orientação. O código de exemplo é fornecido abaixo:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

    String src = requestText + "/" + key;

    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

    BigInteger number = new BigInteger(1, hash);
    StringBuilder hexString = new StringBuilder(number.toString(16));
    while (hexString.length() < 64) {
        hexString.insert(0, '0');
    }
    return hexString.toString();
}

 

Etapa 2

1. Obtenha a chave da API efetuando login e visitando a página de configurações da API em Api-Settings.
2. Para configurar a interface para receber dados, faça login e vá para a página de configurações da API em Api-settings. Em seguida, insira a URL da interface na seção WebHook.

Etapa 3

1. Chame a interface de registro (/register) para assinar os números de rastreamento. É recomendável passar o ID de dados no sistema empresarial por meio de uma tag para facilitar o uso futuro dos resultados de push. (Referência de interface: Registrar número de rastreamento)

Etapa 4

1. Monitore a operação da interface de recebimento de informações. Para garantir que os resultados de rastreamento sejam usados ​​de forma eficaz e oportuna pelo lado empresarial, observe: que os dados podem ser continuamente enviados em estados simultâneos, com cada envio contendo o conjunto de dados completo. Se a recepção normal falhar e um código de status temporário não 200 for retornado, o 17TRACK fornece envios compensatórios, conforme detalhado aqui: como o envio funciona
   
   Se os resultados do rastreamento não puderem ser encontrados, pode ser devido aos seguintes cenários:
   • O rastreamento está em andamento. (Em circunstâncias normais, os resultados iniciais do rastreamento devem estar disponíveis em 1 minuto, com o rastreamento subsequente realizado de 3 a 4 vezes a cada 24 horas até a entrega.)
   • Número de rastreamento incorreto. Nesse caso, chame a Interface de Excluir Rastreamento (/deletetrack) e assine novamente.
   • Operadora incorreta. Nesse caso, chame a interface Alterar Operadora (/changecarrier) para atualizar a operadora.
   • Uma anormalidade na interface da operadora.
   • As operadoras não atualizaram os dados de rastreamento.
   • Parâmetros de rastreamento adicionais estão ausentes. Ao assinar, é necessário incluir parâmetros de rastreamento adicionais para determinadas operadoras, como números de celular e códigos postais.
   • As operadoras não atualizaram seus dados por 30 dias consecutivos. Nesse caso, o 17TRACK interromperá o rastreamento automaticamente.

3.2 Integração de sistemas de terceiros

Usuário-alvo

O guia de integração a seguir foi desenvolvido para provedores de logística de pequeno a médio porte e comerciantes de médio porte que utilizam sistemas ERP, TMS, WMS e CRM de terceiros

Etapa 1

(Se apenas para um teste rápido, você pode verificar o envio via https://webhook.site)

1. Confirme com o provedor do sistema se o sistema atual suporta o recebimento de dados de rastreamento de envio via método Webhook. [Diferente de sistemas autodesenvolvidos]
2. Confirme com o provedor do sistema se uma solução alternativa está disponível caso o envio não seja suportado: chame a interface gettrackinfo (/gettrackinfo) para recuperar os dados em intervalos regulares. (Observação: este método não pode garantir a mesma eficiência de retorno de dados que o método push e também não é recomendado pela 17TRACK.) [Diferente de sistemas autodesenvolvidos]
3. Confirme com o provedor do sistema se o acesso à API 17TRACK é suportado. Se suportado, confirme se a versão integrada atual atende às demandas comerciais. Caso contrário, negocie com o provedor do sistema para integrar outra versão. [Diferente de sistemas autodesenvolvidos]
4. Se o envio for suportado, conclua a lógica de verificação de assinatura na interface de recebimento de informações para garantir que a fonte de informações seja segura e válida. Consulte Verificar a assinatura, o código de exemplo é o seguinte:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

   String src = requestText + "/" + key;

   MessageDigest md = MessageDigest.getInstance("SHA-256");
   byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

   BigInteger number = new BigInteger(1, hash);
   StringBuilder hexString = new StringBuilder(number.toString(16));
   while (hexString.length() < 64) {
       hexString.insert(0, '0');
   }
   return hexString.toString();
}

Etapa 2

1. Obtenha a chave da API: faça login no console da API, obtenha a chave na página Configurações e forneça a chave ao provedor do sistema responsável pela integração. (Consulte Api-Settings)
2. Pule esta etapa se o provedor do sistema não suportar o método push. Se suportar, entre em contato com o provedor do sistema para fornecer a URL da interface push. (Consulte Api-Settings)

Etapa 3

1. Chame a interface de registro (/register) para assinar os números de rastreamento. É recomendado que o provedor do sistema passe o ID de dados no sistema empresarial por meio de uma tag para facilitar o uso futuro dos resultados de push. (Referência de interface: Registrar número de rastreamento)

Etapa 4

1. Faça login no sistema que você está usando e revise os resultados no Módulo de rastreamento. Se necessário, procure assistência e respostas do serviço de atendimento ao cliente do provedor do sistema.
2. Monitore a operação da interface de recebimento de informações. Para garantir que os resultados do rastreamento sejam oportunos e autorizados utilizados pelo lado empresarial, observe: que os dados podem ser continuamente compartilhados em estados simultâneos, com cada envio contendo o conjunto de dados completo. Nos casos em que a recepção normal falha e um código de status temporário não 200 é retornado, o 17TRACK fornece envios compensatórios, conforme detalhado aqui: como funciona o envio

Se os resultados do rastreamento não puderem ser encontrados, pode ser devido aos seguintes cenários:

• O rastreamento está em andamento. (Em circunstâncias normais, os resultados iniciais do rastreamento devem estar disponíveis em 1 minuto, com o rastreamento subsequente realizado de 3 a 4 vezes a cada 24 horas até a entrega.)
• Número de rastreamento incorreto. Nesse caso, chame a Interface de Excluir Rastreamento (/deletetrack) e assine novamente.
• Operadora incorreta. Nesse caso, chame a interface Alterar Operadora (/changecarrier) para atualizar a operadora.
• Uma anormalidade na interface da operadora.
• As operadoras não atualizaram os dados de rastreamento.
• Parâmetros de rastreamento adicionais estão ausentes. Ao assinar, é necessário incluir parâmetros de rastreamento adicionais para determinadas operadoras, como números de celular e códigos postais.
• As operadoras não atualizaram seus dados por 30 dias consecutivos. Nesse caso, o 17TRACK interromperá o rastreamento automaticamente.

4. Versões

Principais versões

Difference	V1.0	V2.0 (May 2022)
Request Address	https://api.17track.net/track/v1	https://api.17track.net/track/v2
Registration interface (/register) simplifies auto-recognition operations	{ carrier : null , auto_detection : true }	{ carrier : null }
Simplified signature verification	TRACKING_STOPPED/ {"number":"RM101474005CN", "carrier":3011,"tag":""} /6A8D7CFC3F7A41149E0A4EE8ABD0DD8A	{"event":"TRACKING_UPDATED", "data":{"number":"RR123456789CN", "carrier":3011,"tag":null}} /123456ABCDEF
Response structuring + node semantics	Not supported	Supported
Independent query additional parameters	Used in conjunction with a tracking number	Independent parameter
Origin and Destination	Not supported	Supported
Timeliness information	Not supported	Supported
Status	7 status	9 main status, 27 sub-status
Attachment Information	Not supported	Weight, volume, etc. (if supported by the carrier).
Carrier information	Not supported	Name, alias, official phone number, official website, etc.
Translation of events	Not supported	8 languages supported

Subversões

v2.1 (Atualizado em agosto de 2023):

1. Adicionados 3 subestados de liberação.
2. Adicionado nó de status de evento.
3. A interface de registro suporta parâmetros de número de pedido e nota.
4. Adicionado número de pedido, limite de tempo e outras informações à interface gettracklist.

v2.2 (Atualizado em outubro de 2023):

1. Incorpore a estrutura de informações brutas para o tempo do evento de logística.