Skip to main content
ΑρχικήΙστολόγιοΟδηγοίΤο πρώτο σας αίτημα στο Tracking API: Οδηγός χρήσης του Rest Client με Postman και Curl

Το πρώτο σας αίτημα στο Tracking API: Οδηγός χρήσης του Rest Client με Postman και Curl

17TRACK

Για να κάνετε το πρώτο σας αίτημα στο tracking API, διαμορφώστε το endpoint, την κεφαλίδα ελέγχου ταυτότητας και το σώμα JSON σε έναν REST client, στείλτε το αίτημα και ελέγξτε τόσο την κατάσταση HTTP όσο και το σώμα της απόκρισης. Αυτός ο οδηγός χρησιμοποιεί το Tracking API της 17TRACK για να παρουσιάσει την ίδια ροή εργασίας στα Postman και curl: καταχωρίστε μια αποστολή, ζητήστε τις πληροφορίες παρακολούθησής της και ελέγξτε αν το αποτέλεσμα είναι έτοιμο για χρήση από την εφαρμογή σας.

Οδηγός για το πρώτο σας αίτημα Tracking API σε REST client

Ο στόχος είναι μια μικρή, αναπαραγώγιμη δοκιμή ενσωμάτωσης — όχι μια ανάπτυξη σε περιβάλλον παραγωγής. Θα χρειαστείτε ένα διαπιστευτήριο API και έναν αριθμό παρακολούθησης που έχετε εξουσιοδότηση να επεξεργαστείτε. Οι παρακάτω εντολές χρησιμοποιούν το μοτίβο endpoint v2.2· επιβεβαιώστε την έκδοση του endpoint και τις απαιτήσεις που αφορούν τον λογαριασμό σας στην τεκμηρίωση API της 17TRACK πριν τις εκτελέσετε.

Κατανοήστε τι πρέπει να επιτυγχάνει το πρώτο σας αίτημα

Μια ενσωμάτωση παρακολούθησης αποστολών περιλαμβάνει δύο ξεχωριστές λειτουργίες: να ενημερώσει την υπηρεσία ποια αποστολή θα παρακολουθήσει και να ανακτήσει τις πληροφορίες παρακολούθησης που σχετίζονται με αυτήν την αποστολή. Στη ροή εργασίας που παρουσιάζεται εδώ, πρόκειται για ξεχωριστά αιτήματα. Η καταχώριση δεν σημαίνει ότι το δέμα έχει ήδη μετακινηθεί και μια επιτυχής καταχώριση δεν εγγυάται ότι τα συμβάντα του μεταφορέα θα είναι άμεσα διαθέσιμα.

Για την πρώτη σας δοκιμή, χρησιμοποιήστε μία αποστολή αντί για παρτίδα. Έτσι είναι ευκολότερο να απομονώσετε σφάλματα ελέγχου ταυτότητας, μη έγκυρους αριθμούς παρακολούθησης και την ερμηνεία της απόκρισης. Το πρώτο χρήσιμο ορόσημο δεν είναι απλώς «έλαβα HTTP 200». Είναι «το API αποδέχθηκε την προβλεπόμενη λειτουργία μου και μπορώ να εξηγήσω το αποτέλεσμα σε επίπεδο αποστολής».

Το Postman παρέχει οπτικό περιβάλλον για την επεξεργασία αιτημάτων και την επιθεώρηση αποκρίσεων. Το curl καθιστά την ίδια ανταλλαγή HTTP αναπαραγώγιμη από ένα τερματικό. Κανένα από τα δύο δεν αλλάζει τους κανόνες ελέγχου ταυτότητας του API, τα δεδομένα αποστολής ή τη συμπεριφορά επεξεργασίας. Χρησιμοποιήστε όποιο σας βοηθά να διερευνήσετε πιο καθαρά το αίτημα και, στη συνέχεια, αναπαραγάγετε τη λειτουργική διαμόρφωση στο άλλο εργαλείο.

Προετοιμάστε το διαπιστευτήριο, την αποστολή και τις λεπτομέρειες του αιτήματος

Πριν ανοίξετε οποιοδήποτε από τα δύο client, συγκεντρώστε τα εξής:

  • Ένα εξουσιοδοτημένο διαπιστευτήριο API: αποκτήστε το μέσω της ρύθμισης του λογαριασμού σας στο 17TRACK API. Μια συνεδρία παρακολούθησης καταναλωτή δεν υποκαθιστά ένα διαπιστευτήριο API.
  • Έναν πραγματικό αριθμό παρακολούθησης: χρησιμοποιήστε μια αποστολή που σας ανήκει ή στην οποία έχετε άδεια πρόσβασης. Μια πρόσφατα ενεργή αποστολή είναι συνήθως πιο χρήσιμη από έναν επινοημένο αριθμό κατά τη δοκιμή πραγματικών δεδομένων παρακολούθησης.
  • Τον μεταφορέα, εφόσον είναι γνωστός: κρατήστε το όνομα του μεταφορέα διαθέσιμο για διάγνωση. Αν απαιτείται αναγνωριστικό μεταφορέα για την περίπτωσή σας, χρησιμοποιήστε την τιμή και το πεδίο που ορίζονται στην τεκμηρίωση του API αντί να μαντέψετε.
  • Το τρέχον συμβόλαιο αιτήματος: επιβεβαιώστε την έκδοση του API, την κεφαλίδα ελέγχου ταυτότητας, το σχήμα αιτήματος και τυχόν περιορισμούς λογαριασμού.
  • Έναν ασφαλή χώρο εργασίας: αποφύγετε την τοποθέτηση διαπιστευτηρίων, στοιχείων πελατών ή πλήρων αποκρίσεων παρακολούθησης σε δημόσια αποθετήρια, στιγμιότυπα οθόνης ή κοινόχρηστα μηνύματα υποστήριξης.

Τα ελάχιστα παραδείγματα αιτημάτων χρησιμοποιούν αυτές τις ρυθμίσεις:

ΡύθμισηΠαράδειγμα διαμόρφωσης
Base URLhttps://api.17track.net/track/v2.2
Λειτουργία καταχώρισηςPOST /register
Λειτουργία πληροφοριών παρακολούθησηςPOST /gettrackinfo
Κεφαλίδα ελέγχου ταυτότητας17token: YOUR_API_TOKEN
Μορφή σώματοςContent-Type: application/json, με πίνακα JSON αντικειμένων αποστολής

Διατηρείτε τους αριθμούς παρακολούθησης ως συμβολοσειρές. Η μετατροπή ενός αριθμού σε αριθμητικό τύπο μπορεί να αφαιρέσει αρχικά μηδενικά ή να αλλάξει διαφορετικά την τιμή του. Το σύμβολο κράτησης θέσης YOUR_TRACKING_NUMBER παρακάτω πρέπει να αντικατασταθεί με την πραγματική δοκιμαστική αποστολή σας· δεν είναι λειτουργικός ενδεικτικός αριθμός.

Κάντε το αίτημα καταχώρισης στο Postman

1. Δημιουργήστε ένα μικρό περιβάλλον δοκιμής

Στο Postman, δημιουργήστε ένα περιβάλλον με τρεις μεταβλητές: base_url, tracking_token και tracking_number. Ορίστε το base_url στο παραπάνω Base URL και εισαγάγετε το διαπιστευτήριο και τον αριθμό αποστολής σας στις άλλες μεταβλητές. Επιλέξτε αυτό το περιβάλλον πριν στείλετε το αίτημα.

Χρησιμοποιήστε τα διαθέσιμα στοιχεία ελέγχου διαχείρισης μυστικών του Postman για το token και ελέγξτε τι κοινοποιεί ή συγχρονίζει ο χώρος εργασίας σας. Η απόκρυψη μιας τιμής στη διεπαφή δεν υποκαθιστά τον έλεγχο του ποιος μπορεί να έχει πρόσβαση σε αυτήν. Μην εξάγετε συμπληρωμένα διαπιστευτήρια μαζί με μια συλλογή που προορίζεται για συναδέλφους ή δημόσια τεκμηρίωση.

2. Διαμορφώστε τη μέθοδο, το URL και τις κεφαλίδες

Δημιουργήστε ένα αίτημα HTTP, επιλέξτε POST και εισαγάγετε το {{base_url}}/register ως URL. Στην καρτέλα Headers, προσθέστε:

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

Σε αυτό το παράδειγμα, το διαπιστευτήριο ανήκει στην προσαρμοσμένη κεφαλίδα 17token. Μην την αντικαταστήσετε με διαμόρφωση Bearer token μόνο και μόνο επειδή κάποιο άλλο API χρησιμοποίησε αυτό το μοτίβο. Ελέγξτε επίσης αν οι κληρονομημένες ρυθμίσεις συλλογής εισάγουν ακούσια μια κεφαλίδα Authorization.

3. Προσθέστε το σώμα JSON

Ανοίξτε το Body, επιλέξτε raw και, στη συνέχεια, JSON. Εισαγάγετε:

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

Οι εξωτερικές αγκύλες έχουν σημασία: αυτό το αίτημα χρησιμοποιεί πίνακα, παρότι περιέχει μόνο μία αποστολή. Χρησιμοποιήστε διπλά εισαγωγικά, αφαιρέστε τα τελικά κόμματα και μην συμπεριλάβετε σχόλια στο JSON. Αν η τεκμηρίωση απαιτεί πρόσθετες πληροφορίες για τον μεταφορέα ή την αποστολή σας, προσθέστε τα τεκμηριωμένα πεδία πριν από την αποστολή.

4. Στείλτε και ελέγξτε το αποτέλεσμα

Κάντε κλικ στο Send. Αρχικά, ελέγξτε αν λάβατε καθόλου απόκριση HTTP. Μια αποτυχία DNS, ένα σφάλμα TLS, ένα πρόβλημα proxy ή ένα timeout διαφέρει από μια απόκριση που εξηγεί ότι το αίτημα δεν ήταν έγκυρο. Στη συνέχεια, ελέγξτε το σώμα της απόκρισης για το αποτέλεσμα της λειτουργίας και τυχόν πληροφορίες αποδοχής ή απόρριψης σε επίπεδο αποστολής.

Αποθηκεύστε το αίτημα ως «Register test shipment». Καταγράψτε την κατάσταση HTTP, το αποτέλεσμα του API και τυχόν μήνυμα σφάλματος χωρίς να αντιγράψετε το token. Αν η καταχώριση αποτύχει, επιλύστε την αποτυχία πριν συνεχίσετε. Η επανειλημμένη υποβολή ενός αμετάβλητου αιτήματος δυσκολεύει τη διάγνωση και μπορεί να καταναλώσει πόρους του λογαριασμού.

Αναπαραγάγετε το αίτημα με curl

Οι παρακάτω εντολές χρησιμοποιούν κέλυφος τύπου POSIX, όπως Bash ή Zsh. Τα PowerShell και Windows Command Prompt έχουν διαφορετικούς κανόνες για εισαγωγικά και μεταβλητές. Στο PowerShell, χρησιμοποιήστε curl.exe όταν είναι απαραίτητο, ώστε να καλέσετε το εκτελέσιμο curl αντί για ένα ψευδώνυμο εντολής ειδικό για το κέλυφος.

Ορίστε το Base URL και φορτώστε το διαπιστευτήριό σας σε μια μεταβλητή περιβάλλοντος μέσω της συνήθους ροής διαχείρισης μυστικών:

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

Μια μεταβλητή περιβάλλοντος διατηρεί το διαπιστευτήριο εκτός του επαναχρησιμοποιήσιμου παραδείγματος, αλλά δεν αποτελεί πλήρες σύστημα διαχείρισης μυστικών. Για τοπικές δοκιμές, αποφύγετε την πληκτρολόγηση πραγματικού token σε εντολή που θα διατηρήσει το ιστορικό του κελύφους σας. Για αυτοματοποίηση, χρησιμοποιήστε το αποθετήριο μυστικών της πλατφόρμας σας και περιορίστε την έξοδο καταγραφής.

Δημιουργήστε ένα αρχείο με όνομα shipment.json και αντικαταστήστε το σύμβολο κράτησης θέσης με τον αριθμό παρακολούθησης της δοκιμής σας:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Στείλτε το αίτημα καταχώρισης:

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'

Αυτό αποθηκεύει το σώμα της απόκρισης στο register-response.json και εκτυπώνει ξεχωριστά την κατάσταση HTTP. Τα timeout σύνδεσης και συνολικού χρόνου είναι επιλογές τοπικής δοκιμής, όχι εγγυήσεις της υπηρεσίας 17TRACK. Ανοίξτε το αποθηκευμένο αρχείο για να ελέγξετε το αποτέλεσμα του API· μόνο η γραμμή κατάστασης δεν επαρκεί.

Το curl μπορεί να ολοκληρώσει επιτυχώς μια μεταφορά ακόμη και όταν ο διακομιστής επιστρέφει απόκριση σφάλματος HTTP. Αντίστροφα, μια αποτυχία μεταφοράς μπορεί να εμποδίσει την άφιξη οποιασδήποτε χρήσιμης απόκρισης API. Κατά τη δημιουργία script, χειριστείτε ως ξεχωριστά σήματα την κατάσταση εξόδου του curl, την κατάσταση HTTP και το αποτέλεσμα σε επίπεδο εφαρμογής.

Ζητήστε τις πληροφορίες παρακολούθησης της αποστολής

Αφού επιβεβαιώσετε την καταχώριση, αντιγράψτε το αίτημα στο Postman και αλλάξτε το URL σε {{base_url}}/gettrackinfo. Διατηρήστε τη μέθοδο POST, την κεφαλίδα ελέγχου ταυτότητας, τον τύπο περιεχομένου και το σώμα της αποστολής. Αποθηκεύστε το ξεχωριστά, ώστε να μην καταχωρίσετε κατά λάθος ξανά την αποστολή όταν θέλετε να ανακτήσετε δεδομένα.

Το αντίστοιχο αίτημα curl είναι:

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'

Μην υποθέτετε ότι μια νεοκαταχωρισμένη αποστολή θα επιστρέψει αμέσως πλήρες ιστορικό συμβάντων. Η διαθεσιμότητα των δεδομένων εξαρτάται από την αποστολή και την επεξεργασία της υπηρεσίας. Αν οι πληροφορίες δεν είναι ακόμη διαθέσιμες, ακολουθήστε τις τεκμηριωμένες οδηγίες ανάκτησης και ενημέρωσης αντί να καταχωρίζετε επανειλημμένα τον ίδιο αριθμό ή να εκτελείτε έναν βρόχο συχνής δημοσκόπησης.

Διαβάστε την απόκριση σε τρία επίπεδα

  1. Μεταφορά: συνδέθηκε ο client και έλαβε απόκριση HTTP;
  2. Λειτουργία: αποδέχθηκε το API το αίτημα και ολοκληρώθηκε επιτυχώς η μεμονωμένη αποστολή;
  3. Πληροφορίες αποστολής: τα επιστρεφόμενα δεδομένα προσδιορίζουν το προβλεπόμενο δέμα και τι τεκμηριώνει στην πραγματικότητα η κατάστασή του ή το ιστορικό συμβάντων;

Χρησιμοποιήστε το επίσημο σχήμα απόκρισης για να εντοπίσετε τα πεδία κατάστασης, μεταφορέα και συμβάντων. Διατηρήστε τη διάκριση μεταξύ μιας κανονικοποιημένης κατάστασης αποστολής και της αρχικής περιγραφής συμβάντος του μεταφορέα. Μια επιτυχής αναζήτηση δεν αποτελεί απόδειξη παράδοσης και η απουσία συμβάντων δεν αποτελεί απόδειξη ότι ένα δέμα χάθηκε.

Κατά την αποθήκευση χρονικών σημάνσεων, διατηρήστε τις παρεχόμενες πληροφορίες ζώνης ώρας ή μετατόπισης. Αποφύγετε την ταξινόμηση ακατέργαστων συμβολοσειρών ημερομηνίας από διαφορετικές μορφές και την υπόθεση ότι αντιπροσωπεύουν σωστή χρονολογική σειρά. Διακρίνετε επίσης τον χρόνο κατά τον οποίο η εφαρμογή σας ανέκτησε μια εγγραφή από τον χρόνο κατά τον οποίο συνέβη το συμβάν της αποστολής.

Αντιμετωπίστε προβλήματα χωρίς να αλλάξετε τα πάντα ταυτόχρονα

  • Καμία απόκριση: ελέγξτε το hostname, την πρόσβαση στο δίκτυο, τις ρυθμίσεις proxy, τη διαμόρφωση TLS και το τοπικό timeout. Μην απενεργοποιείτε την επαλήθευση πιστοποιητικών ως λύση ρουτίνας.
  • Αποτυχία ελέγχου ταυτότητας: επιβεβαιώστε ότι το token είναι ενεργό, ότι υπάρχει η κεφαλίδα 17token και ότι το επιλεγμένο περιβάλλον του Postman επιλύει σωστά τη μεταβλητή. Ελέγξτε για ακούσια κενά.
  • Μη έγκυρο αίτημα: επαληθεύστε την έκδοση του API, τη διαδρομή λειτουργίας, τη μέθοδο POST, τον τύπο περιεχομένου και τη δομή του πίνακα JSON σύμφωνα με την τεκμηρίωση.
  • Απόρριψη αποστολής: διαβάστε το σφάλμα που αφορά τη συγκεκριμένη αποστολή. Ελέγξτε τον αριθμό και τυχόν απαιτούμενες πληροφορίες μεταφορέα αντί να αντιμετωπίζετε κάθε απόρριψη ως πρόβλημα ελέγχου ταυτότητας.
  • Καμία ενημέρωση παρακολούθησης: επιβεβαιώστε την καταχώριση και την ταυτότητα της προβλεπόμενης αποστολής. Ελέγξτε αν απαιτούνται πληροφορίες μεταφορέα και αν υπάρχουν διαθέσιμες ενημερώσεις πριν από νέα προσπάθεια.
  • Το Postman λειτουργεί αλλά το curl αποτυγχάνει: συγκρίνετε το URL που επιλύθηκε, τις πραγματικές κεφαλίδες και τα byte του σώματος. Τα εισαγωγικά του κελύφους και οι μη ορισμένες μεταβλητές περιβάλλοντος είναι συνηθισμένα σημεία απόκλισης των αιτημάτων.

Αλλάζετε μία μεταβλητή ανά δοκιμή και κρατάτε σύντομη καταγραφή του αποτελέσματος. Αν ελέγξετε την κονσόλα του Postman ή χρησιμοποιήσετε την αναλυτική έξοδο του curl, αντιμετωπίστε την έξοδο ως ευαίσθητη: οι κεφαλίδες αιτημάτων μπορεί να εκθέσουν διαπιστευτήρια. Αποκρύψτε μυστικά και πληροφορίες πελατών πριν κοινοποιήσετε διαγνωστικά στοιχεία.

Γνωρίστε πότε ολοκληρώνεται ο οδηγός

Έχετε ολοκληρώσει μια ουσιαστική πρώτη δοκιμή ενσωμάτωσης όταν και τα δύο client στέλνουν το προβλεπόμενο αίτημα, η καταχώριση έχει γίνει κατανοητή, η ανάκτηση επιστρέφει ερμηνεύσιμο αποτέλεσμα και μπορείτε να διακρίνετε μια αποτυχία του API από μια αποστολή χωρίς νέες πληροφορίες. Η αντιστοίχιση μόνο των κωδικών κατάστασης HTTP δεν αποδεικνύει ότι τα δύο client συμπεριφέρθηκαν πανομοιότυπα.

Πριν μεταφέρετε τη ροή εργασίας σε μια εφαρμογή, διατηρείτε τα διαπιστευτήρια στον διακομιστή, επικυρώνετε τις εισόδους και χρησιμοποιείτε δομημένο χειρισμό σφαλμάτων. Συμβουλευτείτε τα τεκμηριωμένα όρια ρυθμού, τα όρια παρτίδων, τις οδηγίες επανάληψης και τις επιλογές παράδοσης ενημερώσεων για τον λογαριασμό σας. Μην υποθέτετε ότι η καταχώριση είναι ασφαλές να επαναληφθεί τυφλά μετά από timeout: ο διακομιστής μπορεί να έχει επεξεργαστεί το αίτημα, παρότι ο client σας δεν έλαβε την απόκριση.

Προσθέστε δοκιμές για μη έγκυρο διαπιστευτήριο, κακοσχηματισμένο JSON, μη έγκυρο αριθμό αποστολής, ήδη καταχωρισμένη αποστολή, μη διαθέσιμα δεδομένα παρακολούθησης και timeout δικτύου. Κάθε περίπτωση πρέπει να οδηγεί σε σκόπιμο αποτέλεσμα της εφαρμογής και όχι σε μη χειριζόμενη εξαίρεση ή παραπλανητική κατάσταση που εμφανίζεται στον πελάτη.

Συχνές ερωτήσεις

Μπορώ να δοκιμάσω χωρίς πραγματικό αριθμό παρακολούθησης;

Μπορείτε να δοκιμάσετε ορισμένες συμπεριφορές επικύρωσης αιτημάτων με μια μη έγκυρη τιμή, αλλά αυτό δεν επαληθεύει την παρακολούθηση αποστολής. Για να δοκιμάσετε πραγματικά συμβάντα, χρησιμοποιήστε μια εξουσιοδοτημένη αποστολή ή ένα τεκμηριωμένο test fixture, εφόσον παρέχεται από την υπηρεσία. Μην υποθέτετε ότι τυχαίοι ενδεικτικοί αριθμοί ανήκουν σε sandbox.

Γιατί μια απόκριση HTTP 200 εξακολουθεί να περιέχει αποτυχία;

Η κατάσταση HTTP και τα αποτελέσματα της εφαρμογής περιγράφουν διαφορετικά επίπεδα. Ένας διακομιστής μπορεί να λάβει και να επεξεργαστεί επιτυχώς ένα αίτημα, ενώ αναφέρει ότι μια μεμονωμένη αποστολή απορρίφθηκε. Διαβάστε το σώμα της απόκρισης και το τεκμηριωμένο αποτέλεσμα σε επίπεδο αποστολής, όχι μόνο την κατάσταση HTTP.

Γιατί χρησιμοποιείται POST για την ανάκτηση πληροφοριών παρακολούθησης;

Χρησιμοποιήστε τη μέθοδο που καθορίζεται από το συμβόλαιο του endpoint. Αυτό το παράδειγμα ανάκτησης δέχεται αναγνωριστικά αποστολών σε σώμα αιτήματος JSON μέσω POST. Η αλλαγή του σε GET επειδή η λειτουργία διαβάζει δεδομένα δεν διατηρεί το τεκμηριωμένο αίτημα.

Πρέπει να τοποθετήσω το token API σε JavaScript του browser;

Μην ενσωματώνετε ιδιωτικό διαπιστευτήριο API σε frontend κώδικα που παραδίδεται δημόσια. Δρομολογήστε τα αιτήματα μέσω εξουσιοδοτημένου backend που προστατεύει το διαπιστευτήριο, επικυρώνει τις εισόδους και ελέγχει σε ποιες πληροφορίες αποστολών μπορεί να έχει πρόσβαση κάθε χρήστης.

Χρειάζομαι και Postman και curl για την παραγωγή;

Όχι. Είναι χρήσιμα εργαλεία δοκιμών και διάγνωσης. Η εφαρμογή παραγωγής σας μπορεί να χρησιμοποιεί κατάλληλο HTTP client. Διατηρήστε ένα αποκαθαρμένο αίτημα Postman ή μια εντολή curl ως αναπαραγώγιμη αναφορά, χωρίς ενεργό token ή περιττά δεδομένα πελατών.

Πηγές