Ροή εργασιών του API παρακολούθησης αποστολών: από την καταχώριση μιας αποστολής έως την ανάκτηση των στοιχείων παρακολούθησης
A workflow API παρακολούθησης αποστολών ξεκινά με την υποβολή ενός αριθμού παρακολούθησης και τυχόν απαιτούμενων στοιχείων μεταφορέα, τον έλεγχο του αν η εγγραφή ολοκληρώθηκε επιτυχώς, την αναμονή μέχρι να γίνουν διαθέσιμα τα δεδομένα παρακολούθησης και την ανάκτηση της κατάστασης και του ιστορικού συμβάντων της αποστολής. Για μια ενσωμάτωση σε περιβάλλον παραγωγής, οι προγραμματιστές πρέπει επίσης να συνδέουν κάθε εγγραφή παρακολούθησης με μια παραγγελία, να διαχειρίζονται μερικές αποτυχίες, να επεξεργάζονται με ασφάλεια τις ενημερώσεις και να διακρίνουν μια αποδεκτή εγγραφή από μια πραγματική σάρωση από τον μεταφορέα.
Αυτός ο οδηγός εξηγεί τη συγκεκριμένη ροή εργασίας για προγραμματιστές που συνδέουν μια πλατφόρμα ecommerce, ένα σύστημα διαχείρισης παραγγελιών, μια εφαρμογή αποθήκης ή ένα εργαλείο εξυπηρέτησης πελατών. Διαχωρίζει τις συστάσεις σχεδιασμού της εφαρμογής από τις απαιτήσεις API που αφορούν συγκεκριμένους παρόχους. Για μια ενσωμάτωση 17TRACK, χρησιμοποιήστε την επίσημη τεκμηρίωση API για να επιβεβαιώσετε το σχήμα αιτήματος, τον έλεγχο ταυτότητας, τις υποστηριζόμενες λειτουργίες και τα πεδία απόκρισης πριν υλοποιήσετε τα παρακάτω παραδείγματα.
Κατανοήστε τι κάνει — και τι δεν κάνει — η εγγραφή
Η εγγραφή μιας αποστολής σε μια υπηρεσία παρακολούθησης σημαίνει την υποβολή ενός αναγνωριστικού, ώστε η υπηρεσία να μπορεί να παρακολουθεί ή να διαχειρίζεται την αποστολή σύμφωνα με το συμβόλαιο API της. Δεν αποτελεί την ίδια λειτουργία με την αγορά ταχυδρομικών τελών, τη δημιουργία ετικέτας αποστολής, τον προγραμματισμό παραλαβής ή την παράδοση ενός δέματος σε μεταφορέα.
Διατηρήστε ξεχωριστά τα ακόλουθα τρία αποτελέσματα στην εφαρμογή σας:
- Το αίτημα παραλήφθηκε: Το API επέστρεψε απόκριση στο HTTP αίτημά σας.
- Η εγγραφή έγινε αποδεκτή: Η υπηρεσία αποδέχθηκε τη συγκεκριμένη εγγραφή παρακολούθησης για επεξεργασία.
- Οι πληροφορίες παρακολούθησης είναι διαθέσιμες: Η υπηρεσία διαθέτει πληροφορίες αποστολής που η εφαρμογή σας μπορεί να ανακτήσει ή να λάβει.
Αυτά τα αποτελέσματα δεν πρέπει να συγχωνεύονται σε μία μόνο σημαία «επιτυχίας». Ένας αποδεκτός αριθμός παρακολούθησης μπορεί να μην έχει ακόμη συμβάντα από τον μεταφορέα. Αντίστοιχα, μια επιτυχημένη HTTP απόκριση για ένα ομαδικό αίτημα δεν αποδεικνύει ότι έγινε αποδεκτό κάθε στοιχείο της ομάδας· εξετάστε τη δομή αποτελέσματος σε επίπεδο εφαρμογής που ορίζει ο πάροχος.
1. Προετοιμάστε την ταυτότητα της αποστολής και τη διαμόρφωση API
Πριν υποβάλετε ένα αίτημα εγγραφής, αποφασίστε πώς θα αναγνωρίζεται μια αποστολή στο δικό σας σύστημα. Ένα αναγνωριστικό παραγγελίας από μόνο του συνήθως δεν επαρκεί, επειδή μία παραγγελία μπορεί να χωριστεί σε πολλά δέματα. Δώστε σε κάθε αποστολή ή δέμα τη δική του εσωτερική εγγραφή και συσχετίστε την με τη σχετική παραγγελία.
Μια χρήσιμη εσωτερική εγγραφή περιλαμβάνει τις ακόλουθες πληροφορίες. Πρόκειται για προτεινόμενα πεδία εφαρμογής και όχι για σχήμα αιτήματος 17TRACK.
- Εσωτερικό ID αποστολής: Το σταθερό αναγνωριστικό σας για το δέμα.
- Αναφορά παραγγελίας: Η παραγγελία ή η εγγραφή εκτέλεσης παραγγελίας στην οποία ανήκει.
- Αριθμός παρακολούθησης: Το αναγνωριστικό που εξέδωσε ο μεταφορέας, αποθηκευμένο ως κείμενο ώστε να διατηρούνται τα αρχικά μηδενικά.
- Στοιχεία μεταφορέα: Η ταυτότητα του μεταφορέα που παρέχεται από το σύστημα εκτέλεσης παραγγελιών, εφόσον είναι γνωστή.
- Αναφορά παρόχου: Οποιοδήποτε αναγνωριστικό επιστρέφει η υπηρεσία παρακολούθησης και απαιτείται για μεταγενέστερες λειτουργίες.
- Κατάσταση εγγραφής: Η καταγραφή σας για το αν η υποβολή εκκρεμεί, έγινε αποδεκτή, απορρίφθηκε ή αναμένει συμφωνία.
- Κατάσταση παρακολούθησης: Η πιο πρόσφατη κατάσταση αποστολής, η οποία διατηρείται ξεχωριστά από την κατάσταση εγγραφής.
Επικυρώστε τα δεδομένα εισόδου πριν από την υποβολή. Αφαιρέστε τυχόν ακούσια κενά γύρω από την τιμή, αλλά μην επανεγγράφετε τον αριθμό παρακολούθησης με βάση υποθέσεις για τη μορφή του μεταφορέα. Διατηρήστε την αρχική τιμή για την αντιμετώπιση προβλημάτων. Αν ο μεταφορέας είναι γνωστός, αντιστοιχίστε τον στο τεκμηριωμένο αναγνωριστικό μεταφορέα του παρόχου αντί να στείλετε ένα ανεπίσημο εμφανιζόμενο όνομα.
Διαμορφώστε τον έλεγχο ταυτότητας στην πλευρά του διακομιστή. Διατηρήστε τα διαπιστευτήρια εκτός του ελέγχου πηγαίου κώδικα, διαχωρίστε τη διαμόρφωση ανάπτυξης από εκείνη της παραγωγής και αποκρύψτε τα μυστικά από τα αρχεία καταγραφής. Επιβεβαιώστε την τεκμηριωμένη έκδοση API, τα όρια αιτημάτων, τα όρια ομαδικών αιτημάτων και τις απαιτήσεις λογαριασμού αντί να δανειστείτε τιμές από μια άσχετη ενσωμάτωση.
2. Καταχωρίστε την αποστολή και καταγράψτε το αποτέλεσμα σε επίπεδο στοιχείου
Υποβάλετε την εγγραφή παρακολούθησης χρησιμοποιώντας τη λειτουργία εγγραφής που περιγράφεται στην τεκμηρίωση του παρόχου σας. Συμπεριλάβετε μόνο τα απαιτούμενα πεδία και τις προαιρετικές πληροφορίες που εξυπηρετούν έναν σαφή σκοπό. Αποφύγετε την αποστολή ονομάτων πελατών, διευθύνσεων ή άλλων προσωπικών δεδομένων απλώς επειδή είναι διαθέσιμα στη βάση δεδομένων παραγγελιών σας.
Ο ακόλουθος ψευδοκώδικας παρουσιάζει τη σειρά ενεργειών της εφαρμογής. Τα ονόματα των συναρτήσεων είναι ενδεικτικά· δεν αποτελούν endpoints API ή μεθόδους SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Αποθηκεύστε αρκετές πληροφορίες ώστε να εξηγείται τι συνέβη: το εσωτερικό ID αποστολής, την ώρα υποβολής, τον αριθμό προσπάθειας, το αποτέλεσμα σε επίπεδο στοιχείου και οποιαδήποτε αναφορά αιτήματος του παρόχου. Μην βασίζεστε αποκλειστικά σε ένα προσωρινό αρχείο καταγραφής worker. Οι ομάδες εξυπηρέτησης πελατών και λειτουργίας χρειάζονται μια μόνιμη απάντηση για το αν μια αποστολή εγγράφηκε επιτυχώς.
Διαχειριστείτε μεμονωμένα τις ομαδικές υποβολές
Αν το API υποστηρίζει ομαδική εγγραφή, συσχετίστε κάθε επιστρεφόμενο στοιχείο με την αρχική αποστολή του. Μην επισημαίνετε ολόκληρη την ομάδα ως αποδεκτή επειδή το HTTP αίτημα ολοκληρώθηκε επιτυχώς. Αποθηκεύστε τα αποδεκτά στοιχεία, απομονώστε τα απορριφθέντα και εξετάστε ξεχωριστά τα ασαφή αποτελέσματα.
Έτσι αποτρέπεται η άσκοπη επανάληψη προσπαθειών για εγγραφές που έχουν ήδη ολοκληρωθεί, όταν ένας μη έγκυρος αριθμός παρακολούθησης προκαλεί αποτυχία. Παράλληλα, παρέχεται στο προσωπικό λειτουργίας μια αξιοποιήσιμη λίστα εγγραφών που απαιτούν διόρθωση.
Αντιμετωπίστε τα timeouts ως άγνωστο αποτέλεσμα
Ένα timeout δεν αποδεικνύει ότι η εγγραφή απέτυχε. Ο πάροχος μπορεί να αποδέχθηκε το αίτημα πριν διακοπεί η σύνδεσή σας. Χρησιμοποιήστε την τεκμηριωμένη συμπεριφορά idempotency, τη διαχείριση διπλοτύπων ή λειτουργίες αναζήτησης για να συμφωνήσετε το αποτέλεσμα πριν από μια τυφλή επανυποβολή.
Όταν η συμπεριφορά του παρόχου για τα διπλότυπα δεν είναι σαφής, δοκιμάστε την με ελεγχόμενες εγγραφές και επιβεβαιώστε το συμβόλαιο πριν ενεργοποιήσετε τις αυτόματες επαναλήψεις. Η εσωτερική αποδιπλοποίηση των εργασιών εγγραφής παραμένει χρήσιμη, αλλά δεν αντικαθιστά την κατανόηση του τρόπου με τον οποίο η απομακρυσμένη υπηρεσία διαχειρίζεται τα επαναλαμβανόμενα αιτήματα.
3. Αφήστε χρόνο για να φτάσουν οι πρώτες πληροφορίες παρακολούθησης
Μετά την αποδοχή της εγγραφής, οι λεπτομέρειες παρακολούθησης μπορεί να μην είναι άμεσα διαθέσιμες. Μια ετικέτα μπορεί να υπάρχει πριν ο μεταφορέας καταγράψει ένα συμβάν φυσικής διακίνησης. Η απουσία πληροφοριών μπορεί επίσης να απαιτεί έλεγχο του αριθμού παρακολούθησης, της επιλογής μεταφορέα ή των απαιτήσεων αναζήτησης για τη συγκεκριμένη αποστολή.
Αναπαραστήστε ρητά αυτή την κατάσταση. Το «Εγγεγραμμένο· αναμονή πληροφοριών παρακολούθησης» είναι ακριβέστερο από το «Σε μεταφορά» ή το «Η εγγραφή απέτυχε». Μην επινοείτε εκτίμηση παράδοσης ή συμβάν κίνησης για να γεμίσετε μια κενή διεπαφή.
Όταν μια εγγραφή παραμένει κενή, διερευνήστε με πρακτική σειρά:
- Επιβεβαιώστε ότι η μεμονωμένη εγγραφή έγινε αποδεκτή.
- Συγκρίνετε τον υποβληθέντα αριθμό παρακολούθησης με την εγγραφή εκτέλεσης παραγγελίας.
- Ελέγξτε την αντιστοίχιση μεταφορέα και τυχόν τεκμηριωμένες πρόσθετες απαιτήσεις αναζήτησης.
- Ελέγξτε τη δική σελίδα παρακολούθησης του μεταφορέα για την ίδια αποστολή.
- Αν ο μεταφορέας έχει συμβάντα αλλά η ενσωμάτωσή σας όχι, εξετάστε τις αποκρίσεις ανάκτησης και επικοινωνήστε με τον πάροχο API παρέχοντας διαγνωστικές πληροφορίες χωρίς ευαίσθητα δεδομένα.
Αποφύγετε την υιοθέτηση μιας καθολικής περιόδου αναμονής χωρίς τεκμηρίωση. Οι κανόνες κλιμάκωσης πρέπει να αντικατοπτρίζουν την υπηρεσία αποστολής, την αναμενόμενη διαδικασία παράδοσης στον μεταφορέα και τις δικές σας λειτουργικές δεσμεύσεις.
4. Ανακτήστε τις λεπτομέρειες παρακολούθησης και ερμηνεύστε τις σωστά
Μόλις η εγγραφή γίνει διαθέσιμη, καλέστε την τεκμηριωμένη λειτουργία λεπτομερειών παρακολούθησης χρησιμοποιώντας τα απαιτούμενα αναγνωριστικά. Μην θεωρείτε ότι η εγγραφή και η ανάκτηση δέχονται πανομοιότυπα πεδία. Ορισμένα συμβόλαια API διακρίνουν τους αριθμούς παρακολούθησης, τα αναγνωριστικά μεταφορέων και τις αναφορές εγγραφών που δημιουργεί ο πάροχος.
Η εφαρμογή σας πρέπει να διακρίνει τρία επίπεδα πληροφοριών:
- Σύνοψη αποστολής: Η συνολική κατάσταση που χρησιμοποιείται σε πίνακες ελέγχου, σελίδες παραγγελιών και λειτουργικά φίλτρα.
- Ιστορικό συμβάντων: Οι μεμονωμένες παρατηρήσεις, συμπεριλαμβανομένων των περιγραφών, των χρονικών σημάνσεων και των τοποθεσιών όταν παρέχονται.
- Μεταδεδομένα ανάκτησης: Πότε η εφαρμογή σας έλαβε ή ανέκτησε τις πληροφορίες και αν το αίτημα ολοκληρώθηκε επιτυχώς.
Μια επιτυχημένη αναζήτηση σημαίνει ότι η λειτουργία ανάκτησης ολοκληρώθηκε επιτυχώς. Δεν σημαίνει ότι το δέμα κινήθηκε από την προηγούμενη αναζήτηση. Συγκρίνετε τις επιστρεφόμενες πληροφορίες παρακολούθησης με την αποθηκευμένη εγγραφή πριν δημιουργήσετε ειδοποίηση ή επόμενη ροή εργασίας.
Διατηρήστε χωριστά τον χρόνο συμβάντος και τον χρόνο ανάκτησης
Αποθηκεύστε ξεχωριστά την ώρα που σχετίζεται με ένα συμβάν του μεταφορέα και την ώρα που το έλαβε το σύστημά σας. Ένα συμβάν που ανακτήθηκε σήμερα το απόγευμα μπορεί να περιγράφει μια παλαιότερη σάρωση. Η αντικατάσταση της ώρας του συμβάντος με την ώρα ανάκτησης θα έκανε μια παλιά ενημέρωση να φαίνεται σαν νέα φυσική κίνηση.
Διατηρήστε την αρχική χρονική σήμανση και οποιαδήποτε παρεχόμενη μετατόπιση ζώνης ώρας. Κανονικοποιείτε τις χρονικές σημάνσεις για σύγκριση μόνο όταν η ζώνη ώρας είναι γνωστή. Αν ένα συμβάν δεν περιέχει πληροφορίες ζώνης ώρας, διατηρήστε αυτή την αβεβαιότητα αντί να εκχωρήσετε σιωπηρά τη ζώνη ώρας του διακομιστή σας.
Διατηρήστε την αρχική σημασία παράλληλα με την κανονικοποιημένη κατάσταση
Μια κανονικοποιημένη κατάσταση είναι χρήσιμη για την ομαδοποίηση αποστολών μεταξύ μεταφορέων, αλλά η αρχική περιγραφή του συμβάντος μπορεί να εξηγήσει με μεγαλύτερη ακρίβεια ένα λειτουργικό πρόβλημα. Διατηρήστε και τα δύο όπου είναι διαθέσιμα. Μια γενική κατηγορία εξαίρεσης από μόνη της μπορεί να μην ενημερώνει έναν εκπρόσωπο υποστήριξης αν το επόμενο βήμα είναι ο έλεγχος διεύθυνσης, η επικοινωνία με τον παραλήπτη ή η αναμονή νέας ενημέρωσης.
Μην συμπεραίνετε εγγύηση παράδοσης, επιβεβαιωμένη απώλεια ή συγκεκριμένη έκβαση τελωνειακού ελέγχου από μια ασαφή κατάσταση. Κλιμακώστε το ζήτημα σύμφωνα με τις υποκείμενες πληροφορίες και την πολιτική λειτουργίας σας.
5. Διατηρήστε τις εγγραφές ενημερωμένες μέσω polling ή webhooks
Η ανάκτηση λεπτομερειών μία φορά αρκεί για τον έλεγχο της συνδεσιμότητας, αλλά όχι για τη διατήρηση της ορατότητας των αποστολών. Ο σχεδιασμός παραγωγής σας χρειάζεται μηχανισμό ενημέρωσης. Επιβεβαιώστε τους μηχανισμούς που υποστηρίζει ο επιλεγμένος πάροχος και τις προϋποθέσεις που τους συνοδεύουν.
Με το polling, η εφαρμογή σας ζητά λεπτομέρειες παρακολούθησης βάσει προγράμματος. Προγραμματίστε τα αιτήματα εντός των τεκμηριωμένων ορίων, αποφύγετε την επαναλαμβανόμενη αναζήτηση αμετάβλητων εγγραφών χωρίς λόγο και χρησιμοποιήστε backoff για αποτυχίες που επιδέχονται επανάληψη. Το άνοιγμα μιας σελίδας παραγγελίας από έναν πελάτη δεν πρέπει να ενεργοποιεί αυτόματα ένα απεριόριστο upstream αίτημα· μια αποθηκευμένη προβολή παρακολούθησης μπορεί να εξυπηρετήσει τη σελίδα ενώ μια ελεγχόμενη διαδικασία παρασκηνίου την ανανεώνει.
Αν χρησιμοποιείτε webhooks, επικυρώστε τα εισερχόμενα αιτήματα χρησιμοποιώντας τον τεκμηριωμένο μηχανισμό επαλήθευσης του παρόχου. Αποθηκεύστε ή τοποθετήστε σε μόνιμη ουρά τα αποδεκτά μηνύματα πριν τα επιβεβαιώσετε, σύμφωνα με το συμβόλαιο webhook, και στη συνέχεια επεξεργαστείτε τα συμβάντα ασύγχρονα.
Σχεδιάστε τον δέκτη ώστε να ανέχεται διπλότυπα και απρόβλεπτη σειρά άφιξης, εκτός αν το τεκμηριωμένο συμβόλαιο παράδοσης εγγυάται το αντίθετο. Χρησιμοποιήστε αναγνωριστικό συμβάντος παρόχου για αποδιπλοποίηση όταν είναι διαθέσιμο. Διαφορετικά, ορίστε και δοκιμάστε ένα fingerprint με βάση κατάλληλα πεδία συμβάντος, αναγνωρίζοντας ότι μπορεί να απαιτούνται προσαρμογές στα δεδομένα σας.
Μια ενσωμάτωση με επίκεντρο τα webhooks μπορεί επίσης να χρησιμοποιεί ελεγχόμενη ανάκτηση για συμφωνία. Για παράδειγμα, μια εργασία αποκατάστασης μπορεί να ελέγχει εγγραφές που επηρεάστηκαν από διακοπή λειτουργίας του δέκτη. Αυτό αποτελεί μοτίβο ανθεκτικότητας και όχι άδεια αγνόησης των ορίων ρυθμού ή των οδηγιών του παρόχου.
6. Μετατρέψτε τις πληροφορίες παρακολούθησης σε ασφαλείς επιχειρηματικές ενέργειες
Ενημερώστε την εσωτερική εγγραφή αποστολής πριν ενεργοποιήσετε ενέργειες προς τον πελάτη. Διατηρήστε μόνιμη καταγραφή των ειδοποιήσεων και των μεταβάσεων ροής εργασίας, ώστε ένα επαναλαμβανόμενο συμβάν να μην δημιουργεί επαναλαμβανόμενα μηνύματα.
Αντιστοιχίστε τις επιχειρηματικές ενέργειες σε ουσιαστικές αλλαγές και όχι σε κάθε απόκριση API. Ένα νεοπαρατηρημένο συμβάν παράδοσης μπορεί να δικαιολογεί ειδοποίηση παράδοσης. Μια επαναλαμβανόμενη απόκριση που περιέχει το ίδιο συμβάν δεν πρέπει να το κάνει. Μια εξαίρεση μπορεί να απαιτεί εσωτερικό έλεγχο, αλλά το μήνυμα προς τον πελάτη πρέπει να αντικατοπτρίζει όσα λέει πραγματικά το συμβάν.
Ορίστε πώς θα διαχειρίζεστε συμβάντα που λαμβάνονται μετά την ολοκλήρωση μιας αποστολής. Μην διαγράφετε το ιστορικό συμβάντων και μην αποκλείετε οριστικά όλες τις μεταγενέστερες ενημερώσεις μόνο επειδή μια σύνοψη έφτασε σε τελική κατάσταση. Οι κανόνες διατήρησης, συμφωνίας και ειδοποιήσεων πρέπει να λαμβάνουν υπόψη νόμιμες διορθώσεις χωρίς να ανοίγουν ξανά επανειλημμένα τις ολοκληρωμένες ροές εργασίας.
Εφαρμογή της ροής εργασίας σε μια ενσωμάτωση 17TRACK
Για μια προσαρμοσμένη ενσωμάτωση παρακολούθησης, τα σχετικά σημεία εκκίνησης είναι η σελίδα 17TRACK Tracking API και η τεκμηρίωση για προγραμματιστές. Χρησιμοποιήστε τη σελίδα προϊόντος για την αξιολόγηση της προσφοράς και την τεκμηρίωση για τον καθορισμό του πραγματικού συμβολαίου ενσωμάτωσης. Οι σελίδες παρακολούθησης για καταναλωτές δεν αντικαθιστούν τις προδιαγραφές API.
Πριν γράψετε τον adapter σας, επιβεβαιώστε τη μορφή ελέγχου ταυτότητας, τις λειτουργίες εγγραφής και ανάκτησης, τους κανόνες αναγνώρισης μεταφορέων, τη διαχείριση αποκρίσεων σε επίπεδο στοιχείου και τα ισχύοντα όρια αιτημάτων. Για επεξεργασία με βάση webhooks, επιβεβαιώστε επίσης το σχήμα payload, τη διαδικασία επαλήθευσης, τις απαιτήσεις επιβεβαίωσης και τη συμπεριφορά επανάληψης.
Διατηρήστε αυτές τις λεπτομέρειες που αφορούν τον πάροχο μέσα σε έναν adapter αντί να διασπείρετε υποθέσεις για τα πεδία απόκρισης σε ολόκληρο το σύστημα παραγγελιών. Έτσι, η υπόλοιπη εφαρμογή σας μπορεί να λειτουργεί με εσωτερικές έννοιες όπως αποτέλεσμα εγγραφής, κατάσταση αποστολής, ιστορικό συμβάντων και τελευταία επιτυχημένη συγχρονισμένη ενημέρωση.
Έλεγχοι πριν από την κυκλοφορία που αποτρέπουν δαπανηρά λάθη
- Αποδεκτή αλλά κενή εγγραφή: Η διεπαφή εμφανίζει ότι οι πληροφορίες παρακολούθησης εκκρεμούν και όχι ότι το δέμα κινείται.
- Μεικτό αποτέλεσμα ομάδας: Κάθε αποστολή λαμβάνει το δικό της αποθηκευμένο αποτέλεσμα.
- Timeout μετά την υποβολή: Ο worker συμφωνεί το αβέβαιο αποτέλεσμα αντί να υποθέτει αποτυχία.
- Επαναλαμβανόμενο συμβάν: Το χρονολόγιο αποστολής και η ειδοποίηση πελάτη παραμένουν χωρίς διπλότυπα.
- Παλαιότερο συμβάν που λήφθηκε αργότερα: Το συμβάν διατηρείται χωρίς τυφλή αντικατάσταση μιας νεότερης σύνοψης.
- Μη διαθέσιμη upstream υπηρεσία: Η σελίδα πελάτη μπορεί να εμφανίζει το τελευταίο αποθηκευμένο αποτέλεσμα με κατάλληλη ένδειξη φρεσκάδας.
- Εσφαλμένη αντιστοίχιση μεταφορέα: Η εγγραφή μπορεί να διορθωθεί μέσω τεκμηριωμένης διαδικασίας αποκατάστασης.
- Χωρισμένη παραγγελία: Κάθε δέμα διατηρεί τη δική του κατάσταση παρακολούθησης και το ιστορικό συμβάντων.
- Έκθεση διαπιστευτηρίων ή payload: Τα αρχεία καταγραφής περιέχουν διαγνωστικές αναφορές χωρίς διαρροή μυστικών ή περιττών προσωπικών πληροφοριών.
Το πρακτικό κριτήριο ολοκλήρωσης δεν είναι απλώς η λήψη μιας επιτυχημένης απόκρισης εγγραφής. Είναι η δυνατότητα παρακολούθησης ενός δέματος από την υποβολή έως τις ενημερώσεις, η εξήγηση ενός κενού ή αποτυχημένου αποτελέσματος και η αποκατάσταση από διακοπείσα επεξεργασία χωρίς απώλεια συμβάντων ή διπλές ενέργειες προς τον πελάτη.
Συχνές ερωτήσεις
Η εγγραφή ενός αριθμού παρακολούθησης δημιουργεί αποστολή;
Όχι στη ροή εργασίας που περιγράφεται εδώ. Η εγγραφή παρακολούθησης υποβάλλει ένα υπάρχον αναγνωριστικό σε μια υπηρεσία παρακολούθησης. Η δημιουργία ετικέτας, η αγορά ταχυδρομικών τελών και η κράτηση μεταφορέα είναι ξεχωριστές λειτουργίες, εκτός αν ένα συγκεκριμένο API τις συνδυάζει ρητά.
Γιατί οι λεπτομέρειες παρακολούθησης είναι κενές μετά την επιτυχή εγγραφή;
Η αποδοχή της εγγραφής και η διαθεσιμότητα των δεδομένων παρακολούθησης είναι διαφορετικές συνθήκες. Ο μεταφορέας μπορεί να μην έχει καταγράψει ακόμη συμβάν ή μπορεί να χρειάζεται έλεγχος του αριθμού παρακολούθησης, της αντιστοίχισης μεταφορέα ή πρόσθετων πληροφοριών αναζήτησης. Εξετάστε το αποτέλεσμα σε επίπεδο στοιχείου πριν θεωρήσετε ότι η εγγραφή ολοκληρώθηκε επιτυχώς.
Πρέπει να καταχωρίζω την αποστολή κάθε φορά που ανακτώ την κατάστασή της;
Μην χρησιμοποιείτε την επαναλαμβανόμενη εγγραφή ως προεπιλεγμένο μηχανισμό ανανέωσης. Αποθηκεύστε την αποδεκτή κατάσταση εγγραφής και χρησιμοποιήστε τον τεκμηριωμένο μηχανισμό ανάκτησης ή ενημέρωσης. Ακολουθήστε τους ρητούς κανόνες του παρόχου για διορθώσεις, επανενεργοποίηση ή διπλές υποβολές.
Πρέπει να χρησιμοποιήσω polling ή webhooks;
Χρησιμοποιήστε τον μηχανισμό που ταιριάζει στο τεκμηριωμένο συμβόλαιο API και στις λειτουργικές απαιτήσεις σας. Το polling απαιτεί ελεγχόμενο πρόγραμμα αιτημάτων. Τα webhooks απαιτούν ασφαλή, μόνιμο δέκτη και επεξεργασία ασφαλή έναντι διπλοτύπων. Όπου υποστηρίζονται, οι ενημερώσεις μέσω webhook σε συνδυασμό με στοχευμένη συμφωνία μπορούν να παρέχουν πρακτική διαδρομή αποκατάστασης.
Μπορώ να χρησιμοποιήσω έναν αριθμό παρακολούθησης ως το μοναδικό αναγνωριστικό αποστολής στη βάση δεδομένων μου;
Χρησιμοποιήστε αντ’ αυτού ένα εσωτερικό αναγνωριστικό αποστολής. Αποθηκεύστε τον αριθμό παρακολούθησης και το σχετικό πλαίσιο μεταφορέα ως χαρακτηριστικά αυτής της εγγραφής. Έτσι διευκολύνεται η διαχείριση χωρισμένων παραγγελιών, διορθωμένων αριθμών παρακολούθησης και αναφορών ειδικών για τον πάροχο χωρίς να αλλάζει η ταυτότητα της εσωτερικής αποστολής.
Πηγές
- 17TRACK Tracking API — επίσημο σημείο εισόδου προϊόντος για την αξιολόγηση μιας ενσωμάτωσης 17TRACK API.
- Τεκμηρίωση 17TRACK API — επίσημη αναφορά για μορφές αιτημάτων, λειτουργίες, αποκρίσεις και απαιτήσεις ενσωμάτωσης ειδικές για την υλοποίηση. Ο ψευδοκώδικας και οι προτάσεις εσωτερικών πεδίων σε αυτόν τον οδηγό αποτελούν παραδείγματα σχεδιασμού εφαρμογής και όχι παραθέματα από το συγκεκριμένο συμβόλαιο API.


