1. Cos'è il monitoraggio logistico

Il monitoraggio logistico è uno strumento fondamentale per monitorare il processo di trasporto, consentendo agli utenti di tracciare percorsi di trasporto, eccezioni e importanti cambiamenti di stato.

Le principali funzionalità della Tracking API includono:

• Le principali funzionalità della Tracking API includono:
  Monitoraggio automatico: una volta registrato un numero di tracciamento, viene monitorato automaticamente con i risultati delle query che vengono inviati senza consumare quote aggiuntive. Nota: questa funzionalità funziona in modo asincrono e non è adatta per pagine Web front-end, mini programmi o app.
• Capacità a livello aziendale: la Tracking API offre funzionalità di elaborazione dati a livello aziendale, consentendo la registrazione di 400.000 numeri di tracciamento all'ora.
• Integrazione con i vettori globali: la Tracking API supporta l'integrazione con oltre 2000 vettori globali, fornendo metodi di chiamata unificati, strutture di risposta e nodi di stato, riducendo efficacemente i costi di sviluppo.
• Best practice per la gestione dei dati: è altamente consigliato archiviare le informazioni logistiche sul server o sul servizio di archiviazione.
• Identificazione univoca dei dati: ogni pezzo di dati viene identificato in modo univoco tramite la combinazione di numero di tracciamento + vettore.
• Panoramica del processo operativo: il processo operativo comprende Abbonamento alla spedizione > Monitoraggio periodico > Esame delle modifiche allo stato della spedizione > Invio dei risultati.

2. Prima dell'uso

2.1 Crea un account 17TRACK

Gli account API non sono specifici dell'ambiente. Si consiglia di mantenere account API separati per gli ambienti di test e di produzione per garantire configurazioni specifiche dell'ambiente e integrità dei dati. Visita 17TRACK-Api per aprire un account.

 

2.2 Numero di tracciamento e codice corriere

• Visita 17TRACK per verificare la disponibilità del numero di tracciamento preparato
• Visita Corrieri per controllare i corrieri supportati
• Cos'è un codice corriere? Il codice corriere è una specifica di parametro sviluppata specificamente per l'uso con la Tracking API. Puoi trovare maggiori informazioni su Codice corriere. Ad esempio, il codice corriere per USPS è 21051.

 

3. Guida all'integrazione

3.1 Integrazione di sistemi non di terze parti

Utente di destinazione

La seguente guida all'integrazione è specificatamente rivolta ai principali fornitori di servizi logistici, commercianti, fornitori di servizi e fornitori di sistemi che dispongono di sistemi proprietari e team di sviluppo IT.

Passaggio 1

(Per un test rapido, puoi verificare il push tramite https://webhook.site)

1. Assicurati che il tuo server sia accessibile dalla rete pubblica per ricevere aggiornamenti di tracciamento. Potrebbe essere necessario modificare le configurazioni del firewall e del gateway per consentire connessioni in entrata dai server di 17TRACK.
2. Sviluppa un'interfaccia in grado di ricevere informazioni di tracciamento e assicurati che possa gestire più richieste simultanee. Si consiglia di distribuire i dati utilizzando servizi indipendenti come code o cache per una migliore scalabilità.
3. Implementa la verifica della firma nella tua interfaccia di ricezione delle informazioni per confermare l'autenticità e l'integrità dei dati ricevuti da 17TRACK. Fai riferimento a Verifica la firma per le istruzioni. Di seguito è fornito un codice di esempio:

/**
* 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();
}

 

Passaggio 2

1. Ottieni la chiave API effettuando l'accesso e visitando la pagina delle impostazioni API su Api-Settings.
2. Per impostare l'interfaccia per la ricezione dei dati, accedi e vai alla pagina delle impostazioni API su Api-settings. Quindi inserisci l'URL dell'interfaccia nella sezione WebHook.

Fase 3

1. Chiamare l'interfaccia di registrazione (/register) per iscriversi ai numeri di tracciamento. Si consiglia di passare l'ID dati nel sistema aziendale tramite un tag per facilitare l'uso futuro dei risultati push. (Riferimento interfaccia: Registra numero di tracciamento)

Fase 4

1. Monitorare il funzionamento dell'interfaccia di ricezione delle informazioni. Per garantire che i risultati di tracciamento siano utilizzati in modo efficace e tempestivo dal lato aziendale, si prega di notare: che i dati possono essere spinti continuamente in stati simultanei, con ogni spinta contenente il set di dati completo. Se la ricezione normale fallisce e viene restituito un codice di stato temporaneo diverso da 200, 17TRACK fornisce spinte compensative, come dettagliato qui: come funziona la spinta
   
   Se non è possibile trovare i risultati del tracciamento, potrebbe essere dovuto ai seguenti scenari:
   • Il tracciamento è in corso. (In circostanze normali, i risultati del tracciamento iniziale dovrebbero essere disponibili entro 1 minuto, con il tracciamento successivo eseguito 3 o 4 volte ogni 24 ore fino alla consegna.)
   • Numero di tracciamento errato. In questo caso, chiama l'interfaccia Elimina tracciamento (/deletetrack) e quindi riabbonati.
   • Corriere errato. In questo caso, chiama l'interfaccia Cambia corriere (/changecarrier) per aggiornare il corriere.
   • Un'anomalia nell'interfaccia del corriere.
   • I corrieri non hanno aggiornato i dati di tracciamento.
   • Mancano parametri di tracciamento aggiuntivi. Quando ci si abbona, è necessario includere parametri di tracciamento aggiuntivi per determinati corrieri, come numeri di cellulare e codici postali.
   • I corrieri non hanno aggiornato i propri dati per 30 giorni consecutivi. In questo caso, 17TRACK interromperà automaticamente il tracciamento.

3.2 Integrazione di sistemi di terze parti

Utente di destinazione

La seguente guida all'integrazione è progettata per i fornitori di servizi logistici di piccole e medie dimensioni e per i commercianti di medie dimensioni che utilizzano sistemi ERP, TMS, WMS e CRM di terze parti

Passaggio 1

(Se solo per un test rapido, puoi verificare il push tramite https://webhook.site)

1. Conferma con il fornitore del sistema se il sistema attuale supporta la ricezione di dati di tracciamento push tramite il metodo Webhook. [Diverso dai sistemi auto-sviluppati]
2. Conferma con il fornitore del sistema se è disponibile una soluzione alternativa nel caso in cui il push non sia supportato: chiama l'interfaccia gettrackinfo (/gettrackinfo) per recuperare i dati a intervalli regolari. (Nota: questo metodo non può garantire la stessa efficienza di restituzione dei dati del metodo push e non è consigliato da 17TRACK.) [Diverso dai sistemi auto-sviluppati]
3. Conferma con il fornitore del sistema se è supportato l'accesso API 17TRACK. Se supportato, conferma se la versione integrata corrente soddisfa le esigenze aziendali. In caso contrario, negozia con il fornitore del sistema per integrare un'altra versione. [Diverso dai sistemi auto-sviluppati]
4. Se push è supportato, completare la logica di verifica della firma nell'interfaccia di ricezione delle informazioni per garantire che la fonte delle informazioni sia sicura e valida. Fare riferimento a Verifica la firma, il codice di esempio è il seguente:

/**
* 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();
}

Passaggio 2

1. Ottieni la chiave API: accedi alla console API, ottieni la chiave nella pagina Impostazioni e forniscila al provider di sistema responsabile dell'integrazione. (Vedi Impostazioni API)
2. Salta questo passaggio se il provider di sistema non supporta il metodo push. In caso contrario, contatta il provider di sistema per fornire l'URL dell'interfaccia push. (Vedi Impostazioni API)

Fase 3

1. Chiamare l'interfaccia di registrazione (/register) per iscriversi ai numeri di tracciamento. Si consiglia al provider di sistema di passare l'ID dati nel sistema aziendale tramite un tag per facilitare l'uso futuro dei risultati push. (Riferimento interfaccia: Registra numero di tracciamento)

Fase 4

1. Accedere al sistema in uso e rivedere i risultati nel modulo di tracciamento. Se necessario, cercare assistenza e risposte dal servizio clienti del provider di sistema.
2. Monitorare il funzionamento dell'interfaccia di ricezione delle informazioni. Per garantire che i risultati di tracciamento siano utilizzati tempestivamente ed efficacemente dal lato aziendale, notare che: i dati possono essere spinti continuamente in stati simultanei, con ogni spinta contenente il set di dati completo. Nei casi in cui la normale ricezione fallisce e viene restituito un codice di stato temporaneo diverso da 200, 17TRACK fornisce spinte compensative, come descritto qui: come funziona la spinta
   Se i risultati di tracciamento non possono essere trovati, potrebbe essere dovuto ai seguenti scenari:

Se non è possibile trovare i risultati del tracciamento, potrebbe essere dovuto ai seguenti scenari:

• Il tracciamento è in corso. (In circostanze normali, i risultati del tracciamento iniziale dovrebbero essere disponibili entro 1 minuto, con il tracciamento successivo eseguito 3 o 4 volte ogni 24 ore fino alla consegna.)
• Numero di tracciamento errato. In questo caso, chiama l'interfaccia Elimina tracciamento (/deletetrack) e quindi riabbonati.
• Corriere errato. In questo caso, chiama l'interfaccia Cambia corriere (/changecarrier) per aggiornare il corriere.
  Un'anomalia nell'interfaccia del corriere.
• I corrieri non hanno aggiornato i dati di tracciamento.
• Mancano parametri di tracciamento aggiuntivi. Quando ci si abbona, è necessario includere parametri di tracciamento aggiuntivi per determinati corrieri, come numeri di cellulare e codici postali.
• I corrieri non hanno aggiornato i propri dati per 30 giorni consecutivi. In questo caso, 17TRACK interromperà automaticamente il tracciamento.

4. Versioni

Versioni principali

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

Versioni secondarie

v2.1 (aggiornato ad agosto 2023):

1. Aggiunti 3 sottostati di autorizzazione.
2. Aggiunto nodo stato evento.
3. L'interfaccia di registrazione supporta i parametri numero ordine e nota.
4. Aggiunti numero ordine, limite di tempo e altre informazioni all'interfaccia gettracklist.

v2.2 (aggiornato ad ottobre 2023):

1. Incorpora la struttura delle informazioni non elaborate per la tempistica dell'evento logistico.