Skip to main content
CasaBlogGuideCome ottenere lo stato più recente della spedizione tramite API senza attendere un webhook

Come ottenere lo stato più recente della spedizione tramite API senza attendere un webhook

17TRACK

Per ottenere l'ultimo stato di spedizione disponibile senza attendere un webhook, invia una richiesta autenticata all'API di interrogazione delle spedizioni del tuo provider di tracking. Usa la risposta per aggiornare immediatamente la tua applicazione, quindi mantieni attivi i webhook per le modifiche successive. La distinzione importante è che una query di solito recupera le informazioni di tracking più recenti memorizzate dal provider; non attiva necessariamente un nuovo controllo presso il corriere.

Come ottenere l’ultimo stato della spedizione tramite API senza

Questo approccio è utile quando un cliente apre la pagina di un ordine, quando un operatore dell'assistenza necessita di un aggiornamento o quando il sistema deve recuperare una notifica persa. Un'implementazione affidabile combina query su richiesta, indicatori chiari di aggiornamento e protezioni contro aggiornamenti duplicati o fuori ordine.

Decidi cosa significa “ultimo stato della spedizione”

Prima di scegliere un endpoint, distingui tra tre operazioni che possono sembrare simili ma producono risultati diversi.

OperazioneCosa faCosa non stabilisce
Leggere il proprio databaseRestituisce le informazioni di tracking già in possesso dell'applicazione.Se il provider ha ricevuto un aggiornamento più recente.
Interrogare l'API di trackingRecupera le informazioni disponibili tramite l'operazione di query del provider.Se durante quella richiesta è stata effettuata una nuova ricerca presso il corriere.
Richiedere un aggiornamento del trackingRichiede un nuovo controllo a monte, se il provider offre questa operazione.Che il corriere disponga di una nuova scansione o che l'aggiornamento venga completato in modo sincrono.

Usa una query quando ti serve una risposta immediata. Esamina un'operazione di aggiornamento solo quando hai bisogno che il provider tenti un altro controllo a monte. Non presumere che l'aggiunta di un parametro per evitare la cache, la ripetizione di una richiesta o l'invio di un'intestazione HTTP cache-control costringano il corriere a fornire nuove informazioni.

La visibilità della spedizione attraversa diverse fasi: il corriere registra un evento, il provider di tracking lo acquisisce e la tua applicazione lo riceve o lo recupera. Una richiesta API diretta può evitare di attendere la consegna di una notifica, ma non può eliminare i ritardi che si verificano prima nella catena.

Verifica il contratto della query prima di scrivere il codice

Lo sviluppatore che integra il servizio di tracking è responsabile di questo flusso di lavoro. Inizia dalla documentazione aggiornata del provider, non da un endpoint copiato da un vecchio esempio di integrazione. Conferma questi dettagli:

  • Identità della spedizione: la query accetta un numero di tracking, un ID interno della spedizione o un numero di tracking combinato con un identificativo del corriere?
  • Requisiti di registrazione: la spedizione deve essere registrata prima di poter essere interrogata?
  • Autenticazione: quale intestazione o meccanismo di autenticazione è richiesto?
  • Significato della risposta: l'operazione restituisce informazioni memorizzate, avvia la raccolta dei dati o restituisce un job da controllare in seguito?
  • Gestione del risultato: una risposta HTTP corretta può contenere un errore a livello di spedizione o un risultato in sospeso?
  • Vincoli di utilizzo: quali limiti di frequenza, limiti per i batch e restrizioni specifiche dell'account si applicano?
  • Campi relativi all'aggiornamento: quali timestamp rappresentano gli eventi del corriere, gli aggiornamenti del provider e la generazione della risposta?

Per un'integrazione con 17TRACK, la Tracking API è il prodotto pertinente, non una pagina di tracking per consumatori o un'interfaccia di tracking del negozio. Usa la documentazione API ufficiale per confermare l'operazione di query delle informazioni di tracking, l'autenticazione, i campi della richiesta e la struttura della risposta per la tua integrazione. Considera la gestione delle query e dei webhook come percorsi applicativi separati che aggiornano lo stesso record della spedizione.

Evita di codificare rigide supposizioni sul comportamento degli aggiornamenti o sulla frequenza delle query. Questi dettagli devono corrispondere all'operazione e ai termini del servizio che utilizzi effettivamente.

Crea una ricerca su richiesta tramite il backend

Un design pratico consiste nell'esporre un endpoint autenticato nella propria applicazione. Il browser richiede un aggiornamento della spedizione a tale endpoint; il server verifica l'autorizzazione, decide se è necessaria una query al provider e restituisce un risultato normalizzato.

Il percorso seguente è un esempio di endpoint che creeresti nella tua applicazione. Non è un endpoint 17TRACK né una specifica di richiesta del provider.

GET /api/orders/{order_id}/shipment-status

Usa l'identificativo dell'ordine per individuare la spedizione sul server. Non consentire a un chiamante di recuperare la cronologia di tracking di un altro cliente semplicemente sostituendo un numero di tracking nella richiesta. Mantieni la credenziale API del provider nel backend, non nel JavaScript del browser o nel bundle di un'applicazione mobile.

Un flusso di richiesta che puoi implementare

  1. Autorizza l'accesso. Verifica che il cliente o il membro del personale possa visualizzare l'ordine.
  2. Risolvi la spedizione. Leggi l'identificativo di tracking memorizzato e le informazioni sul corriere, se applicabile.
  3. Controlla l'aggiornamento locale. Se esiste già una query recente completata con successo, riutilizzala secondo la politica di aggiornamento della tua applicazione.
  4. Interroga il provider quando necessario. Usa l'operazione documentata e un timeout della richiesta limitato.
  5. Convalida il risultato. Controlla sia l'esito HTTP sia il risultato a livello di spedizione.
  6. Unisci le informazioni. Applica le stesse regole di normalizzazione e riconciliazione usate per gli eventi webhook.
  7. Restituisci lo stato e l'aggiornamento. Includi l'ora dell'evento più recente e, quando disponibile, l'ora dell'ultimo controllo riuscito presso il provider.

La politica di aggiornamento locale è una decisione ingegneristica, non un'affermazione sulla frequenza degli aggiornamenti del corriere. Sceglila in base ai requisiti dell'interfaccia, ai limiti del provider, al volume delle spedizioni e all'utilità osservata delle query. Un cliente che fa clic ripetutamente su un pulsante di aggiornamento non dovrebbe creare un flusso illimitato di richieste a monte.

Normalizza la risposta senza inventare l'aggiornamento

La tua applicazione può restituire un formato interno stabile anche quando le strutture delle risposte del provider differiscono. Questo oggetto illustrativo è il contratto della tua applicazione, non un payload reale del provider:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Compila ogni timestamp solo quando il suo significato è noto. L'ora in cui il server ha ricevuto una risposta appartiene ai metadati della query; non deve essere presentata come l'ora in cui il pacco si è spostato. Se il provider non fornisce un timestamp di aggiornamento, lascia quel campo assente o nullo invece di sostituirlo con un altro timestamp.

Per l'interfaccia del cliente, separa i messaggi: “Ultimo evento del corriere” descrive l'attività della spedizione, mentre “Tracking verificato” descrive l'attività di recupero della tua applicazione. Questa distinzione impedisce che una scansione invariata sembri appena registrata.

Impedisci alle query API e ai webhook di sovrascriversi a vicenda

Quando entrambi i meccanismi sono attivi, lo stesso evento può arrivare tramite una query e un webhook. Inoltre, possono terminare in un ordine diverso da quello di avvio. Una query avviata per prima può completarsi dopo che un webhook ha già fornito informazioni più recenti.

Non usare una logica in cui vince l'ultima risposta. Il payload ricevuto più recentemente non rappresenta necessariamente lo stato più recente della spedizione.

  • Condividi un'unica pipeline di aggiornamento. Invia i risultati delle query e i payload dei webhook attraverso le stesse funzioni di convalida, normalizzazione e persistenza.
  • Deduplica gli eventi. Preferisci un identificativo dell'evento documentato. Se non esiste, crea un'impronta definita con attenzione a partire dai campi disponibili, come ora dell'evento, stato, posizione e descrizione.
  • Usa campi di ordinamento con semantica nota. Una revisione o una sequenza documentata è più utile che presumere che l'ora di arrivo rappresenti l'ordine degli eventi.
  • Conserva la cronologia. Un evento appena ricevuto può colmare una lacuna storica senza modificare il riepilogo corrente della spedizione.
  • Consenti le correzioni. Gli stati non formano una scala lineare universale. Segui il comportamento di correzione documentato invece di rifiutare permanentemente ogni apparente transizione all'indietro.

Quando l'ordine degli eventi è incerto, conserva il payload originale e la relativa provenienza per le verifiche. Non risolvere l'ambiguità inventando un timestamp dell'evento o presumendo che tutti i timestamp dei corrieri condividano lo stesso fuso orario.

Gestisci diversamente i dati mancanti e le richieste non riuscite

Un risultato vuoto, un risultato invariato e una richiesta non riuscita non dovrebbero generare lo stesso messaggio per il cliente.

La query riesce ma lo stato non è cambiato

Mantieni lo stato esistente della spedizione e aggiorna l'ora dell'ultima query riuscita. Non generare un nuovo evento di spedizione solo perché è stata completata un'altra ricerca. Se il cliente necessita di maggiori dettagli, mostra la cronologia degli eventi esistente e spiega che non è stato restituito alcun evento di tracking più recente.

La spedizione non contiene ancora informazioni di tracking

Verifica se è necessaria la registrazione, se l'identificativo e il corriere sono corretti e come il provider rappresenta la raccolta in sospeso. L'assenza di eventi non dimostra di per sé che il numero di tracking sia invalido o che il pacco sia perso. Mantieni la distinzione del provider tra identificativo sconosciuto, spedizione registrata in attesa di informazioni e richiesta che non ha potuto essere elaborata.

La richiesta al provider va in timeout o non riesce

Se disponi di uno stato valido precedente, restituiscilo indicando esplicitamente che l'ultimo controllo non è riuscito. Mantieni invariato il timestamp della query riuscita precedente. Un errore di rete non è un'eccezione di consegna e non dovrebbe modificare lo stato commerciale del pacco.

Usa tentativi ripetuti limitati con backoff e jitter per i guasti transitori appropriati. Non ripetere continuamente le credenziali non valide o le richieste malformate. Quando una risposta fornisce Retry-After, interpretala secondo il contratto del provider e la semantica HTTP. La specifica HTTP consente che tale valore sia espresso come ritardo in secondi o come data HTTP.

Arrivano più richieste per la stessa spedizione

Raggruppa le ricerche simultanee in modo che possano condividere un'unica richiesta a monte. Applica limiti per account e spedizione e impedisci che un tentativo automatico si moltiplichi attraverso diversi livelli dell'applicazione. Quando è supportata l'elaborazione in batch, esamina il risultato di ogni spedizione invece di considerare l'intero batch riuscito solo perché la richiesta HTTP è stata completata.

Usa il polling come fallback controllato

Senza webhook, il polling programmato può mantenere aggiornato il database, ma richiede una politica operativa esplicita. Decidi quali spedizioni restano idonee, come i guasti influiscono sulla pianificazione e quando interrompere il polling ordinario.

Per la maggior parte delle integrazioni, un design ibrido è un punto di partenza sensato: i webhook gestiscono le modifiche in background, le query su richiesta servono le richieste interattive e i job di riconciliazione controllano i record che richiedono attenzione. Si tratta di una raccomandazione architetturale, non di una garanzia che riduca i costi per ogni account.

  • Dai priorità alle spedizioni attive e ai record con errori di recupero non risolti.
  • Evita di interrogare ogni spedizione storica a ogni esecuzione programmata.
  • Definisci come gestire le spedizioni completate, compresa l'eventuale finestra di correzione richiesta dalla tua attività.
  • Monitora la frequenza con cui le query trovano informazioni realmente nuove.
  • Esamina i problemi di consegna dei webhook invece di nasconderli con polling sempre più frequente.

Monitora la latenza delle richieste al provider, le query non riuscite, le risposte relative ai limiti di frequenza e le differenze tra i dati interrogati e i record alimentati dai webhook. Monitora separatamente l'età dell'ultimo evento del corriere. Risposte API riuscite possono coesistere con informazioni di tracking che non sono cambiate.

Testa il flusso di lavoro prima del rilascio

Una richiesta riuscita è solo il primo test. Verifica le situazioni che altrimenti potrebbero creare aggiornamenti di stato fuorvianti:

  • Arriva un webhook mentre è ancora in esecuzione una query su richiesta.
  • Due clienti o sessioni del personale richiedono contemporaneamente la stessa spedizione.
  • Il provider restituisce un esito HTTP positivo ma segnala un errore a livello di spedizione.
  • Una richiesta non riesce dopo che l'applicazione ha già ricevuto informazioni di tracking valide.
  • Un evento non contiene un fuso orario o include un codice di stato sconosciuto.
  • Una correzione del corriere modifica un risultato visualizzato in precedenza.
  • Un utente tenta di accedere a una spedizione appartenente a un altro account.

Il criterio di rilascio dovrebbe essere che l'applicazione restituisca le migliori informazioni conosciute sulla spedizione, ne spieghi accuratamente l'aggiornamento e non le corrompa quando le richieste non riescono o arrivano fuori ordine.

Domande frequenti

Interrogare l'API obbliga il corriere a scansionare o aggiornare un pacco?

No. Recuperare le informazioni di tracking non può causare una scansione fisica. Se una richiesta attiva una ricerca a monte dipende dall'operazione documentata. Anche un aggiornamento supportato può restituire informazioni invariate se il corriere non dispone di un evento più recente.

Posso usare le query API senza configurare i webhook?

Se il provider supporta il flusso di query richiesto, puoi creare un'integrazione basata su richieste su domanda o polling. Conferma prima i requisiti di registrazione e di query. La tua applicazione sarà quindi responsabile di decidere quando controllare, controllare il volume delle richieste e rilevare le modifiche.

Con quale frequenza dovrei eseguire il polling dello stato della spedizione?

Non esiste un intervallo universale. Scegli una pianificazione adatta ai limiti del provider, al volume delle spedizioni e al valore commerciale di trovare prima gli aggiornamenti. Misura la frequenza con cui il polling restituisce nuovi eventi, quindi modifica la pianificazione invece di presumere che richieste frequenti producano dati del corriere più aggiornati.

Perché l'API restituisce informazioni che avevo già ricevuto tramite webhook?

Entrambi i percorsi possono esporre lo stesso record sottostante della spedizione. Un webhook consegna una notifica, mentre una query recupera le informazioni su richiesta. Ricevere lo stesso evento tramite entrambi non è necessariamente un errore; la tua applicazione dovrebbe deduplicarlo.

Il pulsante di aggiornamento dovrebbe dire “Aggiorna tracking”?

Solo se questa formulazione descrive accuratamente l'operazione. Se il pulsante recupera dati del provider già memorizzati, “Controlla aggiornamenti” è più chiaro. Mostra separatamente l'ultimo evento del corriere e l'ora in cui l'applicazione ha completato l'ultimo controllo riuscito.

Fonti