Come registrare un numero di tracciamento tramite API: campi della richiesta, codici dei corrieri e risposte
Per registrare un numero di tracciamento tramite API, invia una richiesta di registrazione autenticata contenente il numero di tracciamento della spedizione e, quando richiesto, un identificativo del corriere. Quindi esamina la risposta per ogni spedizione inviata, non solo lo stato HTTP, e salva se la registrazione è riuscita, fallita o rimane incerta. La registrazione avvia il flusso di tracciamento; non dimostra che il corriere abbia scansionato il pacco o che gli eventi di tracciamento siano già disponibili.
Questa guida è destinata agli sviluppatori che collegano un sistema di gestione degli ordini, un'applicazione di magazzino o una piattaforma ecommerce a un'API di tracciamento. Utilizza 17TRACK come esempio concreto di integrazione e spiega quali dettagli devono essere verificati nella documentazione relativa alla versione dell'API selezionata.
Cosa fa la registrazione e cosa non fa
Una richiesta di registrazione comunica a un servizio di tracciamento quale spedizione desideri monitorare. È diversa dall'acquisto di un'etichetta di spedizione, dalla prenotazione di un ritiro o dalla richiesta a un corriere di creare una spedizione. In un'integrazione tipica, il flusso di spedizione produce prima un numero di tracciamento e la tua applicazione registra poi quel numero.
Mantieni separati questi tre eventi nella tua applicazione:
- Spedizione creata: il sistema di spedizione ha assegnato un numero di tracciamento.
- Registrazione accettata: il servizio di tracciamento ha accettato la spedizione per il monitoraggio.
- Informazioni di tracciamento ricevute: gli eventi del corriere sono diventati disponibili tramite il servizio di tracciamento.
Non aggiornare un ordine allo stato “in transito” semplicemente perché la registrazione è riuscita. Un'etichetta appena creata potrebbe non avere ancora una scansione fisica di accettazione. Lo stato della spedizione mostrato al cliente dovrebbe derivare dagli eventi di tracciamento interpretati secondo le tue regole di mappatura degli stati, non dalla risposta di registrazione.
Per le integrazioni 17TRACK, inizia dalla panoramica dell'API di tracciamento e utilizza la documentazione ufficiale dell'API come riferimento autorevole per endpoint, definizioni dei campi, autenticazione e codici di risposta. Gli esempi seguenti si concentrano sulla registrazione, non sulle attività separate di recupero dei risultati o ricezione degli aggiornamenti.
Prepara i campi della richiesta prima di scrivere la chiamata API
La preparazione più utile consiste in un piccolo contratto sui campi tra il sistema di spedizione e l'integrazione di tracciamento. Decidi da dove proviene ogni valore, se può essere mancante e come verrà convalidato.
| Campo o valore | Scopo | Regola di implementazione |
|---|---|---|
| Numero di tracciamento | Identifica la spedizione da monitorare. | Salvalo e trasmettilo come stringa; conserva gli zeri iniziali. |
| Identificativo del corriere | Identifica il corriere nel sistema del provider di tracciamento. | Utilizza l'identificativo documentato dal provider, non un codice interno di magazzino. |
| Riferimento interno | Collega la registrazione al record della spedizione. | Utilizza un campo di riferimento supportato, se disponibile; conserva comunque la tua mappatura nel database. |
| Dati identificativi aggiuntivi | Possono aiutare a identificare una spedizione quando un corriere richiede più del solo numero di tracciamento. | Invia solo i campi documentati per quella integrazione e quel corriere. |
| Credenziale API | Autentica l'account chiamante. | Conservala sul server ed escludila dai log dell'applicazione. |
Tratta il numero di tracciamento come un identificativo
Non convertire mai un numero di tracciamento in un intero. La conversione numerica può rimuovere gli zeri iniziali e, in alcuni ambienti di programmazione, i valori elevati possono perdere precisione. Rimuovi gli spazi bianchi accidentali all'inizio e alla fine, ma non eliminare la punteggiatura né modificare maiuscole e minuscole, salvo che la documentazione pertinente o il formato del corriere supportino tale normalizzazione.
Convalida gli errori di input più evidenti prima di chiamare l'API: stringhe vuote, interruzioni di riga impreviste e un numero d'ordine copiato nel campo del numero di tracciamento. Evita di imporre una lunghezza o una regola sui caratteri universale per tutti i corrieri. Una regola adatta a un corriere potrebbe rifiutare numeri validi di un altro.
Mantieni separati i riferimenti dell'ordine dalle identità delle spedizioni
Un ordine può contenere più pacchi e una spedizione sostitutiva può introdurre un altro numero di tracciamento. Modella la registrazione a livello di spedizione o pacco invece di presumere un solo numero di tracciamento per ordine.
Se utilizzi un tag o un campo di riferimento supportato dal provider, preferisci un riferimento opaco della spedizione anziché l'indirizzo email o l'indirizzo postale del cliente. Il tuo database deve rimanere il collegamento autorevole tra ordini, spedizioni, numeri di tracciamento e mappature dei corrieri.
Scegli il codice del corriere corretto
Un codice corriere non è necessariamente un identificativo universale del settore. Il valore riconosciuto da una piattaforma di tracciamento può differire dal nome del corriere memorizzato nel software di spedizione. Anche due sistemi che utilizzano codici numerici possono assegnare numeri diversi allo stesso corriere.
Mantieni una mappatura esplicita dal tuo servizio di spedizione all'identificativo del corriere del provider di tracciamento. Se necessario, distingui l'operatività regionale o il servizio di un corriere dal suo marchio più ampio. Una mappatura basata solo su un nome visualizzato può diventare ambigua quando i sistemi di spedizione utilizzano alias.
- Quando il corriere è noto: utilizza l'identificativo documentato del corriere quando supportato, soprattutto nei casi in cui i formati dei numeri di tracciamento si sovrappongono.
- Quando il corriere è sconosciuto: utilizza il rilevamento automatico solo tramite il meccanismo documentato. Non presumere che omissione, stringa vuota, zero e null abbiano lo stesso significato.
- Quando il risultato sembra errato: verifica l'etichetta originale, il servizio di spedizione e la mappatura prima di registrare ripetutamente lo stesso numero.
Il rilevamento automatico è utile, ma non dimostra che un determinato corriere detenga fisicamente la spedizione. Analogamente, un codice corriere valido non garantisce che il numero di tracciamento fornito appartenga a quel corriere.
Mantieni configurabili le mappature dei corrieri invece di distribuirle nel codice dell'applicazione. Registra quando una mappatura è stata verificata l'ultima volta e includi una spedizione nota nei test di regressione ogni volta che la modifichi.
Esempio: inviare una richiesta di registrazione 17TRACK
L'esempio seguente illustra l'endpoint di registrazione 17TRACK v2.2, l'header di autenticazione 17token e un array contenente un oggetto con un numero di tracciamento. Prima della distribuzione, verifica che questa versione e i relativi requisiti della richiesta corrispondano al tuo account e alla documentazione ufficiale. Il numero di tracciamento è un segnaposto e deve essere sostituito con un identificativo reale della spedizione.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Questo esempio minimale non illustra la selezione del corriere né i campi supplementari specifici del corriere. Consulta la documentazione sulla registrazione per determinare come funziona il rilevamento del corriere quando il campo del corriere viene omesso e se la tua spedizione richiede informazioni aggiuntive. Se fornisci un corriere, utilizza il campo carrier documentato e l'identificativo previsto da quella versione dell'API.
Esegui questa richiesta da un ambiente lato server. Non incorporare il token in un negozio pubblico, in uno script del browser o in un'applicazione mobile distribuita ai clienti. Una variabile d'ambiente è comoda per un esempio locale; le distribuzioni di produzione devono utilizzare i controlli di gestione dei segreti dell'organizzazione.
Prima di aumentare il volume, testa una spedizione nota ed esamina la risposta completa. Poi testa un input non valido e un batch contenente elementi validi e non validi. Questi controlli rivelano se l'integrazione gestisce effettivamente gli esiti a livello di elemento invece di limitarsi a riconoscere una risposta HTTP positiva.
Leggi la risposta a tre livelli
Un gestore delle risposte affidabile risponde a tre domande separate: la richiesta ha raggiunto il servizio? Il servizio ha accettato l'operazione? Cosa è successo a ogni spedizione?
1. Esito HTTP e del trasporto
Un timeout della connessione, un errore TLS o una risposta interrotta non indicano necessariamente se il server ha elaborato la richiesta. Contrassegna l'esito come incerto finché non puoi riconciliarlo. Uno stato HTTP positivo conferma uno scambio HTTP riuscito, ma devi comunque esaminare la risposta dell'applicazione.
2. Esito a livello di richiesta
Esamina il risultato principale e i campi di errore documentati dall'API. Gli errori di autenticazione, il JSON non valido e le limitazioni dell'account richiedono azioni diverse. Memorizza il codice e il messaggio di errore originali del provider invece di ridurre ogni errore a “tracciamento non disponibile”.
Non presumere che un codice numerico dell'applicazione abbia lo stesso significato di un codice di stato HTTP. I loro significati provengono da livelli diversi e devono essere interpretati separatamente.
3. Esito a livello di spedizione
Per la registrazione in batch, considera ogni elemento inviato. Una risposta può distinguere le spedizioni accettate da quelle rifiutate; il parser deve seguire lo schema esatto documentato per la versione selezionata. Non contrassegnare un intero batch come registrato solo perché un elemento è riuscito.
Normalizza le risposte del provider nei tuoi stati applicativi stabili. Ad esempio, il database potrebbe utilizzare accepted, rejected e uncertain. Si tratta di stati interni suggeriti, non di valori letterali della risposta 17TRACK. Conserva la risposta originale del provider secondo un'adeguata politica di conservazione e accesso, affinché gli sviluppatori possano analizzare le discrepanze.
Un record di registrazione utile contiene l'ID interno della spedizione, il numero inviato, la selezione del corriere, l'ora del tentativo, la versione dell'API, l'esito e i dettagli dell'errore del provider. Mantieni separato lo stato della registrazione dallo stato della consegna.
Gestisci i tentativi senza creare un ciclo infinito
La politica dei tentativi dovrebbe dipendere dal tipo di errore, non semplicemente dal verificarsi di un'eccezione.
- Input non valido: correggi il campo prima di riprovare. Ripetere una richiesta non valida e invariata è improbabile che sia utile.
- Errore di autenticazione: verifica le credenziali e la configurazione dell'account. Evita di inviare ripetutamente lo stesso batch che fallisce.
- Limitazione della frequenza: segui i limiti documentati e le eventuali istruzioni applicabili sui tentativi. Utilizza un backoff limitato invece di tentativi paralleli immediati.
- Errore temporaneo del servizio: riprova entro un limite definito di tentativi e tempo.
- Timeout dopo l'invio: riconcilia lo stato di registrazione della spedizione utilizzando il comportamento documentato dell'API prima di presumere che il primo tentativo sia fallito.
- Risposta relativa a un duplicato: verifica se la spedizione è già registrata e correttamente associata al record della tua applicazione.
Non presumere che la registrazione sia idempotente a meno che la documentazione non definisca tale comportamento. La deduplicazione lato applicazione riduce gli invii ripetuti accidentali, ma non stabilisce la politica del provider per la gestione dei duplicati.
Utilizza una regola di unicità interna adeguata al modello delle tue spedizioni. Il solo numero di tracciamento potrebbe non essere una chiave permanente sufficiente tra corrieri e lunghi periodi di conservazione. Conserva il contesto del corriere e il tuo identificativo della spedizione e documenta come vengono gestite le sostituzioni e i numeri corretti.
Monitora la registrazione separatamente dagli aggiornamenti di tracciamento
Il monitoraggio dell'API dovrebbe distinguere un errore di integrazione da una spedizione che semplicemente non ha nuovi eventi del corriere. Queste condizioni richiedono responsabili e correzioni diversi.
Per la registrazione, monitora i conteggi di accettazioni e rifiuti, le categorie di errore, gli esiti incerti, la coda dei tentativi e la latenza delle risposte. Per il tracciamento successivo, monitora separatamente la ricezione degli aggiornamenti o gli errori di recupero. Evita di assegnare soglie numeriche di allerta finché non comprendi il traffico normale e i limiti operativi documentati del provider.
Un controllo pratico in produzione dovrebbe rispondere a queste domande:
- Ogni spedizione in attesa di tracciamento ha un record di registrazione?
- Ogni registrazione accettata può essere ricondotta al pacco corretto?
- Gli elementi rifiutati vengono indirizzati a qualcuno che possa correggere i dati sottostanti?
- Le richieste incerte vengono riconciliate invece di essere abbandonate o ritentate indefinitamente?
- Gli stati mostrati ai clienti derivano dagli eventi della spedizione anziché dall'accettazione della registrazione?
- Le credenziali e le informazioni personali non necessarie sono escluse dai log?
Per le operazioni ecommerce, il passaggio operativo è importante quanto la chiamata API. Gli sviluppatori dovrebbero occuparsi degli errori di trasporto e analisi; i team di spedizione o fulfillment dovrebbero poter verificare etichette errate, mappature dei corrieri e informazioni mancanti sulle spedizioni.
FAQ
Posso registrare un numero di tracciamento prima della prima scansione del corriere?
La registrazione e le scansioni del corriere sono eventi separati. Un servizio può accettare un numero prima che gli eventi di tracciamento siano disponibili, in base alle proprie regole di convalida. Non interpretare l'accettazione come prova che il corriere abbia ricevuto il pacco.
Devo sempre fornire un codice corriere?
Dipende dal comportamento di rilevamento documentato dall'API e dalla spedizione coinvolta. Se il corriere è noto, un identificativo esplicito e mappato correttamente può ridurre l'ambiguità. Se è sconosciuto, utilizza il metodo di rilevamento automatico documentato invece di inventare un valore per il corriere.
Perché l'API ha restituito un successo HTTP mentre una spedizione è fallita?
La richiesta HTTP può avere esito positivo mentre l'applicazione rifiuta un singolo elemento. Leggi il risultato principale dell'applicazione e i risultati a livello di spedizione. Questa distinzione è particolarmente importante per le richieste batch.
Cosa devo fare quando una richiesta di registrazione va in timeout?
Considera il risultato incerto. Il server potrebbe aver elaborato la richiesta prima che la connessione fallisse. Verifica il comportamento documentato del provider per i duplicati e i metodi disponibili di ricerca della registrazione o del tracciamento, quindi riconcilia o riprova secondo una politica limitata.
La registrazione configura automaticamente le notifiche di tracciamento?
Non presumere che lo faccia. Registrazione, recupero del tracciamento e configurazione dei webhook sono aspetti separati dell'integrazione. Verifica la documentazione pertinente e testa l'intero percorso degli aggiornamenti prima di farvi affidamento per le notifiche ai clienti.
Fonti
- Documentazione API 17TRACK — riferimento per endpoint di registrazione, autenticazione, campi della richiesta, identificativi dei corrieri, schemi delle risposte e gestione degli errori. Adatta i dettagli dell'implementazione alla versione dell'API che distribuisci.
- Panoramica dell'API di tracciamento 17TRACK — punto di partenza ufficiale per il prodotto API di tracciamento e le risorse di integrazione per sviluppatori.


