UPS Tracking API: Ένας οδηγός για αρχάριους για να ξεκινήσετε
Το UPS Tracking API επιτρέπει σε μια επιχείρηση να ανακτά την κατάσταση αποστολών και να εμφανίζει ενημερώσεις παράδοσης μέσα στον δικό της ιστότοπο, εφαρμογή, σύστημα διαχείρισης παραγγελιών ή εργαλεία εξυπηρέτησης πελατών. Η έναρξη συνήθως περιλαμβάνει τη δημιουργία λογαριασμού προγραμματιστή UPS, την καταχώριση μιας εφαρμογής, την απόκτηση διαπιστευτηρίων ελέγχου ταυτότητας, την αποστολή ενός αιτήματος παρακολούθησης και τη μετατροπή της απόκρισης σε χρήσιμα συμβάντα που εμφανίζονται στους πελάτες. Αυτός ο οδηγός εξηγεί τη διαδικασία χωρίς να προϋποθέτει προηγούμενη εμπειρία με API.
Τα παραδείγματα επικεντρώνονται στην παρακολούθηση και όχι στη δημιουργία ετικετών, την τιμολόγηση ή την επικύρωση διευθύνσεων. Η UPS διατηρεί ξεχωριστά προϊόντα API και τεκμηρίωση, επομένως επιβεβαιώστε ότι η εφαρμογή που καταχωρίζετε έχει πρόσβαση στη δυνατότητα παρακολούθησης που χρειάζεστε πριν δημιουργήσετε ροές εργασίας παραγωγής.
Τι κάνει ένα UPS Tracking API
Ένα API είναι ένας δομημένος τρόπος ώστε ένα σύστημα λογισμικού να ζητά πληροφορίες από ένα άλλο. Σε μια ροή εργασίας παρακολούθησης, το σύστημά σας στέλνει ένα αναγνωριστικό αποστολής, όπως έναν αριθμό παρακολούθησης, σε έναν μεταφορέα ή μια πλατφόρμα παρακολούθησης. Η υπηρεσία επιστρέφει δεδομένα αποστολής που μπορεί να περιλαμβάνουν την τρέχουσα κατάσταση, περιγραφή κατάστασης, πληροφορίες τοποθεσίας, ημερομηνίες και ορόσημα δέματος, ανάλογα με την υπηρεσία, την αποστολή και τα πεδία απόκρισης που είναι διαθέσιμα κατά τη στιγμή του αιτήματος.
Αυτά τα δεδομένα μπορούν να υποστηρίξουν διάφορες πρακτικές λειτουργίες:
- Μια σελίδα παρακολούθησης ενσωματωμένη σε ένα ηλεκτρονικό κατάστημα.
- Ορατότητα αποστολών μέσα σε ένα σύστημα διαχείρισης παραγγελιών ή επιχειρησιακού σχεδιασμού πόρων.
- Οθόνες εξυπηρέτησης πελατών που μειώνουν την ανάγκη χειροκίνητου ελέγχου στον ιστότοπο του μεταφορέα.
- Εσωτερικές ειδοποιήσεις για εξαιρέσεις παράδοσης, καθυστερήσεις ή ολοκληρωμένες παραδόσεις.
- Μηνύματα μετά την αγορά που βασίζονται σε συμβάντα αποστολής.
Το API δεν αντικαθιστά τη λογική της εφαρμογής σας. Εξακολουθείτε να πρέπει να αποφασίσετε πόσο συχνά θα ζητάτε ενημερώσεις, πώς θα αποθηκεύετε τις αποκρίσεις, πώς θα χειρίζεστε ελλιπή δεδομένα και πώς θα εξηγείτε στους πελάτες τις καταστάσεις του μεταφορέα.
UPS Tracking API έναντι του ιστότοπου της UPS
Ο ιστότοπος της UPS έχει σχεδιαστεί για ένα άτομο που εισάγει έναν αριθμό παρακολούθησης και διαβάζει το αποτέλεσμα. Ένα API έχει σχεδιαστεί για λογισμικό. Είναι χρήσιμο όταν οι πληροφορίες παρακολούθησης πρέπει να εμφανίζονται αυτόματα σε άλλο σύστημα ή να ενεργοποιούν μια εσωτερική διαδικασία.
Αυτή η διάκριση έχει σημασία, επειδή μια ενσωμάτωση API εισάγει ευθύνες που δεν έχει μια χειροκίνητη αναζήτηση. Η ομάδα σας πρέπει να προστατεύει τα διαπιστευτήρια, να επικυρώνει τις εισόδους των χρηστών, να καταγράφει κατάλληλα τα αιτήματα και τις αποκρίσεις, να αντιμετωπίζει προσωρινές αποτυχίες και να παρακολουθεί αν η ενσωμάτωση συνεχίζει να λειτουργεί μετά από αλλαγές στην πλατφόρμα του μεταφορέα.
Η πλατφόρμα προγραμματιστών της UPS είναι το κατάλληλο σημείο εκκίνησης για τις τρέχουσες απαιτήσεις εγγραφής και τεχνικής υλοποίησης. Η τεκμηρίωσή της θα πρέπει να έχει προτεραιότητα έναντι παλαιότερων οδηγών, δειγμάτων κώδικα ή αναρτήσεων σε φόρουμ, επειδή οι μέθοδοι ελέγχου ταυτότητας, οι εκδόσεις API, οι απαιτούμενες κεφαλίδες και οι κανόνες πρόσβασης προϊόντων μπορεί να αλλάξουν.
Τι χρειάζεστε πριν υποβάλετε ένα αίτημα
Προετοιμάστε τα ακόλουθα στοιχεία πριν γράψετε την ενσωμάτωση:
- Έναν λογαριασμό προγραμματιστή UPS. Χρησιμοποιήστε την επίσημη πύλη UPS Developer Portal για να ελέγξετε τα διαθέσιμα API και να δημιουργήσετε μια εφαρμογή.
- Διαπιστευτήρια εφαρμογής. Οι ακριβείς ονομασίες των διαπιστευτηρίων και η ροή ελέγχου ταυτότητας θα πρέπει να λαμβάνονται από την τρέχουσα τεκμηρίωση της UPS. Μην τοποθετείτε μυστικά πελάτη σε κώδικα προγράμματος περιήγησης, εφαρμογές για κινητές συσκευές, δημόσια αποθετήρια ή σελίδες ορατές στους πελάτες.
- Έναν έγκυρο αριθμό παρακολούθησης για δοκιμές. Κάντε δοκιμές με αποστολές στις οποίες ο οργανισμός σας έχει εξουσιοδοτημένη πρόσβαση και αποφύγετε την έκθεση προσωπικών ή εμπορικών δεδομένων αποστολών στα αρχεία καταγραφής.
- Ένα σημείο ενσωμάτωσης στην πλευρά του διακομιστή. Μια υπηρεσία backend είναι συνήθως ασφαλέστερη από την απευθείας κλήση του μεταφορέα από μια δημόσια ιστοσελίδα, επειδή μπορεί να διατηρεί ιδιωτικά τα διαπιστευτήρια και να ελέγχει τον όγκο των αιτημάτων.
- Ένα σχέδιο αποθήκευσης αποκρίσεων. Αποφασίστε ποια πεδία χρειάζεστε, για πόσο διάστημα θα τα διατηρείτε και πώς θα συσχετίζετε ένα συμβάν μεταφορέα με μια εσωτερική παραγγελία.
Μια φιλική προς αρχάριους ροή εργασίας ενσωμάτωσης
1. Επιβεβαιώστε την επιχειρηματική απαίτηση
Αρχικά ορίστε τι σημαίνει «παρακολούθηση» στο προϊόν σας. Μια σελίδα που απευθύνεται σε πελάτες μπορεί να χρειάζεται μόνο την τρέχουσα κατάσταση και πληροφορίες για την αναμενόμενη παράδοση. Ένας πίνακας ελέγχου αποθήκης ή υποστήριξης μπορεί επίσης να χρειάζεται ιστορικό σαρώσεων, χρονικές σημάνσεις, περιγραφές εξαιρέσεων και τον αρχικό αριθμό παρακολούθησης.
Αποφύγετε να ζητάτε κάθε διαθέσιμο πεδίο χωρίς λόγο. Ένα μικρότερο μοντέλο δεδομένων είναι ευκολότερο στη συντήρηση και λιγότερο πιθανό να εκθέσει πληροφορίες που δεν χρειάζονται οι χρήστες σας.
2. Καταχωρίστε την εφαρμογή
Δημιουργήστε μια εφαρμογή στο περιβάλλον προγραμματιστών της UPS και επιλέξτε το σχετικό προϊόν παρακολούθησης σύμφωνα με τις τρέχουσες οδηγίες της πύλης. Καταγράψτε με ασφάλεια το αναγνωριστικό της εφαρμογής. Αν η UPS απαιτεί έγκριση, συσχέτιση λογαριασμού ή πρόσθετη ρύθμιση για πρόσβαση παραγωγής, ολοκληρώστε αυτά τα βήματα πριν υποσχεθείτε ημερομηνία ζωντανής έναρξης.
Διατηρείτε ξεχωριστά διαπιστευτήρια και ρυθμίσεις για δοκιμές και παραγωγή, όπου η πλατφόρμα υποστηρίζει αυτό το μοντέλο. Έτσι μειώνεται η πιθανότητα ένα δοκιμαστικό σενάριο να επηρεάσει μια ζωντανή ροή εργασίας.
3. Υλοποιήστε τον έλεγχο ταυτότητας
Ο έλεγχος ταυτότητας αποδεικνύει ότι η εφαρμογή σας επιτρέπεται να καλεί την υπηρεσία. Ακολουθήστε τη μέθοδο ελέγχου ταυτότητας, το endpoint διακριτικών, τις απαιτήσεις scope και τη μορφή κεφαλίδων που εμφανίζονται στην τρέχουσα τεκμηρίωση της UPS. Αντιμετωπίζετε τα access token ως προσωρινά μυστικά και μην τα γράφετε στα αρχεία καταγραφής της εφαρμογής.
Μια λογική υλοποίηση ζητά διακριτικό μόνο όταν χρειάζεται, το επαναχρησιμοποιεί για την επιτρεπόμενη διάρκεια ζωής του και λαμβάνει νέο μετά τη λήξη του. Ο κώδικάς σας θα πρέπει επίσης να διακρίνει μια αποτυχία ελέγχου ταυτότητας από ένα σφάλμα αριθμού παρακολούθησης. Η αντιμετώπιση είναι διαφορετική: το πρώτο απαιτεί έλεγχο διαπιστευτηρίων ή ρυθμίσεων, ενώ το δεύτερο μπορεί να απαιτεί επικύρωση εισόδου.
4. Στείλτε ένα αίτημα παρακολούθησης
Μετά τον έλεγχο ταυτότητας, στείλτε ένα αίτημα χρησιμοποιώντας τη λειτουργία παρακολούθησης και τη μορφή αναγνωριστικού που καθορίζει η UPS. Η ακριβής URL, η μέθοδος HTTP, οι κεφαλίδες και το σχήμα απόκρισης περιγράφονται στην επίσημη τεκμηρίωση της έκδοσης API που θα επιλέξετε.
Ένα εννοιολογικό αίτημα μοιάζει ως εξής:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Αυτό είναι ένα εκπαιδευτικό παράδειγμα και όχι αίτημα παραγωγής για αντιγραφή και επικόλληση. Αντικαταστήστε το όνομα λειτουργίας, το endpoint, τις κεφαλίδες και το σώμα με τις τιμές που περιλαμβάνονται στην τρέχουσα αναφορά API της UPS. Ορισμένα API χρησιμοποιούν παράμετρο διαδρομής ή διαφορετική δομή αιτήματος.
5. Κανονικοποιήστε την απόκριση
Οι αποκρίσεις των μεταφορέων δεν είναι πάντα γραμμένες στη γλώσσα που περιμένουν οι πελάτες σας. Δημιουργήστε ένα εσωτερικό μοντέλο συμβάντων με σταθερά πεδία όπως:
- Εσωτερικό αναγνωριστικό παραγγελίας ή αποστολής.
- Όνομα μεταφορέα και αριθμός παρακολούθησης.
- Τελευταίος κωδικός κατάστασης του μεταφορέα και ακατέργαστη περιγραφή.
- Μια κανονικοποιημένη κατάσταση που χρησιμοποιείται από την εφαρμογή σας.
- Χρονική σήμανση συμβάντος και, όταν παρέχεται, τοποθεσία.
- Ώρα τελευταίας επιτυχούς ενημέρωσης.
Διατηρείτε την αρχική κατάσταση του μεταφορέα όπου είναι δυνατόν. Μια κανονικοποιημένη ετικέτα όπως «Σε μεταφορά» είναι χρήσιμη για μια διεπαφή πελάτη, αλλά η ακατέργαστη περιγραφή μπορεί να βοηθήσει το προσωπικό υποστήριξης να διερευνήσει ένα ασυνήθιστο συμβάν.
6. Αποφασίστε πώς θα ανακτώνται οι ενημερώσεις
Ορισμένα συστήματα χρησιμοποιούν προγραμματισμένη δημοσκόπηση: ένα backend ελέγχει τις επιλέξιμες αποστολές σε επιλεγμένα διαστήματα και αποθηκεύει τις αλλαγές. Άλλα χρησιμοποιούν ειδοποιήσεις συμβάντων όταν τις υποστηρίζει η σχετική πλατφόρμα. Μην υποθέτετε ότι κάθε προϊόν παρακολούθησης της UPS προσφέρει τον ίδιο μηχανισμό ειδοποιήσεων. Επιβεβαιώστε την τρέχουσα τεκμηρίωση και τους εμπορικούς όρους πριν σχεδιάσετε μια ροή εργασίας βασισμένη σε webhook.
Η δημοσκόπηση θα πρέπει να είναι επιλεκτική. Τα δέματα που στάλθηκαν πρόσφατα ή βρίσκονται ενεργά σε μετακίνηση μπορεί να δικαιολογούν συχνότερους ελέγχους από τις παραδοθείσες ή ακυρωμένες αποστολές. Εφαρμόστε επαναλήψεις με backoff για προσωρινές αποτυχίες, τηρήστε τα τεκμηριωμένα όρια και σταματήστε τα περιττά αιτήματα μετά από μια τελική κατάσταση, εκτός αν η επιχειρηματική διαδικασία απαιτεί μεταγενέστερη επαλήθευση.
Συνηθισμένα σφάλματα και τρόπος αντιμετώπισής τους
| Κατάσταση | Πιθανή απόκριση | Πρακτική ενέργεια |
|---|---|---|
| Αποτυχία ελέγχου ταυτότητας | Το αίτημα δεν είναι εξουσιοδοτημένο. | Ελέγξτε τα διαπιστευτήρια, τον χειρισμό διακριτικών, τα scope, το περιβάλλον και τις απαιτούμενες κεφαλίδες. |
| Μη έγκυρη είσοδος παρακολούθησης | Το αναγνωριστικό λείπει, έχει λανθασμένη μορφή ή δεν γίνεται αποδεκτό. | Επικυρώστε την είσοδο και εμφανίστε σαφές μήνυμα διόρθωσης. |
| Δεν υπάρχει ακόμη χρήσιμο συμβάν | Μια αποστολή μπορεί να μην έχει λάβει την πρώτη της σάρωση. | Μην δηλώσετε αποτυχία παράδοσης· εμφανίστε ουδέτερο μήνυμα εκκρεμότητας και δοκιμάστε ξανά αργότερα. |
| Απόκριση ορίου ρυθμού ή ποσόστωσης | Η εφαρμογή στέλνει αιτήματα πολύ γρήγορα ή έχει φτάσει το επιτρεπόμενο όριο. | Μειώστε τη δημοσκόπηση, τοποθετήστε την εργασία σε ουρά και ακολουθήστε τις οδηγίες του παρόχου. |
| Προσωρινό σφάλμα διακομιστή ή δικτύου | Η υπηρεσία μπορεί να μην είναι προσωρινά διαθέσιμη. | Δοκιμάστε ξανά με ασφάλεια και backoff και διατηρήστε την τελευταία γνωστή κατάσταση. |
Ο σημαντικότερος κανόνας για την εμπειρία χρήστη είναι να μην μετατρέπετε τα δεδομένα που λείπουν σε βέβαιο συμπέρασμα. «Δεν υπάρχει νέα σάρωση» δεν σημαίνει αυτόματα «χάθηκε» και «δημιουργήθηκε ετικέτα» δεν σημαίνει απαραίτητα «σε μεταφορά». Αντιστοιχίστε προσεκτικά τις καταστάσεις και διατηρήστε ορατό τον χειρισμό εξαιρέσεων για τις ομάδες υποστήριξης.
Πότε ένα API πολλαπλών μεταφορέων είναι καταλληλότερο
Μια άμεση ενσωμάτωση με την UPS μπορεί να είναι λογική επιλογή όταν οι αποστολές σας εξυπηρετούνται κυρίως από την UPS και η ομάδα σας θέλει άμεσο έλεγχο της σύνδεσης με τον μεταφορέα. Το αντάλλαγμα είναι ότι κάθε πρόσθετος μεταφορέας μπορεί να απαιτεί διαφορετικό μοντέλο ελέγχου ταυτότητας, σχήμα δεδομένων, πολιτική σφαλμάτων και διαδικασία συντήρησης.
Αν η λειτουργία σας χρησιμοποιεί πολλούς μεταφορείς, μια υπηρεσία πολλαπλών μεταφορέων μπορεί να μειώσει τον αριθμό των ξεχωριστών ενσωματώσεων. Το Tracking API της 17TRACK έχει σχεδιαστεί για παρακολούθηση αποστολών βάσει εφαρμογών και η επίσημη τεκμηρίωση προγραμματιστών εξηγεί το διαθέσιμο μοντέλο ενσωμάτωσης. Αξίζει να αξιολογηθεί όταν η πραγματική απαίτηση δεν είναι μόνο η παρακολούθηση UPS, αλλά ένα συνεπές επίπεδο παρακολούθησης μεταξύ μεταφορέων.
Αυτό δεν αποτελεί λόγο για αυτόματη αντικατάσταση μιας άμεσης σύνδεσης με την UPS. Συγκρίνετε την κάλυψη μεταφορέων που χρειάζεστε, τη λεπτομέρεια συμβάντων, τις απαιτήσεις διατήρησης δεδομένων, το μοντέλο ελέγχου ταυτότητας, τα λειτουργικά όρια, τη διαδικασία υποστήριξης και τη συνολική προσπάθεια υλοποίησης. Η δημόσια τεκμηρίωση ενός παρόχου θα πρέπει να θεωρείται αφετηρία για μια τεχνική απόδειξη ιδέας και όχι υποκατάστατο της δοκιμής των δικών σας μοτίβων αποστολών.
Λίστα ελέγχου ετοιμότητας παραγωγής
- Τα διαπιστευτήρια αποθηκεύονται σε διαχειριστή μυστικών και δεν εκτίθενται ποτέ στο πρόγραμμα περιήγησης.
- Τα περιβάλλοντα δοκιμών και παραγωγής είναι σαφώς διαχωρισμένα.
- Τα αιτήματα έχουν χρονικά όρια, ελεγχόμενες επαναλήψεις και χρήσιμη καταγραφή σφαλμάτων.
- Οι αριθμοί παρακολούθησης επικυρώνονται πριν σταλούν.
- Το σύστημα αποθηκεύει την τελευταία επιτυχή ενημέρωση και αποφεύγει την αντικατάστασή της με κενή απόκριση.
- Τα ακατέργαστα μηνύματα του μεταφορέα και οι ετικέτες που εμφανίζονται στους πελάτες υποβάλλονται σε ξεχωριστή διαχείριση.
- Η συχνότητα δημοσκόπησης ακολουθεί τα δημοσιευμένα όρια του παρόχου και τις λειτουργικές σας ανάγκες.
- Η παρακολούθηση μπορεί να εντοπίζει αποτυχίες ελέγχου ταυτότητας, αυξημένα ποσοστά σφαλμάτων και παρωχημένες αποστολές.
- Το προσωπικό υποστήριξης μπορεί να δει αρκετές λεπτομέρειες για να διερευνήσει μια ερώτηση πελάτη.
- Η ενσωμάτωση επανελέγχεται όταν η UPS αλλάζει την τεκμηρίωση, τα διαπιστευτήρια, τα endpoints ή τα πεδία απόκρισης.
Ξεκινήστε με μία ολοκληρωμένη διαδρομή: έλεγχος ταυτότητας, παρακολούθηση μίας δοκιμαστικής αποστολής, αποθήκευση της απόκρισης, εμφάνιση μιας απλής κατάστασης και χειρισμός αποτυχίας. Επεκταθείτε μόνο αφού αυτή η διαδρομή είναι αξιόπιστη. Αυτή η προσέγγιση είναι συνήθως ασφαλέστερη από τη δημιουργία μιας μεγάλης εμπειρίας παρακολούθησης για πελάτες πριν κατανοηθούν τα υποκείμενα δεδομένα και η συμπεριφορά σφαλμάτων.
Συχνές ερωτήσεις
Χρειάζομαι API αν παρακολουθώ μόνο λίγα δέματα;
Συνήθως όχι. Η χειροκίνητη παρακολούθηση στον ιστότοπο του μεταφορέα μπορεί να είναι πιο πρακτική για περιστασιακές αναζητήσεις. Ένα API γίνεται πιο πολύτιμο όταν η παρακολούθηση αποτελεί μέρος μιας επαναλαμβανόμενης ροής εργασίας ή πρέπει να εμφανίζεται μέσα σε άλλη εφαρμογή.
Μπορώ να καλέσω το UPS Tracking API από ένα θέμα Shopify ή ένα πρόγραμμα περιήγησης;
Μια απευθείας κλήση από το πρόγραμμα περιήγησης μπορεί να εκθέσει διαπιστευτήρια και να δυσκολέψει τον έλεγχο των αιτημάτων. Μια υπηρεσία στην πλευρά του διακομιστή ή μια καθιερωμένη ενσωμάτωση παρακολούθησης είναι γενικά ασφαλέστερη. Επιβεβαιώστε τις τεχνικές απαιτήσεις και την επιτρεπόμενη αρχιτεκτονική στην τρέχουσα τεκμηρίωση της UPS.
Δημιουργεί ένα API παρακολούθησης ετικέτες αποστολής;
Όχι απαραίτητα. Η παρακολούθηση, η δημιουργία ετικετών, η τιμολόγηση, η επικύρωση διευθύνσεων και άλλες λειτουργίες logistics μπορεί να αποτελούν ξεχωριστά προϊόντα API. Επιλέξτε το προϊόν που αντιστοιχεί στη λειτουργία που χρειάζεστε.
Γιατί ένας έγκυρος αριθμός παρακολούθησης μπορεί να επιστρέφει λίγες πληροφορίες;
Ένα δέμα μπορεί να μην έχει λάβει την πρώτη του σάρωση, τα δεδομένα μπορεί να μην είναι ακόμη διαθέσιμα ή το αίτημα μπορεί να μην αντιστοιχεί στην απαιτούμενη μορφή ή στα δικαιώματα πρόσβασης του API. Αντιμετωπίστε μια κενή ή περιορισμένη απόκριση ως κατάσταση προς διερεύνηση και όχι ως απόδειξη ότι η αποστολή χάθηκε.
Να επιλέξω απευθείας την UPS ή ένα API παρακολούθησης πολλαπλών μεταφορέων;
Επιλέξτε άμεση σύνδεση όταν η UPS είναι ο κύριος μεταφορέας και θέλετε μια εστιασμένη ενσωμάτωση. Εξετάστε μια υπηρεσία πολλαπλών μεταφορέων όταν ο λειτουργικός σας στόχος είναι μία ροή παρακολούθησης για αρκετούς μεταφορείς. Δοκιμάστε τους απαιτούμενους μεταφορείς και τα σενάρια συμβάντων πριν λάβετε την τελική απόφαση.
