Skip to main content
ΑρχικήΙστολόγιοΟδηγοίΠώς να επικυρώνετε τους αριθμούς παρακολούθησης πριν από την υποβολή στο API: 7 κανόνες που πρέπει να ακολουθείτε

Πώς να επικυρώνετε τους αριθμούς παρακολούθησης πριν από την υποβολή στο API: 7 κανόνες που πρέπει να ακολουθείτε

17TRACK

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

7 κανόνες για την επικύρωση αριθμών παρακολούθησης πριν από την υποβολή στο API

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

Τι μπορεί —και τι δεν μπορεί— να επιβεβαιώσει η επικύρωση

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

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

Οι επτά κανόνες

1. Κανονικοποιήστε την τιμή χωρίς να αλλάξετε το νόημά της

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

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

Ο χειρισμός Unicode χρειάζεται προσοχή. Ένας οπτικά παρόμοιος χαρακτήρας από άλλο αλφάβητο μπορεί να μην γίνεται αποδεκτός από ένα API, παρότι μοιάζει με γράμμα ή ψηφίο ASCII. Ο περιορισμός της κανονικής τιμής στο σύνολο χαρακτήρων που επιτρέπεται από την επιλεγμένη ενσωμάτωση μπορεί να αποτρέψει δυσνόητα σφάλματα στα επόμενα στάδια.

2. Απορρίψτε τιμές που αποτυγχάνουν στους βασικούς δομικούς ελέγχους

Πριν εφαρμόσετε ειδική λογική μεταφορέα, ελέγξτε αν η τιμή υπάρχει και είναι εύλογη. Χρήσιμοι έλεγχοι περιλαμβάνουν ελάχιστο και μέγιστο μήκος, επιτρεπόμενες κατηγορίες χαρακτήρων και αν η τιμή περιέχει μόνο κενά ή ένα σύμβολο κράτησης θέσης όπως «N/A», «TBD» ή «test». Τα ακριβή όρια πρέπει να προέρχονται από τη σύμβαση του API ή την τεκμηρίωση του μεταφορέα. Μην επινοείτε ένα καθολικό μέγιστο μόνο επειδή τα περισσότερα παραδείγματα είναι σύντομα.

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

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

3. Χρησιμοποιήστε το πλαίσιο του μεταφορέα αντί να μαντεύετε μόνο από τον αριθμό

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

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

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

4. Εφαρμόστε αθροίσματα ελέγχου μόνο όταν ο κανόνας είναι τεκμηριωμένος

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

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

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

5. Διαχωρίστε την επικύρωση μορφής από την καταλληλότητα για το API

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

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

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

6. Προστατεύστε το API με περιορισμένες εισόδους, αποδιπλοποίηση και ασφαλείς επαναλήψεις

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

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

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

7. Επιβεβαιώστε το αποτέλεσμα μετά την υποβολή και παρακολουθήστε τα ψευδώς θετικά

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

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

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

Μια πρακτική ακολουθία επικύρωσης

Μια συντηρήσιμη υλοποίηση μπορεί να χρησιμοποιεί την ακόλουθη ακολουθία:

  1. Ελέγξτε ότι το αίτημα περιέχει τιμή τύπου συμβολοσειράς και έγκυρη επιχειρησιακή εγγραφή.
  2. Αποθηκεύστε την αρχική είσοδο και, στη συνέχεια, δημιουργήστε μια τεκμηριωμένη κανονική μορφή.
  3. Απορρίψτε κενές τιμές, σύμβολα κράτησης θέσης, μη ασφαλείς χαρακτήρες και τιμές εκτός του τεκμηριωμένου εύρους μήκους.
  4. Επιλύστε τον μεταφορέα από αξιόπιστα δεδομένα παραγγελίας ή χρησιμοποιήστε ρητά υποστηριζόμενη ροή ανίχνευσης.
  5. Εφαρμόστε ειδικούς για τον μεταφορέα κανόνες σύνταξης και αθροίσματος ελέγχου μόνο όταν υποστηρίζονται από έγκυρη τεκμηρίωση.
  6. Ελέγξτε τις απαιτήσεις endpoint, την κατάσταση διπλοτύπων και την καταλληλότητα επανάληψης.
  7. Υποβάλετε, κατηγοριοποιήστε την απόκριση, αποθηκεύστε το αποτέλεσμα και προγραμματίστε παρακολούθηση για ανεπίλυτες εγγραφές.

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

Λίστα ελέγχου υλοποίησης

  • Αποθηκεύετε τους αριθμούς παρακολούθησης ως συμβολοσειρές, ώστε να διατηρούνται τα αρχικά μηδενικά.
  • Διατηρείτε χωριστά τις αρχικές και τις κανονικές τιμές όταν έχει σημασία η δυνατότητα ελέγχου.
  • Διατηρείτε τους κανόνες μεταφορέων ως ρυθμίσεις με εκδόσεις και όχι ως διάσπαρτες, hard-coded συνθήκες.
  • Δοκιμάζετε γράμματα, ψηφία, ενωτικά, κενά, οπτικά παρόμοιους χαρακτήρες Unicode, σύμβολα κράτησης θέσης και οριακά μήκη.
  • Χρησιμοποιείτε αξιόπιστο πλαίσιο μεταφορέα όποτε είναι διαθέσιμο.
  • Μην συμπεραίνετε την ύπαρξη αποστολής από μια επιτυχή αντιστοίχιση κανονικής έκφρασης.
  • Κατηγοριοποιείτε τα μόνιμα σφάλματα επικύρωσης χωριστά από τα προσωρινά σφάλματα API ή δικτύου.
  • Εξετάζετε την τεκμηρίωση του παρόχου πριν αλλάξετε κανόνες μορφής ή λογική αιτημάτων.

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

Μπορεί μια κανονική έκφραση να επικυρώσει έναν αριθμό παρακολούθησης;

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

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

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

Αρκεί ένα άθροισμα ελέγχου για την επιβεβαίωση μιας αποστολής;

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

Τι πρέπει να συμβαίνει όταν ο μεταφορέας είναι άγνωστος;

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

Πώς πρέπει να αντιμετωπίζονται τα σφάλματα API;

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

Πηγές