Skip to main content
CasaBlogGuideFlusso di lavoro dell’API di tracciamento delle spedizioni: dalla registrazione di una spedizione al recupero dei dettagli di tracciamento

Flusso di lavoro dell’API di tracciamento delle spedizioni: dalla registrazione di una spedizione al recupero dei dettagli di tracciamento

17TRACK

A workflow API per il monitoraggio delle spedizioni inizia inviando un numero di tracking e qualsiasi informazione sul corriere richiesta, verificando se la registrazione è riuscita, consentendo la disponibilità dei dati di tracking e recuperando lo stato e la cronologia degli eventi della spedizione. Per un'integrazione in produzione, gli sviluppatori devono inoltre collegare ogni record di tracking a un ordine, gestire gli errori parziali, elaborare gli aggiornamenti in modo sicuro e distinguere una registrazione accettata da una scansione effettiva del corriere.

Workflow dell’API di monitoraggio delle spedizioni dalla registrazione al recupero

Questa guida illustra questo workflow per gli sviluppatori che collegano una piattaforma ecommerce, un sistema di gestione degli ordini, un'applicazione di magazzino o uno strumento di assistenza clienti. Separa le raccomandazioni di progettazione dell'applicazione dai requisiti API specifici del provider. Per un'integrazione 17TRACK, utilizza la documentazione API ufficiale per confermare lo schema delle richieste, l'autenticazione, le operazioni supportate e i campi delle risposte prima di implementare gli esempi riportati di seguito.

Capire cosa fa e cosa non fa la registrazione

Registrare una spedizione presso un servizio di tracking significa inviare un identificativo affinché il servizio possa monitorare o gestire quella spedizione secondo il proprio contratto API. Non è la stessa operazione dell'acquisto dell'affrancatura, della generazione di un'etichetta di spedizione, della prenotazione di un ritiro o della consegna di un pacco a un corriere.

Tieni separati questi tre risultati nella tua applicazione:

  • Richiesta ricevuta: l'API ha restituito una risposta alla tua richiesta HTTP.
  • Registrazione accettata: il servizio ha accettato il singolo record di tracking per l'elaborazione.
  • Informazioni di tracking disponibili: il servizio dispone di informazioni sulla spedizione che la tua applicazione può recuperare o ricevere.

Questi risultati non devono essere ridotti a un unico flag di «successo». Un numero di tracking accettato potrebbe non avere ancora eventi del corriere. Allo stesso modo, una risposta HTTP riuscita per una richiesta batch non dimostra che ogni elemento del batch sia stato accettato; esamina la struttura del risultato a livello applicativo definita dal provider.

1. Prepara l'identità della spedizione e la configurazione API

Prima di effettuare una richiesta di registrazione, decidi come identificare una spedizione all'interno del tuo sistema. Di solito un solo identificativo dell'ordine non è sufficiente, perché un ordine può essere suddiviso in diversi pacchi. Assegna a ogni spedizione o pacco un proprio record interno e associa tale record all'ordine pertinente.

Un utile record interno comprende le seguenti informazioni. Si tratta di campi applicativi suggeriti, non di uno schema di richiesta 17TRACK.

  • ID interno della spedizione: il tuo identificativo stabile per il pacco.
  • Riferimento dell'ordine: l'ordine o il record di evasione a cui appartiene.
  • Numero di tracking: l'identificativo assegnato dal corriere, memorizzato come testo per preservare gli zeri iniziali.
  • Informazioni sul corriere: l'identità del corriere fornita dal tuo sistema di evasione, se nota.
  • Riferimento del provider: qualsiasi identificativo restituito dal servizio di tracking necessario per operazioni successive.
  • Stato della registrazione: il tuo record che indica se l'invio è in sospeso, accettato, rifiutato o in attesa di riconciliazione.
  • Stato del tracking: lo stato più recente della spedizione, mantenuto separatamente dallo stato della registrazione.

Convalida gli input prima dell'invio. Rimuovi gli spazi bianchi accidentali circostanti, ma non riscrivere il numero di tracking basandoti su supposizioni sul formato del corriere. Conserva il valore originale per la risoluzione dei problemi. Se il corriere è noto, mappalo sull'identificativo del corriere documentato dal provider invece di inviare un nome descrittivo informale.

Configura l'autenticazione sul lato server. Mantieni le credenziali fuori dal controllo del codice sorgente, separa la configurazione di sviluppo da quella di produzione e oscura i segreti nei log. Conferma la versione API documentata, i limiti delle richieste, i limiti dei batch e i requisiti dell'account invece di copiare valori da un'integrazione non correlata.

2. Registra la spedizione e memorizza il risultato a livello di elemento

Invia il record di tracking utilizzando l'operazione di registrazione descritta nella documentazione del provider. Includi solo i campi obbligatori e le informazioni facoltative che hanno uno scopo definito. Evita di inviare nomi dei clienti, indirizzi o altri dati personali solo perché sono disponibili nel database degli ordini.

Il seguente pseudocodice illustra la sequenza applicativa. I nomi delle funzioni sono esemplificativi; non sono endpoint API né metodi SDK.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Conserva informazioni sufficienti a spiegare cosa è successo: l'ID interno della spedizione, l'ora di invio, il numero del tentativo, il risultato a livello di elemento e qualsiasi riferimento alla richiesta del provider. Non affidarti esclusivamente a un log temporaneo del worker. I team di assistenza clienti e operations hanno bisogno di una risposta duratura sul fatto che una spedizione sia stata registrata correttamente.

Gestisci individualmente gli invii batch

Se l'API supporta la registrazione batch, associa ogni elemento restituito alla spedizione originale. Non contrassegnare l'intero batch come accettato perché la richiesta HTTP è stata completata correttamente. Salva gli elementi accettati, isola quelli rifiutati e analizza separatamente i risultati ambigui.

In questo modo eviti che un numero di tracking non valido provochi nuovi tentativi non necessari per i record già riusciti. Inoltre fornisci al personale operativo un elenco concreto dei record che richiedono una correzione.

Considera i timeout come un risultato sconosciuto

Un timeout non dimostra che la registrazione sia fallita. Il provider potrebbe aver accettato la richiesta prima che la connessione venisse interrotta. Utilizza il comportamento di idempotenza documentato, la gestione dei duplicati o le operazioni di ricerca per riconciliare il risultato prima di inviare nuovamente la richiesta alla cieca.

Quando il comportamento del provider nei confronti dei duplicati non è chiaro, testalo con record controllati e conferma il contratto prima di abilitare i tentativi automatici. Deduplicare internamente i job di registrazione è comunque utile, ma non sostituisce la comprensione di come il servizio remoto gestisca le richieste ripetute.

3. Attendi l'arrivo delle prime informazioni di tracking

Dopo l'accettazione della registrazione, i dettagli del tracking potrebbero non essere immediatamente disponibili. Un'etichetta può esistere prima che il corriere abbia registrato un evento di gestione fisica. La mancanza di informazioni può inoltre richiedere il controllo del numero di tracking, della selezione del corriere o dei requisiti di ricerca specifici della spedizione.

Rappresenta esplicitamente questa condizione. «Registrata; in attesa delle informazioni di tracking» è più accurato di «In transito» o «Registrazione fallita». Non inventare una stima di consegna o un evento di movimento per riempire un'interfaccia vuota.

Quando un record rimane vuoto, analizza la situazione in questo ordine pratico:

  1. Conferma che la singola registrazione sia stata accettata.
  2. Confronta il numero di tracking inviato con il record di evasione.
  3. Controlla la mappatura del corriere e gli eventuali requisiti aggiuntivi di ricerca documentati.
  4. Controlla la pagina di tracking del corriere per la stessa spedizione.
  5. Se il corriere dispone di eventi ma la tua integrazione no, esamina le risposte di recupero e contatta il provider API fornendo informazioni diagnostiche oscurate.

Evita di adottare un periodo di attesa universale senza prove. Le regole di escalation devono riflettere il servizio di spedizione, il processo di consegna previsto e i tuoi impegni operativi.

4. Recupera i dettagli del tracking e interpretali correttamente

Quando il record è disponibile, chiama l'operazione documentata per i dettagli del tracking utilizzando gli identificativi richiesti. Non dare per scontato che registrazione e recupero accettino campi identici. Alcuni contratti API distinguono tra numeri di tracking, identificativi dei corrieri e riferimenti ai record generati dal provider.

La tua applicazione dovrebbe distinguere tre livelli di informazioni:

  • Riepilogo della spedizione: lo stato complessivo utilizzato in dashboard, pagine degli ordini e filtri operativi.
  • Cronologia degli eventi: le singole osservazioni, comprese descrizioni degli eventi, timestamp e località quando fornite.
  • Metadati del recupero: quando la tua applicazione ha ricevuto o recuperato le informazioni e se la richiesta è stata completata correttamente.

Una ricerca riuscita significa che l'operazione di recupero è andata a buon fine. Non significa che il pacco si sia mosso dall'ultima ricerca. Confronta le informazioni di tracking restituite con il record memorizzato prima di generare una notifica o un workflow a valle.

Mantieni separati l'orario dell'evento e quello del recupero

Memorizza separatamente l'ora associata a un evento del corriere e l'ora in cui il sistema lo ha ricevuto. Un evento recuperato questo pomeriggio potrebbe descrivere una scansione precedente. Sostituire l'orario dell'evento con quello del recupero farebbe sembrare un aggiornamento vecchio un nuovo movimento fisico.

Conserva il timestamp originale e qualsiasi offset fornito. Normalizza i timestamp per il confronto solo quando il fuso orario è noto. Se un evento non contiene informazioni sul fuso orario, mantieni tale incertezza invece di assegnargli silenziosamente il fuso del server.

Conserva il significato originale insieme allo stato normalizzato

Uno stato normalizzato è utile per raggruppare le spedizioni tra diversi corrieri, ma la descrizione originale dell'evento può spiegare più precisamente un problema operativo. Conserva entrambi quando disponibili. Una sola categoria generica di eccezione potrebbe non indicare all'operatore dell'assistenza se l'azione successiva consiste nel controllare un indirizzo, contattare il destinatario o attendere un altro aggiornamento.

Non dedurre una garanzia di consegna, una perdita confermata o un particolare esito doganale da uno stato vago. Effettua l'escalation in base alle informazioni sottostanti e alla tua politica operativa.

5. Mantieni aggiornati i record tramite polling o webhook

Recuperare i dettagli una sola volta è sufficiente per testare la connettività, ma non per mantenere la visibilità sulla spedizione. La progettazione in produzione richiede un meccanismo di aggiornamento. Conferma i meccanismi supportati dal provider scelto e le condizioni a essi associate.

Con il polling, la tua applicazione richiede i dettagli del tracking secondo una pianificazione. Pianifica le richieste entro i limiti documentati, evita di interrogare ripetutamente record invariati senza motivo e utilizza il backoff per gli errori ritentabili. L'apertura della pagina di un ordine da parte di un cliente non dovrebbe attivare automaticamente una richiesta upstream senza limiti; una vista di tracking memorizzata può servire la pagina mentre un processo in background controllato la aggiorna.

Se utilizzi i webhook, convalida le richieste in entrata tramite il meccanismo di verifica documentato dal provider. Rendi persistenti o accoda in modo durevole i messaggi accettati prima di confermarli secondo il contratto del webhook, quindi elabora gli eventi in modo asincrono.

Progetta il ricevitore affinché tolleri duplicati e un ordine di arrivo imprevisto, salvo che il contratto di consegna documentato garantisca diversamente. Quando disponibile, utilizza un identificativo dell'evento del provider per la deduplicazione. Altrimenti definisci e testa un'impronta basata su campi evento appropriati, riconoscendo che tale impronta potrebbe richiedere modifiche per i tuoi dati.

Un'integrazione basata sui webhook può inoltre utilizzare un recupero controllato per la riconciliazione. Per esempio, un job di ripristino può controllare i record interessati da un'interruzione del ricevitore. Questo è un modello di resilienza, non un'autorizzazione a ignorare i limiti di frequenza o le indicazioni specifiche del provider.

6. Trasforma le informazioni di tracking in azioni aziendali sicure

Aggiorna il record interno della spedizione prima di attivare azioni rivolte ai clienti. Conserva un record duraturo delle notifiche e delle transizioni del workflow, in modo che un evento ripetuto non generi messaggi ripetuti.

Mappa le azioni aziendali su cambiamenti significativi, non su ogni risposta API. Un evento di consegna osservato per la prima volta può giustificare una notifica di consegna. Una risposta ripetuta contenente lo stesso evento non dovrebbe farlo. Un'eccezione può giustificare una revisione interna, ma il messaggio al cliente deve riflettere ciò che l'evento comunica realmente.

Definisci come gestire gli eventi ricevuti dopo che una spedizione è stata considerata completata. Non eliminare la cronologia degli eventi né bloccare permanentemente tutti gli aggiornamenti successivi solo perché un riepilogo ha raggiunto uno stato terminale. Le regole di conservazione, riconciliazione e notifica devono tenere conto delle correzioni legittime senza riaprire ripetutamente i workflow completati.

Applicazione del workflow a un'integrazione 17TRACK

Per un'integrazione di tracking personalizzata, i punti di partenza pertinenti sono la pagina API di tracking 17TRACK e la relativa documentazione per sviluppatori. Utilizza la pagina del prodotto per valutare l'offerta e la documentazione per stabilire il contratto effettivo dell'integrazione. Le pagine di tracking per i consumatori non sostituiscono le specifiche API.

Prima di scrivere il tuo adapter, conferma il formato di autenticazione, le operazioni di registrazione e recupero, le regole di identificazione dei corrieri, la gestione delle risposte a livello di elemento e i limiti applicabili alle richieste. Per l'elaborazione basata sui webhook, conferma inoltre lo schema del payload, il processo di verifica, i requisiti di conferma e il comportamento dei tentativi.

Mantieni questi dettagli specifici del provider all'interno di un adapter invece di distribuire le supposizioni sui campi delle risposte in tutto il sistema degli ordini. Il resto dell'applicazione potrà così lavorare con concetti interni quali esito della registrazione, stato della spedizione, cronologia degli eventi e ultima sincronizzazione riuscita.

Controlli pre-lancio che evitano errori costosi

  • Record accettato ma vuoto: l'interfaccia mostra che le informazioni di tracking sono in attesa, non che il pacco sia in movimento.
  • Risultato batch misto: ogni spedizione riceve un proprio esito persistito.
  • Timeout dopo l'invio: il worker riconcilia il risultato incerto invece di presumere un errore.
  • Evento ripetuto: la cronologia della spedizione e la notifica al cliente restano deduplicate.
  • Evento precedente ricevuto in ritardo: l'evento viene conservato senza sostituire alla cieca un riepilogo più recente.
  • Servizio upstream non disponibile: la pagina del cliente può mostrare l'ultimo risultato memorizzato con un'indicazione appropriata della freschezza.
  • Mappatura errata del corriere: il record può essere corretto tramite un percorso di ripristino documentato.
  • Ordine suddiviso: ogni pacco conserva il proprio stato di tracking e la propria cronologia degli eventi.
  • Esposizione di credenziali o payload: i log contengono riferimenti diagnostici senza divulgare segreti o informazioni personali non necessarie.

Il criterio pratico di completamento non consiste semplicemente nel ricevere una risposta di registrazione riuscita. Consiste nel poter tracciare un pacco dall'invio agli aggiornamenti, spiegare un risultato vuoto o fallito e ripristinare un'elaborazione interrotta senza perdere eventi né duplicare le azioni rivolte ai clienti.

FAQ

La registrazione di un numero di tracking crea una spedizione?

Non nel workflow descritto qui. La registrazione del tracking invia un identificativo esistente a un servizio di tracking. La creazione dell'etichetta, l'acquisto dell'affrancatura e la prenotazione del corriere sono operazioni separate, salvo che una determinata API le combini esplicitamente.

Perché i dettagli del tracking sono vuoti dopo che la registrazione è riuscita?

L'accettazione della registrazione e la disponibilità dei dati di tracking sono condizioni diverse. Il corriere potrebbe non aver ancora registrato un evento oppure potrebbe essere necessario verificare il numero di tracking, la mappatura del corriere o ulteriori informazioni di ricerca. Esamina il risultato a livello di elemento prima di considerare il record registrato correttamente.

Devo registrare la spedizione ogni volta che recupero il suo stato?

Non utilizzare la registrazione ripetuta come meccanismo di aggiornamento predefinito. Memorizza lo stato della registrazione accettata e utilizza il meccanismo documentato di recupero o aggiornamento. Segui le regole esplicite del provider per correzioni, riattivazioni o invii duplicati.

Devo usare il polling o i webhook?

Utilizza il meccanismo più adatto al contratto API documentato e ai tuoi requisiti operativi. Il polling richiede una pianificazione controllata delle richieste. I webhook richiedono un ricevitore sicuro e duraturo e un'elaborazione sicura rispetto ai duplicati. Quando supportati, gli aggiornamenti tramite webhook con una riconciliazione mirata possono offrire un percorso pratico di ripristino.

Posso usare un numero di tracking come unico identificativo della spedizione nel database?

Utilizza invece un identificativo interno della spedizione. Memorizza il numero di tracking e il contesto del corriere pertinente come attributi di quel record. Questo facilita la gestione degli ordini suddivisi, dei numeri di tracking corretti e dei riferimenti specifici del provider senza modificare l'identità della tua spedizione interna.

Fonti

  • 17TRACK Tracking API — punto di accesso ufficiale al prodotto per valutare un'integrazione API 17TRACK.
  • Documentazione API 17TRACK — riferimento ufficiale per i formati delle richieste, le operazioni, le risposte e i requisiti di integrazione specifici dell'implementazione. Lo pseudocodice e i suggerimenti sui campi interni presenti in questa guida sono esempi di progettazione applicativa, non citazioni del contratto API.