Κατάσταση παράδοσης του Shipping API: Κωδικοί κατάστασης, Webhooks και ειδοποιήσεις εξαιρέσεων

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

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

Διαχωρίστε τους κωδικούς HTTP, τα αποτελέσματα API και τις καταστάσεις αποστολής

Η φράση «κωδικός κατάστασης» μπορεί να αναφέρεται σε τρία διαφορετικά επίπεδα. Η ανάμειξή τους δημιουργεί παραπλανητικούς πίνακες ελέγχου και περιττές ειδοποιήσεις πελατών.

Επίπεδο	Τι σας ενημερώνει	Παράδειγμα ερμηνείας
Απόκριση HTTP	Το αποτέλεσμα του αιτήματος HTTP	Μια απόκριση 200 υποδεικνύει επιτυχία σε επίπεδο HTTP· δεν σημαίνει ότι το δέμα παραδόθηκε.
Επιχειρηματικό αποτέλεσμα API	Αν η ζητούμενη λειτουργία ολοκληρώθηκε επιτυχώς σύμφωνα με τους κανόνες εφαρμογής του παρόχου	Το σώμα της απόκρισης μπορεί να αναφέρει ότι μια εγγραφή παρακολούθησης απορρίφθηκε, ακόμη και μέσα σε επιτυχή απόκριση HTTP, αν το API χρησιμοποιεί αυτόν τον σχεδιασμό.
Κατάσταση αποστολής	Η αναφερόμενη φυσική ή λειτουργική κατάσταση του δέματος	Σε μεταφορά, σε αναμονή παραλαβής ή παραδόθηκε.

Το πρότυπο σημασιολογίας HTTP ορίζει τις σημασίες των αποκρίσεων HTTP. Για παράδειγμα, το 202 Accepted σημαίνει ότι ένα αίτημα έγινε αποδεκτό για επεξεργασία, αλλά η επεξεργασία δεν έχει απαραίτητα ολοκληρωθεί. Δεν αποτελεί απόδειξη ότι ένας μεταφορέας έχει παραλάβει ένα δέμα.

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

Δημιουργήστε ένα μοντέλο κατάστασης χωρίς να απορρίπτετε τις λεπτομέρειες του μεταφορέα

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

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

Ενδεικτική εσωτερική κατάσταση	Σημασία	Λειτουργική προσοχή
Οι πληροφορίες ελήφθησαν	Υπάρχουν ηλεκτρονικές πληροφορίες αποστολής.	Μην θεωρείτε τη δημιουργία ετικέτας επιβεβαιωμένη φυσική παράδοση στον μεταφορέα.
Σε μεταφορά	Η εγγραφή παρακολούθησης υποδεικνύει κίνηση μέσω του δικτύου παράδοσης.	Αυτή η ευρεία κατηγορία μπορεί να περιλαμβάνει διαφορετικά στάδια μεταφοράς.
Προς παράδοση	Το δέμα αναφέρεται ότι βρίσκεται σε διαδρομή παράδοσης.	Μην το μετατρέπετε σε άνευ όρων εγγύηση παράδοσης.
Σε αναμονή παραλαβής	Ο παραλήπτης αναμένεται να παραλάβει το δέμα.	Συμπεριλάβετε οδηγίες ή προθεσμίες παραλαβής μόνο όταν υποστηρίζονται από την πηγή.
Παραδόθηκε	Η πηγή παρακολούθησης αναφέρει παράδοση.	Μια σάρωση παράδοσης από μόνη της δεν επιλύει τον ισχυρισμό πελάτη ότι δεν παρέλαβε το δέμα.
Εξαίρεση	Ένα συμβάν μπορεί να απαιτεί προσοχή ή να διακόπτει την κανονική πορεία.	Διατηρήστε την αιτία αντί να θεωρείτε κάθε εξαίρεση απώλεια.
Επιστροφή σε εξέλιξη ή επιστράφηκε	Το δέμα επιστρέφει ή έχει αναφερθεί ολοκλήρωση της επιστροφής.	Διατηρήστε ξεχωριστή την πορεία επιστροφής από την παράδοση στον αρχικό παραλήπτη.
Άγνωστη	Οι διαθέσιμες πληροφορίες δεν μπορούν να αντιστοιχιστούν με βεβαιότητα.	Διερευνήστε την αντιστοίχιση ή το κενό δεδομένων αντί να επινοήσετε κατάσταση παράδοσης.

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

Για μια υλοποίηση πολλών μεταφορέων, το 17TRACK Tracking API αποτελεί σχετική επιλογή ενσωμάτωσης. Χρησιμοποιήστε την επίσημη τεκμηρίωση API για να καθορίσετε το συμβόλαιο υλοποίησης, αντί να αντιγράψετε ενδεικτικές ετικέτες σε πεδία ειδικά για τον πάροχο. Επιβεβαιώστε τους ισχύοντες ορισμούς καταστάσεων, τη διαμόρφωση webhook, τις απαιτήσεις ελέγχου ταυτότητας και τη σημασιολογία των αποκρίσεων πριν δημιουργήσετε τον adapter.

Δομήστε τον χειρισμό webhook γύρω από την αξιόπιστη παραλαβή

Ένα webhook είναι ένα αίτημα HTTP που αποστέλλεται στο endpoint σας για να αναφέρει ένα συμβάν. Μπορεί να μειώσει την ανάγκη επαναλαμβανόμενης δημοσκόπησης, αλλά δεν πρέπει να θεωρείται εγγύηση άμεσης, διατεταγμένης ή ακριβώς μίας παράδοσης. Σχεδιάστε τον δέκτη ώστε να αντέχει επαναλήψεις, διακοπές και απρόσμενα payloads, εκτός αν ο πάροχος εγγυάται ρητά το αντίθετο.

1. Ελέγξτε την ταυτότητα του αιτήματος. Εφαρμόστε τη μέθοδο επαλήθευσης που τεκμηριώνει ο πάροχος. Αν υποστηρίζονται υπογραφές, επικυρώστε τις χρησιμοποιώντας τον καθορισμένο αλγόριθμο και τα ακατέργαστα bytes του αιτήματος. Μην επινοείτε κεφαλίδα υπογραφής και μην υποθέτετε ότι κάθε υπηρεσία χρησιμοποιεί HMAC.
2. Επικυρώστε το payload. Ελέγξτε τα απαιτούμενα πεδία, τους τύπους, το μέγεθος του payload και τη συσχέτιση με αποστολή που διαχειρίζεται ο λογαριασμός σας. Χειριστείτε άγνωστα προαιρετικά πεδία χωρίς να διακόπτετε άσκοπα τη συμβατότητα προς τα εμπρός.
3. Αποθηκεύστε πριν επιβεβαιώσετε. Αποθηκεύστε το αποδεκτό συμβάν ή τοποθετήστε το σε μόνιμη ουρά πριν στείλετε την τεκμηριωμένη επιτυχή απόκριση. Αν η αποθήκευση αποτύχει, μην επιβεβαιώσετε ότι το συμβάν παραλήφθηκε με ασφάλεια.
4. Επεξεργαστείτε ασύγχρονα. Εκτελείτε την αντιστοίχιση καταστάσεων, τις ενημερώσεις παραγγελιών και τις αποφάσεις ειδοποιήσεων εκτός του χειριστή αιτήματος όπου είναι πρακτικά δυνατό.
5. Κάντε τις παρενέργειες ιδεμποτέντ. Ένα επαναλαμβανόμενο συμβάν δεν πρέπει να δημιουργεί νέο δελτίο υποστήριξης ή να στέλνει δεύτερο αντίγραφο του ίδιου μηνύματος πελάτη.

Ο ακριβής κωδικός επιβεβαίωσης, το χρονικό όριο, το πρόγραμμα επαναλήψεων και η συμπεριφορά επανάληψης εξαρτώνται από τον πάροχο. Ελέγξτε ρητά αυτές τις λεπτομέρειες. Μια γενική οδηγία «επιστρέψτε 200» δεν αντικαθιστά το συμβόλαιο webhook.

Χρησιμοποιήστε HTTPS και κρατήστε τα διαπιστευτήρια εκτός URL και τακτικών αρχείων καταγραφής. Εφαρμόστε ελέγχους πρόσβασης στα αποθηκευμένα payloads, επειδή τα δεδομένα παρακολούθησης μπορεί να περιέχουν προσωπικές πληροφορίες. Το OWASP REST Security Cheat Sheet παρέχει σχετικές οδηγίες για την προστασία μεταφοράς, την επικύρωση εισόδου και την ασφάλεια endpoint.

Αποφύγετε τα διπλότυπα συμβάντων χωρίς να καταστέλλετε πραγματικές ενημερώσεις

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

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

Διατηρήστε ξεχωριστές την ώρα συμβάντος και την ώρα παραλαβής

Υποθέστε ότι ένα συμβάν «σε μεταφορά» φτάνει στο σύστημά σας μετά από ένα συμβάν «προς παράδοση», αλλά η χρονική σήμανση του μεταφορέα είναι παλαιότερη. Αποθηκεύστε το στο ιστορικό χωρίς να αλλάξετε αυτόματα την τρέχουσα κατάσταση ξανά σε «σε μεταφορά».

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

Μετατρέψτε τις εξαιρέσεις σε ενέργειες με υπεύθυνο

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

Ξεκινήστε με μια μικρή πολιτική δρομολόγησης:

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

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

Αντιμετωπίστε την «καμία ενημέρωση» ως ξεχωριστή συνθήκη

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

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

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

Παρακολουθείτε την υγεία της ενσωμάτωσης ξεχωριστά από την απόδοση παράδοσης

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

• Υγεία αιτημάτων: Παρακολουθήστε αποτυχίες ελέγχου ταυτότητας, χρονικά όρια, αποκρίσεις περιορισμού ρυθμού, σφάλματα διακομιστή και απορρίψεις σε επίπεδο εφαρμογής.
• Υγεία webhook: Παρακολουθήστε αποτυχίες επαλήθευσης, καθυστέρηση επιβεβαίωσης, αποτυχίες αποθήκευσης, διπλότυπες παραδόσεις και σφάλματα επεξεργασίας.
• Υγεία επεξεργασίας: Παρακολουθήστε την ηλικία ουράς, τα μη επεξεργασμένα συμβάντα, τις αποτυχίες αντιστοίχισης και τις αποτυχίες ειδοποιήσεων.
• Φρεσκάδα παρακολούθησης: Μετρήστε τον χρόνο από το τελευταίο συμβάν πηγής ξεχωριστά από τον χρόνο από την τελευταία επιτυχή εισαγωγή σας.
• Λειτουργικά αποτελέσματα: Παρακολουθήστε τις ανεπίλυτες εξαιρέσεις, τον χρόνο μέχρι την ανάθεση και τις εκπρόθεσμες επανεπικοινωνίες.

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

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

Δοκιμάστε τις περιπτώσεις αποτυχίας πριν ενεργοποιήσετε τις ειδοποιήσεις πελατών

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

• Ένα διπλότυπο webhook δημιουργεί μία προβλεπόμενη ειδοποίηση πελάτη.
• Ένα παλαιότερο συμβάν που φτάνει αργά δεν αντικαθιστά λανθασμένα την τρέχουσα κατάσταση.
• Μια άγνωστη κατάσταση διατηρείται και επισημαίνεται αντί να αντιστοιχιστεί σιωπηρά σε «παραδόθηκε».
• Μια αποτυχημένη μόνιμη εγγραφή δεν παράγει επιτυχή επιβεβαίωση.
• Μια προσωρινή διακοπή downstream αφήνει τα συμβάντα διαθέσιμα για επανάληψη.
• Ένα συμβάν παράδοσης που ακολουθείται από διόρθωση παραμένει ελέγξιμο.
• Μια παραγγελία με πολλά δέματα δεν γίνεται πλήρως παραδοθείσα όταν έχει παραδοθεί μόνο ένα δέμα.
• Μια διακοπή API ειδοποιεί τη μηχανική ομάδα χωρίς να ενημερώνει αυτόματα τους πελάτες ότι τα δέματά τους καθυστερούν.

Το κριτήριο κυκλοφορίας πρέπει να είναι η λειτουργική συνέπεια: η εγγραφή αποστολής, το μήνυμα πελάτη και η ενέργεια υποστήριξης πρέπει να συμφωνούν με τα ίδια υποκείμενα στοιχεία. Μια επιτυχής απόκριση webhook από μόνη της δεν αποδεικνύει ότι η εμπειρία παράδοσης λειτουργεί.

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

Σημαίνει το HTTP 200 ότι το δέμα παραδόθηκε;

Όχι. Υποδεικνύει επιτυχία σε επίπεδο HTTP για το αίτημα. Διαβάστε ξεχωριστά το επιχειρηματικό αποτέλεσμα του API και τα πεδία κατάστασης αποστολής. Για ένα webhook, η επιτυχής επιβεβαίωση αφορά την παραλαβή της ειδοποίησης και όχι τη φυσική παράδοση του δέματος.

Πρέπει να χρησιμοποιώ webhooks ή polling για ενημερώσεις παρακολούθησης;

Χρησιμοποιήστε webhooks για ενημερώσεις που βασίζονται σε συμβάντα όταν τα υποστηρίζει ο πάροχος. Όπου υποστηρίζεται και δικαιολογείται λειτουργικά, προσθέστε περιορισμένο polling συμφωνίας για την ανάκτηση κενών. Το polling μόνο του μπορεί να είναι κατάλληλο όταν τα webhooks δεν είναι διαθέσιμα, αλλά η συχνότητά του πρέπει να σέβεται τα όρια του παρόχου και τις απαιτήσεις φρεσκάδας σας.

Γιατί μπορεί να αλλάξει η κατάσταση παρακολούθησης μετά την ένδειξη «παραδόθηκε»;

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

Πόσο γρήγορα πρέπει να αποστέλλεται μια ειδοποίηση εξαίρεσης;

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

Πρέπει οι πελάτες να βλέπουν την ακατέργαστη κατάσταση του μεταφορέα;

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

Πηγές

• RFC 9110: HTTP Semantics — αναφορά για τις σημασίες των κωδικών κατάστασης HTTP, συμπεριλαμβανομένων των 200 και 202.
• OWASP REST Security Cheat Sheet — οδηγίες ασφαλείας σχετικές με endpoints API και webhook.
• 17TRACK Tracking API — επίσημη αναφορά προϊόντος για την επιλογή ενσωμάτωσης παρακολούθησης που συζητείται.
• 17TRACK API Documentation — επίσημη αναφορά για τις ειδικές απαιτήσεις ενσωμάτωσης του παρόχου· τα ενδεικτικά σχήματα και οι προτάσεις ροής εργασίας αυτού του οδηγού δεν αντικαθιστούν αυτό το συμβόλαιο.