Skip to main content
CasaBlogGuideCome convalidare i numeri di tracciamento prima dell’invio all’API: 7 regole da seguire

Come convalidare i numeri di tracciamento prima dell’invio all’API: 7 regole da seguire

17TRACK

Convalida un numero di tracciamento a più livelli prima di inviarlo a un'API di tracciamento: normalizza l'input, verifica la struttura di base, conferma il contesto del corriere, applica un checksum solo quando il corriere ne documenta l'uso e rifiuta i valori chiaramente non sicuri o incompleti. Non affidarti a una singola espressione regolare universale. I formati dei numeri di tracciamento variano in base al corriere, al servizio, al Paese e al tipo di spedizione; pertanto, un validatore efficace dovrebbe impedire le richieste errate senza bloccare numeri legittimi che utilizzano un formato non familiare.

7 regole per convalidare i numeri di tracciamento prima dell

Questa guida è destinata agli sviluppatori e ai team operativi che integrano il tracciamento delle spedizioni in un sistema di gestione degli ordini, in un flusso di lavoro di magazzino, in un portale clienti o in un'applicazione di ecommerce. L'obiettivo non è dimostrare che un pacco esista prima dell'invio. La convalida sintattica e la convalida dello stato della spedizione sono fasi separate.

Cosa può e non può confermare la convalida

Un validatore preliminare può identificare problemi comuni dell'input, come un valore vuoto, spazi accidentali, caratteri non supportati, una lunghezza eccessiva o un numero di tracciamento inserito nel campo sbagliato. Può anche identificare un probabile corriere quando il corriere è noto e il formato è documentato.

Normalmente non può confermare che un numero appartenga a una spedizione reale, che il pacco sia stato accettato da un corriere o che il numero sia attualmente tracciabile. Per rispondere a queste domande è necessaria una ricerca presso il corriere o la piattaforma di tracciamento. Un numero può superare il controllo del formato e tuttavia non essere stato utilizzato, contenere un errore di battitura non evidente, essere scaduto o essere associato a un servizio diverso.

Le sette regole

1. Normalizza il valore senza cambiarne il significato

Gli utenti e i sistemi upstream aggiungono spesso spazi iniziali o finali, interruzioni di riga, spazi unificatori o caratteri di formattazione. Normalizzali in modo sicuro prima della convalida. Un primo passaggio comune consiste nel rimuovere gli spazi superflui circostanti e convertire gli spazi non stampabili in spazi ordinari. Se il formato documentato del corriere consente spazi o trattini interni, decidi se rimuoverli per la richiesta API o conservare il valore originale per la visualizzazione e l'audit.

Quando è pratico, conserva due valori: l'input originale e un valore canonico. L'originale aiuta i team di supporto a indagare sui problemi di qualità dei dati; il valore canonico viene utilizzato per la convalida e l'invio. Evita trasformazioni che possono alterare gli identificatori. Non convertire automaticamente le lettere in numeri, non sostituire i caratteri ambigui e non rimuovere ogni segno di punteggiatura, a meno che la documentazione del corriere o dell'API pertinente non supporti esplicitamente tale comportamento.

La gestione Unicode richiede attenzione. Un carattere visivamente simile proveniente da un altro alfabeto potrebbe non essere accettato da un'API anche se appare come una lettera o una cifra ASCII. Limitare il valore canonico al set di caratteri consentito dall'integrazione selezionata può prevenire errori a valle difficili da interpretare.

2. Rifiuta i valori che non superano i controlli strutturali di base

Prima di applicare la logica specifica del corriere, verifica se il valore è presente e plausibile. I controlli utili includono la lunghezza minima e massima, le classi di caratteri consentite e la verifica che il valore non contenga solo spazi o un segnaposto come “N/A”, “TBD” o “test”. I limiti esatti dovrebbero derivare dal contratto dell'API o dalla documentazione del corriere. Evita di inventare una lunghezza massima universale solo perché la maggior parte degli esempi è breve.

Un controllo strutturale dovrebbe essere deliberatamente prudente. Ad esempio, una regola che consente solo cifre rifiuterà gli identificatori alfanumerici validi. Una regola che richiede una lunghezza fissa può rifiutare varianti del servizio o formati internazionali. Usa controlli generici per intercettare gli errori evidenti, quindi applica controlli più specifici solo quando il corriere e il servizio sono noti.

Convalida inoltre il tipo di dati al confine dell'applicazione. Un numero di tracciamento dovrebbe normalmente essere trattato come una stringa, non come un intero. La conversione numerica può rimuovere gli zeri iniziali e creare problemi di precisione nei sistemi che utilizzano tipi numerici a larghezza fissa. Conserva il valore esattamente come stringa dopo la normalizzazione approvata.

3. Usa il contesto del corriere invece di fare supposizioni basate solo sul numero

Un numero di tracciamento senza corriere è un input ambiguo. Corrieri diversi possono usare lunghezze, prefissi o set di caratteri sovrapposti, e un formato plausibile per un corriere può essere non valido per un altro. Se l'ordine, l'etichetta, il sistema di magazzino o l'account del commerciante identifica già il corriere, trasmetti tale contesto insieme al numero di tracciamento ogni volta che l'API lo supporta.

Il contesto del corriere migliora sia la convalida sia l'instradamento. Permette all'applicazione di selezionare le regole di formato pertinenti, riduce le corrispondenze errate e rende più utili i messaggi di errore. Impedisce inoltre che un risultato di rilevamento automatico venga trattato come un fatto quando più corrieri potrebbero accettare un valore dall'aspetto simile.

Se il corriere è sconosciuto, usa un approccio in due fasi. Innanzitutto, esegui i controlli generici di sicurezza. Successivamente, invia il valore solo tramite un flusso API che supporti esplicitamente il rilevamento del corriere oppure inseriscilo in una coda di revisione quando il processo aziendale richiede un corriere confermato. Non assegnare silenziosamente un corriere basandoti solo su un prefisso, a meno che tale corrispondenza non sia mantenuta e documentata.

4. Applica i checksum solo quando la regola è documentata

Alcuni sistemi di identificazione utilizzano cifre di controllo, ma i numeri di tracciamento non sono regolati da un unico standard universale di checksum. Un checksum può rilevare determinati errori di trascrizione, ma non dimostra che una spedizione esista. Inoltre, l'applicazione dell'algoritmo di checksum sbagliato può rifiutare numeri validi.

Implementa un checksum solo quando il corriere, il servizio, la specifica dell'etichetta o la documentazione dell'API pertinente definisce l'algoritmo e la parte dell'input a cui si applica. Registra la versione della regola e testala con esempi ufficiali. Se non è disponibile una regola autorevole, salta il checksum invece di indovinare sulla base di schemi osservati in un campione ridotto.

Considera il risultato del checksum come un segnale, non come una decisione completa di convalida. Un controllo fallito può giustificare il blocco dell'invio quando la regola è autorevole. Un controllo superato dovrebbe far avanzare il valore alla fase successiva, non contrassegnarlo come spedizione attiva.

5. Separa la convalida del formato dall'idoneità dell'API

Un valore può essere ben formato ma non essere comunque adatto all'endpoint che stai chiamando. Prima dell'invio, verifica nella documentazione dell'API i campi obbligatori, gli identificatori dei corrieri accettati, i requisiti di autenticazione, i limiti delle richieste, il comportamento per i duplicati e le eventuali restrizioni sui tipi di servizio o sulle destinazioni. Queste sono regole di integrazione, non regole del numero di tracciamento, ma determinano se un identificatore valido può essere elaborato correttamente.

La documentazione dell'API di tracciamento 17TRACK è un esempio del motivo per cui questa distinzione è importante: gli sviluppatori devono seguire il modello di richiesta della piattaforma e il comportamento d'integrazione supportato, invece di inventare una richiesta basandosi sull'aspetto di un numero di tracciamento. Consulta la documentazione aggiornata per i requisiti degli endpoint e la gestione delle risposte all'indirizzo Documentazione API di 17TRACK.

Mantieni separati gli errori di convalida dagli errori di trasporto e autenticazione. “Formato del numero di tracciamento non valido”, “corriere sconosciuto”, “limite di richieste raggiunto” e “autorizzazione fallita” richiedono azioni diverse. Un singolo messaggio generico come “invio non riuscito” rende meno affidabili i tentativi e i report operativi.

6. Proteggi l'API con input limitati, deduplicazione e tentativi sicuri

La convalida è anche una misura di sicurezza operativa. Imposta una lunghezza massima dell'input prima dell'analisi o della registrazione nei log. Rifiuta i caratteri di controllo e le strutture di payload impreviste. Applica limiti di frequenza al confine della tua applicazione, in modo che un'importazione difettosa non generi un picco incontrollato di richieste.

Deduplica prima dell'invio quando il processo aziendale non richiede registrazioni ripetute. Una chiave di deduplicazione utile può includere il numero di tracciamento canonico, il corriere, l'account e il contesto della spedizione. La chiave corretta dipende dal flusso di lavoro; lo stesso identificatore può talvolta essere riutilizzato per servizi o record aziendali diversi, quindi non presumere che il numero da solo sia sempre univoco a livello globale.

Usa tentativi limitati con backoff per gli errori temporanei ed evita di ripetere gli errori permanenti di convalida. Memorizza un record di idempotenza o di invio quando l'API e la tua architettura lo supportano. Registra informazioni sufficienti per risolvere i problemi della richiesta, ma proteggi le credenziali, i dati dei clienti e qualsiasi dettaglio sensibile della spedizione. Un validatore dovrebbe ridurre i fallimenti ripetuti, non creare un secondo problema di sicurezza attraverso una registrazione eccessiva.

7. Conferma il risultato dopo l'invio e monitora i falsi positivi

L'ultima regola consiste nel trattare la convalida preliminare come un filtro, non come un verdetto. Dopo l'accettazione della richiesta, esamina la risposta dell'API e memorizza lo stato, l'identificatore della richiesta, l'associazione al corriere e qualsiasi codice di errore documentato. Se la piattaforma accetta la richiesta ma non è ancora in grado di restituire eventi di movimentazione, ciò può indicare un ritardo nell'elaborazione anziché un numero non valido.

Definisci una politica di follow-up per i numeri che rimangono irrisolti. La finestra temporale dovrebbe riflettere il corriere, il servizio, l'origine della spedizione e la politica del servizio clienti; non esiste un periodo universale che dimostri che un numero è non valido. Inoltra alla revisione i record con corriere mancante, errori ripetuti del provider, risultati discordanti tra i corrieri o uno stato non coerente con il record dell'ordine.

Misura i falsi rifiuti e le false accettazioni. Un'espressione regolare rigida può ridurre gli invii malformati bloccando però erroneamente spedizioni legittime. Un validatore permissivo può aumentare le richieste accettate ma creare rumore a valle. Esamina i campioni falliti per corriere e servizio, aggiorna le regole documentate tramite il controllo delle versioni e testa le modifiche su un set di dati rappresentativo e sicuro dal punto di vista della privacy.

Una sequenza pratica di convalida

Un'implementazione facilmente manutenibile può usare la sequenza seguente:

  1. Verifica che la richiesta contenga un valore stringa e un record aziendale valido.
  2. Salva l'input originale, quindi crea una forma canonica documentata.
  3. Rifiuta valori vuoti, segnaposto, caratteri non sicuri e valori al di fuori dell'intervallo di lunghezza documentato.
  4. Risolvi il corriere dai dati attendibili dell'ordine oppure usa un flusso di rilevamento esplicitamente supportato.
  5. Applica la sintassi specifica del corriere e le regole di checksum solo quando sono supportate da una documentazione autorevole.
  6. Verifica i requisiti dell'endpoint, lo stato dei duplicati e l'idoneità ai tentativi.
  7. Invia, classifica la risposta, memorizza il risultato e pianifica il follow-up per i record irrisolti.

Questa sequenza rende il validatore più facile da testare perché ogni decisione ha una motivazione diversa. Inoltre fornisce ai team operativi categorie di errore utilizzabili invece di un singolo errore opaco.

Checklist di implementazione

  • Memorizza i numeri di tracciamento come stringhe per preservare gli zeri iniziali.
  • Conserva separatamente i valori originali e canonici quando l'audit è importante.
  • Mantieni le regole dei corrieri come configurazione versionata, non come condizioni codificate in modo rigido e disperse nel codice.
  • Testa lettere, cifre, trattini, spazi, caratteri Unicode simili, segnaposto e lunghezze limite.
  • Usa il contesto attendibile del corriere ogni volta che è disponibile.
  • Non dedurre l'esistenza di una spedizione dal superamento di una corrispondenza con un'espressione regolare.
  • Classifica separatamente gli errori permanenti di convalida dagli errori temporanei dell'API o della rete.
  • Esamina la documentazione del provider prima di modificare le regole del formato o la logica delle richieste.

Domande frequenti

Un'espressione regolare può convalidare un numero di tracciamento?

Può convalidare uno schema limitato quando il formato del corriere e del servizio è noto. Non può dimostrare che il numero esista, appartenga a una determinata spedizione o sia attualmente attivo. Un'espressione universale probabilmente produrrà falsi rifiuti o false corrispondenze.

Un numero dall'aspetto non valido dovrebbe essere inviato all'API?

I valori chiaramente vuoti, non sicuri o strutturalmente impossibili dovrebbero normalmente essere bloccati prima dell'invio. Un formato non familiare ma altrimenti sicuro non dovrebbe essere rifiutato solo perché non corrisponde a un'ipotesi interna. Consulta prima la documentazione del corriere o usa un processo di rilevamento supportato.

Un checksum è sufficiente per confermare una spedizione?

No. Un checksum, quando applicabile, verifica soltanto se il valore soddisfa una regola matematica. Non conferma che il corriere abbia emesso il numero o che il pacco sia entrato nella rete.

Cosa dovrebbe accadere quando il corriere è sconosciuto?

Esegui i controlli generici di sicurezza e usa un flusso API che supporti esplicitamente il rilevamento del corriere, se disponibile. Altrimenti, conserva il record per l'arricchimento o la revisione manuale invece di indovinare silenziosamente il corriere.

Come dovrebbero essere gestiti gli errori dell'API?

Classificali in base alla causa. Correggi gli input malformati e i valori di corriere non supportati; riprova gli errori temporanei di rete o del provider con limiti e backoff; indirizza invece gli errori di autenticazione o di quota al responsabile dell'integrazione. Memorizza i dettagli della risposta necessari per la diagnosi senza esporre i segreti.

Fonti