Skip to main content
CasaBlogGuideLa tua prima richiesta all’API di tracciamento: guida passo passo a un client REST con Postman e Curl

La tua prima richiesta all’API di tracciamento: guida passo passo a un client REST con Postman e Curl

17TRACK

Per effettuare la prima richiesta all'API di tracking, configura l'endpoint, l'header di autenticazione e il corpo JSON in un client REST, invia la richiesta e controlla sia lo stato HTTP sia il corpo della risposta. Questa guida utilizza l'API di tracking di 17TRACK per dimostrare lo stesso flusso di lavoro in Postman e curl: registra una spedizione, richiedi le relative informazioni di tracking e verifica se il risultato è pronto per essere utilizzato dalla tua applicazione.

La tua prima richiesta all'API di tracking: guida a un client REST

L'obiettivo è un piccolo test di integrazione riproducibile, non una distribuzione in produzione. Ti serviranno una credenziale API e un numero di tracking che sei autorizzato a elaborare. I comandi riportati di seguito utilizzano il modello di endpoint v2.2; verifica la versione dell'endpoint e i requisiti specifici dell'account nella documentazione dell'API di 17TRACK prima di eseguirli.

Comprendi cosa dovrebbe realizzare la tua prima richiesta

Un'integrazione per il tracking delle spedizioni comprende due aspetti distinti: indicare al servizio quale spedizione monitorare e recuperare le informazioni di tracking associate a quella spedizione. Nel flusso di lavoro illustrato qui, si tratta di richieste separate. La registrazione non significa che il pacco sia già in movimento e una registrazione riuscita non garantisce che gli eventi del corriere siano immediatamente disponibili.

Per il primo test, utilizza una sola spedizione anziché un lotto. In questo modo sarà più facile isolare gli errori di autenticazione, i numeri di tracking non validi e l'interpretazione della risposta. Il primo traguardo utile non è semplicemente «ho ricevuto HTTP 200». È «l'API ha accettato l'operazione prevista e posso spiegare il risultato a livello di spedizione».

Postman offre un'interfaccia visiva per modificare le richieste e analizzare le risposte. curl rende riproducibile lo stesso scambio HTTP da un terminale. Nessuno dei due modifica le regole di autenticazione dell'API, i dati della spedizione o il comportamento di elaborazione. Usa lo strumento che ti aiuta a esaminare più chiaramente la richiesta, quindi riproduci la configurazione funzionante nell'altro strumento.

Prepara la credenziale, la spedizione e i dettagli della richiesta

Prima di aprire uno dei due client, raccogli quanto segue:

  • Una credenziale API autorizzata: ottienila tramite la configurazione del tuo account API 17TRACK. Una sessione di tracking per consumatori non sostituisce una credenziale API.
  • Un numero di tracking reale: utilizza una spedizione di tua proprietà o alla quale hai il permesso di accedere. Una spedizione attiva di recente è generalmente più utile di un numero inventato quando si testano dati di tracking reali.
  • Il corriere, se noto: tieni a disposizione il nome del corriere per la diagnosi. Se per il tuo caso è richiesto un identificativo del corriere, utilizza il valore e il campo definiti nella documentazione dell'API invece di procedere per tentativi.
  • Il contratto della richiesta corrente: conferma la versione dell'API, l'header di autenticazione, lo schema della richiesta e le eventuali limitazioni dell'account.
  • Un ambiente di lavoro sicuro: evita di inserire credenziali, dati dei clienti o risposte di tracking complete in repository pubblici, screenshot o messaggi di assistenza condivisi.

Gli esempi di richiesta minimi utilizzano queste impostazioni:

ImpostazioneConfigurazione di esempio
URL di basehttps://api.17track.net/track/v2.2
Operazione di registrazionePOST /register
Operazione per le informazioni di trackingPOST /gettrackinfo
Header di autenticazione17token: YOUR_API_TOKEN
Formato del corpoContent-Type: application/json, con un array JSON di oggetti spedizione

Conserva i numeri di tracking come stringhe. La conversione in un tipo numerico può rimuovere gli zeri iniziali o alterarne altrimenti il valore. Il segnaposto YOUR_TRACKING_NUMBER riportato di seguito deve essere sostituito con la spedizione di test effettiva; non è un numero di esempio funzionante.

Effettua la richiesta di registrazione in Postman

1. Crea un piccolo ambiente di test

In Postman, crea un ambiente con tre variabili: base_url, tracking_token e tracking_number. Imposta base_url sull'URL di base indicato sopra e inserisci la credenziale e il numero della spedizione nelle altre variabili. Seleziona l'ambiente prima di inviare la richiesta.

Utilizza i controlli disponibili in Postman per la gestione sicura dei segreti per il token e verifica cosa viene condiviso o sincronizzato dal tuo workspace. Nascondere un valore nell'interfaccia non sostituisce il controllo su chi può accedervi. Non esportare credenziali valorizzate con una raccolta destinata ai colleghi o alla documentazione pubblica.

2. Configura metodo, URL e header

Crea una richiesta HTTP, seleziona POST e inserisci {{base_url}}/register come URL. Nella scheda Headers, aggiungi:

17token: {{tracking_token}}
Content-Type: application/json

In questo esempio, la credenziale deve essere inserita nell'header personalizzato 17token. Non sostituirlo con una configurazione di token Bearer solo perché un'altra API utilizza questo schema. Controlla inoltre che le impostazioni ereditate dalla raccolta non introducano un header Authorization indesiderato.

3. Aggiungi il corpo JSON

Apri Body, scegli raw e seleziona JSON. Inserisci:

[
  {
    "number": "{{tracking_number}}"
  }
]

Le parentesi quadre esterne sono importanti: questa richiesta utilizza un array, anche se contiene una sola spedizione. Usa le virgolette doppie, rimuovi le virgole finali e non inserire commenti nel JSON. Se la documentazione richiede informazioni aggiuntive per il tuo corriere o la tua spedizione, aggiungi i campi documentati prima dell'invio.

4. Invia e analizza il risultato

Fai clic su Send. Innanzitutto, verifica se hai ricevuto una risposta HTTP. Un errore DNS, un errore TLS, un problema del proxy o un timeout sono diversi da una risposta che indica che la richiesta non era valida. Successivamente, analizza il corpo della risposta per individuare il risultato dell'operazione e le eventuali informazioni di accettazione o rifiuto a livello di spedizione.

Salva la richiesta come «Register test shipment». Registra lo stato HTTP, il risultato dell'API e ogni messaggio di errore senza copiare il token. Se la registrazione non riesce, risolvi il problema prima di procedere. L'invio ripetuto di una richiesta invariata rende più difficile la diagnosi e può consumare risorse dell'account.

Riproduci la richiesta con curl

I comandi seguenti utilizzano una shell in stile POSIX, come Bash o Zsh. PowerShell e Windows Command Prompt hanno regole diverse per virgolette e variabili. In PowerShell, quando necessario usa curl.exe per richiamare l'eseguibile curl anziché un alias di comando specifico della shell.

Imposta l'URL di base e carica la credenziale in una variabile d'ambiente tramite il normale flusso di gestione dei segreti:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Una variabile d'ambiente mantiene la credenziale fuori dall'esempio riutilizzabile, ma non costituisce un sistema completo di gestione dei segreti. Per i test locali, evita di digitare un token reale in un comando che verrà conservato dalla cronologia della shell. Per l'automazione, utilizza l'archivio dei segreti della tua piattaforma e limita l'output dei log.

Crea un file denominato shipment.json e sostituisci il segnaposto con il numero di tracking di test:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Invia la richiesta di registrazione:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Questo salva il corpo della risposta in register-response.json e stampa separatamente lo stato HTTP. I timeout di connessione e totali sono scelte per i test locali, non garanzie del servizio 17TRACK. Apri il file salvato per analizzare il risultato dell'API; la sola riga dello stato non è sufficiente.

curl può completare correttamente un trasferimento anche quando il server restituisce una risposta di errore HTTP. Al contrario, un errore di trasporto può impedire l'arrivo di una risposta API utilizzabile. Quando crei script, gestisci separatamente lo stato di uscita di curl, lo stato HTTP e il risultato a livello applicativo.

Richiedi le informazioni di tracking della spedizione

Dopo aver confermato la registrazione, duplica la richiesta Postman e modifica l'URL in {{base_url}}/gettrackinfo. Mantieni il metodo POST, l'header di autenticazione, il tipo di contenuto e il corpo della spedizione. Salvala separatamente per non registrare accidentalmente di nuovo la spedizione quando intendi recuperarne i dati.

La richiesta curl equivalente è:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Non presumere che una spedizione appena registrata restituisca immediatamente una cronologia completa degli eventi. La disponibilità dei dati dipende dalla spedizione e dall'elaborazione del servizio. Se le informazioni non sono ancora disponibili, segui le indicazioni documentate per il recupero e l'aggiornamento invece di registrare ripetutamente lo stesso numero o eseguire un ciclo di polling troppo ravvicinato.

Leggi la risposta su tre livelli

  1. Trasporto: il client si è connesso e ha ricevuto una risposta HTTP?
  2. Operazione: l'API ha accettato la richiesta e la singola spedizione è andata a buon fine?
  3. Informazioni sulla spedizione: i dati restituiti identificano il pacco previsto e cosa dimostrano effettivamente il suo stato o la cronologia degli eventi?

Utilizza lo schema ufficiale della risposta per individuare i campi relativi a stato, corriere ed eventi. Mantieni la distinzione tra uno stato della spedizione normalizzato e la descrizione originale dell'evento del corriere. Una ricerca riuscita non dimostra che la consegna sia avvenuta e l'assenza di eventi non dimostra che un pacco sia smarrito.

Quando memorizzi i timestamp, conserva le informazioni sul fuso orario o sull'offset fornito. Evita di ordinare stringhe di date grezze provenienti da formati diversi presumendo che rappresentino una sequenza cronologica corretta. Distingui inoltre il momento in cui la tua applicazione ha recuperato un record dal momento in cui si è verificato l'evento della spedizione.

Risolvi i problemi senza cambiare tutto contemporaneamente

  • Nessuna risposta: controlla il nome host, l'accesso alla rete, le impostazioni del proxy, la configurazione TLS e il timeout locale. Non disabilitare la verifica dei certificati come soluzione ordinaria.
  • Errore di autenticazione: verifica che il token sia attivo, che l'header 17token sia presente e che l'ambiente Postman selezionato risolva correttamente la variabile. Controlla la presenza accidentale di spazi.
  • Richiesta non valida: verifica la versione dell'API, il percorso dell'operazione, il metodo POST, il tipo di contenuto e la struttura dell'array JSON rispetto alla documentazione.
  • Spedizione rifiutata: leggi l'errore specifico della spedizione. Controlla il numero e le eventuali informazioni richieste sul corriere invece di considerare ogni rifiuto come un problema di autenticazione.
  • Nessun evento di tracking: conferma la registrazione e l'identità della spedizione prevista. Verifica se sono necessarie informazioni sul corriere e se gli aggiornamenti sono disponibili prima di riprovare.
  • Postman funziona ma curl no: confronta l'URL risolto, gli header effettivi e i byte del corpo. Le virgolette della shell e le variabili d'ambiente non impostate sono cause comuni di divergenza tra le richieste.

Modifica una variabile per test e conserva una breve registrazione del risultato. Se analizzi la console di Postman o utilizzi l'output dettagliato di curl, considera l'output come sensibile: gli header delle richieste possono esporre credenziali. Oscura i segreti e le informazioni dei clienti prima di condividere la diagnostica.

Sappi quando la guida è completa

Hai completato un primo test di integrazione significativo quando entrambi i client inviano la richiesta prevista, la registrazione è compresa, il recupero restituisce un risultato interpretabile e sai distinguere un errore dell'API da una spedizione senza nuove informazioni. La sola corrispondenza dei codici di stato HTTP non dimostra che i due client si siano comportati in modo identico.

Prima di trasferire il flusso di lavoro in un'applicazione, conserva le credenziali sul server, convalida gli input e utilizza una gestione strutturata degli errori. Consulta i limiti di frequenza, i limiti dei batch, le indicazioni sui tentativi e le opzioni di consegna degli aggiornamenti documentati per il tuo account. Non presumere che sia sicuro ripetere ciecamente la registrazione dopo un timeout: il server potrebbe aver elaborato la richiesta anche se il client non ha ricevuto la risposta.

Aggiungi test per una credenziale non valida, JSON malformato, un numero di spedizione non valido, una spedizione già registrata, dati di tracking non disponibili e un timeout di rete. Ogni caso dovrebbe portare a un risultato applicativo deliberato anziché a un'eccezione non gestita o a uno stato fuorviante mostrato al cliente.

FAQ

Posso testare senza un numero di tracking reale?

Puoi testare alcuni comportamenti di convalida della richiesta con un valore non valido, ma ciò non verifica il tracking della spedizione. Per testare eventi reali, utilizza una spedizione autorizzata o un dispositivo di test documentato, se il servizio ne fornisce uno. Non presumere che numeri di esempio arbitrari appartengano a un ambiente sandbox.

Perché una risposta HTTP 200 contiene comunque un errore?

Lo stato HTTP e i risultati dell'applicazione descrivono livelli diversi. Un server può ricevere ed elaborare correttamente una richiesta segnalando al contempo che una singola spedizione è stata rifiutata. Leggi il corpo della risposta e il risultato documentato a livello di spedizione, non soltanto lo stato HTTP.

Perché viene utilizzato POST per recuperare le informazioni di tracking?

Utilizza il metodo specificato dal contratto dell'endpoint. Questo esempio di recupero accetta gli identificativi della spedizione in un corpo della richiesta JSON tramite POST. Modificarlo in GET perché l'operazione legge dati non mantiene la richiesta documentata.

Devo inserire il token API nel JavaScript del browser?

Non incorporare una credenziale API privata nel codice frontend distribuito pubblicamente. Instrada le richieste attraverso un backend autorizzato che protegga la credenziale, convalidi gli input e controlli a quali informazioni sulle spedizioni può accedere ciascun utente.

Mi servono sia Postman sia curl per la produzione?

No. Sono strumenti utili per test e diagnosi. La tua applicazione di produzione può utilizzare un client HTTP appropriato. Conserva una richiesta Postman o un comando curl sanificato come riferimento riproducibile, senza un token attivo o dati cliente non necessari.

Fonti