Πώς να καταχωρίσετε έναν αριθμό παρακολούθησης μέσω API: πεδία αιτήματος, κωδικοί μεταφορέων και απαντήσεις
Για να καταχωρίσετε έναν αριθμό εντοπισμού μέσω API, στείλτε ένα αυθεντικοποιημένο αίτημα καταχώρισης που περιέχει τον αριθμό εντοπισμού της αποστολής και, όταν απαιτείται, ένα αναγνωριστικό μεταφορέα. Στη συνέχεια, ελέγξτε την απόκριση για κάθε αποστολή που υποβλήθηκε — όχι μόνο την κατάσταση HTTP — και αποθηκεύστε αν η καταχώριση πέτυχε, απέτυχε ή παραμένει αβέβαιη. Η καταχώριση ξεκινά τη ροή εργασίας εντοπισμού· δεν αποδεικνύει ότι ο μεταφορέας έχει σαρώσει το δέμα ή ότι τα συμβάντα εντοπισμού είναι ήδη διαθέσιμα.
Αυτός ο οδηγός απευθύνεται σε προγραμματιστές που συνδέουν ένα σύστημα διαχείρισης παραγγελιών, μια εφαρμογή αποθήκης ή μια πλατφόρμα ηλεκτρονικού εμπορίου με ένα API εντοπισμού. Χρησιμοποιεί το 17TRACK ως συγκεκριμένο παράδειγμα ενσωμάτωσης και εξηγεί ποιες λεπτομέρειες πρέπει να ελεγχθούν σε σχέση με την τεκμηρίωση για την επιλεγμένη έκδοση API.
Τι κάνει η καταχώριση — και τι δεν κάνει
Ένα αίτημα καταχώρισης ενημερώνει μια υπηρεσία εντοπισμού ποια αποστολή θέλετε να παρακολουθεί. Διαφέρει από την αγορά ετικέτας αποστολής, τον προγραμματισμό παραλαβής ή το αίτημα προς έναν μεταφορέα να δημιουργήσει μια αποστολή. Σε μια τυπική ενσωμάτωση, η ροή αποστολής δημιουργεί πρώτα έναν αριθμό εντοπισμού και στη συνέχεια η εφαρμογή σας καταχωρίζει αυτόν τον αριθμό.
Διατηρήστε αυτά τα τρία συμβάντα ξεχωριστά στην εφαρμογή σας:
- Η αποστολή δημιουργήθηκε: το σύστημα αποστολών σας έχει εκχωρήσει έναν αριθμό εντοπισμού.
- Η καταχώριση έγινε αποδεκτή: η υπηρεσία εντοπισμού έχει αποδεχτεί την αποστολή για εντοπισμό.
- Λήφθηκαν πληροφορίες εντοπισμού: τα συμβάντα του μεταφορέα έχουν γίνει διαθέσιμα μέσω της υπηρεσίας εντοπισμού.
Μην ενημερώνετε μια παραγγελία σε «σε μεταφορά» απλώς επειδή η καταχώριση πέτυχε. Μια ετικέτα που δημιουργήθηκε πρόσφατα ενδέχεται να μην έχει ακόμη φυσική σάρωση αποδοχής. Η κατάσταση αποστολής που εμφανίζεται στους πελάτες πρέπει να προέρχεται από συμβάντα εντοπισμού που ερμηνεύονται μέσω των κανόνων αντιστοίχισης καταστάσεων και όχι από την απόκριση καταχώρισης.
Για ενσωματώσεις 17TRACK, ξεκινήστε από την επισκόπηση του Tracking API και χρησιμοποιήστε την επίσημη τεκμηρίωση API ως αρμόδια πηγή για endpoints, ορισμούς πεδίων, αυθεντικοποίηση και κωδικούς απόκρισης. Τα παρακάτω παραδείγματα εστιάζουν στην καταχώριση και όχι στις ξεχωριστές εργασίες ανάκτησης αποτελεσμάτων ή λήψης ενημερώσεων.
Προετοιμάστε τα πεδία του αιτήματος πριν γράψετε την κλήση API
Η πιο χρήσιμη προετοιμασία είναι ένα μικρό συμβόλαιο πεδίων μεταξύ του συστήματος αποστολών σας και της ενσωμάτωσης εντοπισμού. Αποφασίστε από πού προέρχεται κάθε τιμή, αν μπορεί να λείπει και πώς θα επικυρώνεται.
| Πεδίο ή τιμή | Σκοπός | Κανόνας υλοποίησης |
|---|---|---|
| Αριθμός εντοπισμού | Προσδιορίζει την αποστολή προς εντοπισμό. | Αποθηκεύστε και μεταδώστε τον ως συμβολοσειρά· διατηρήστε τα αρχικά μηδενικά. |
| Αναγνωριστικό μεταφορέα | Προσδιορίζει τον μεταφορέα στο σύστημα του παρόχου εντοπισμού. | Χρησιμοποιήστε το τεκμηριωμένο αναγνωριστικό του παρόχου και όχι εσωτερικό κωδικό αποθήκης. |
| Εσωτερική αναφορά | Συνδέει την καταχώριση με την εγγραφή της αποστολής σας. | Χρησιμοποιήστε υποστηριζόμενο πεδίο αναφοράς, εφόσον υπάρχει· διατηρήστε ούτως ή άλλως τη δική σας αντιστοίχιση στη βάση δεδομένων. |
| Πρόσθετα δεδομένα ταυτοποίησης | Ενδέχεται να βοηθήσουν στην ταυτοποίηση μιας αποστολής όταν ο μεταφορέας απαιτεί περισσότερα από τον αριθμό εντοπισμού. | Υποβάλετε μόνο πεδία που τεκμηριώνονται για τη συγκεκριμένη ενσωμάτωση και τον μεταφορέα. |
| Διαπιστευτήριο API | Αυθεντικοποιεί τον λογαριασμό που πραγματοποιεί την κλήση. | Διατηρήστε το στον διακομιστή και εξαιρέστε το από τα αρχεία καταγραφής της εφαρμογής. |
Αντιμετωπίστε τον αριθμό εντοπισμού ως αναγνωριστικό
Μην μετατρέπετε ποτέ έναν αριθμό εντοπισμού σε ακέραιο. Η αριθμητική μετατροπή μπορεί να αφαιρέσει τα αρχικά μηδενικά και οι μεγάλες τιμές ενδέχεται να χάσουν την ακρίβειά τους σε ορισμένα περιβάλλοντα προγραμματισμού. Αφαιρέστε τυχόν κατά λάθος κενά στην αρχή ή στο τέλος, αλλά μην αφαιρείτε σημεία στίξης και μην αλλάζετε πεζά/κεφαλαία, εκτός αν η σχετική τεκμηρίωση ή η μορφή του μεταφορέα υποστηρίζει αυτήν την κανονικοποίηση.
Επικυρώστε τα προφανή σφάλματα εισόδου πριν καλέσετε το API: κενές συμβολοσειρές, απρόσμενες αλλαγές γραμμής και έναν αριθμό παραγγελίας που αντιγράφηκε στο πεδίο αριθμού εντοπισμού. Αποφύγετε την επιβολή ενός ενιαίου κανόνα μήκους ή χαρακτήρων για όλους τους μεταφορείς. Ένας κανόνας επικύρωσης που ταιριάζει σε έναν μεταφορέα μπορεί να απορρίψει έγκυρους αριθμούς άλλου μεταφορέα.
Διατηρήστε ξεχωριστές τις αναφορές παραγγελίας από τις ταυτότητες αποστολής
Μια παραγγελία μπορεί να έχει πολλά δέματα και μια αποστολή αντικατάστασης μπορεί να εισαγάγει έναν ακόμη αριθμό εντοπισμού. Μοντελοποιήστε την καταχώριση σε επίπεδο αποστολής ή δέματος αντί να υποθέτετε έναν αριθμό εντοπισμού ανά παραγγελία.
Αν χρησιμοποιείτε ετικέτα ή πεδίο αναφοράς που υποστηρίζει ο πάροχος, προτιμήστε μια αδιαφανή αναφορά αποστολής αντί για τη διεύθυνση email ή την ταχυδρομική διεύθυνση του πελάτη. Η δική σας βάση δεδομένων πρέπει να παραμένει η έγκυρη σύνδεση μεταξύ παραγγελιών, αποστολών, αριθμών εντοπισμού και αντιστοιχίσεων μεταφορέων.
Επιλέξτε τον σωστό κωδικό μεταφορέα
Ένας κωδικός μεταφορέα δεν είναι απαραίτητα ένα καθολικό αναγνωριστικό του κλάδου. Η τιμή που αναγνωρίζει μια πλατφόρμα εντοπισμού μπορεί να διαφέρει από το όνομα του μεταφορέα που αποθηκεύεται στο λογισμικό αποστολών σας. Ακόμη και δύο συστήματα που χρησιμοποιούν αριθμητικούς κωδικούς μπορεί να εκχωρούν διαφορετικούς αριθμούς στον ίδιο μεταφορέα.
Διατηρήστε ρητή αντιστοίχιση από την υπηρεσία αποστολών σας προς το αναγνωριστικό μεταφορέα του παρόχου εντοπισμού. Όπου είναι απαραίτητο, διακρίνετε την περιφερειακή λειτουργία ή υπηρεσία ενός μεταφορέα από την ευρύτερη επωνυμία του. Μια αντιστοίχιση που βασίζεται μόνο σε εμφανιζόμενο όνομα μπορεί να γίνει ασαφής όταν τα συστήματα αποστολών χρησιμοποιούν ψευδώνυμα.
- Όταν ο μεταφορέας είναι γνωστός: χρησιμοποιήστε το τεκμηριωμένο αναγνωριστικό μεταφορέα όταν υποστηρίζεται, ιδιαίτερα όταν οι μορφές αριθμών εντοπισμού επικαλύπτονται.
- Όταν ο μεταφορέας είναι άγνωστος: χρησιμοποιήστε την αυτόματη ανίχνευση μόνο μέσω του τεκμηριωμένου μηχανισμού. Μην υποθέτετε ότι η παράλειψη, μια κενή συμβολοσειρά, το μηδέν και το null σημαίνουν το ίδιο.
- Όταν το αποτέλεσμα φαίνεται λανθασμένο: επαληθεύστε την αρχική ετικέτα, την υπηρεσία αποστολής και την αντιστοίχιση πριν καταχωρίσετε επανειλημμένα τον ίδιο αριθμό.
Η αυτόματη ανίχνευση είναι χρήσιμη, αλλά δεν αποτελεί απόδειξη ότι ένας συγκεκριμένος μεταφορέας έχει στην κατοχή του την αποστολή. Ομοίως, ένας έγκυρος κωδικός μεταφορέα δεν εγγυάται ότι ο παρεχόμενος αριθμός εντοπισμού ανήκει σε αυτόν τον μεταφορέα.
Παράδειγμα: υποβολή αιτήματος καταχώρισης 17TRACK
Το ακόλουθο παράδειγμα παρουσιάζει το endpoint καταχώρισης 17TRACK v2.2, την κεφαλίδα αυθεντικοποίησης 17token και έναν πίνακα που περιέχει ένα αντικείμενο αριθμού εντοπισμού. Επιβεβαιώστε ότι αυτή η έκδοση και οι απαιτήσεις αιτήματός της αντιστοιχούν στον λογαριασμό σας και στην επίσημη τεκμηρίωση πριν από την ανάπτυξη. Ο αριθμός εντοπισμού είναι placeholder και πρέπει να αντικατασταθεί με πραγματικό αναγνωριστικό αποστολής.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Αυτό το ελάχιστο παράδειγμα δεν παρουσιάζει επιλογή μεταφορέα ή συμπληρωματικά πεδία ειδικά για μεταφορείς. Ελέγξτε την τεκμηρίωση καταχώρισης για να προσδιορίσετε πώς λειτουργεί η ανίχνευση μεταφορέα όταν το πεδίο μεταφορέα παραλείπεται και αν η αποστολή σας χρειάζεται πρόσθετες πληροφορίες. Αν παρέχετε μεταφορέα, χρησιμοποιήστε το τεκμηριωμένο πεδίο carrier και το αναγνωριστικό που αναμένει η συγκεκριμένη έκδοση API.
Εκτελέστε αυτό το αίτημα από περιβάλλον στην πλευρά του διακομιστή. Μην ενσωματώνετε το token σε δημόσιο ηλεκτρονικό κατάστημα, script προγράμματος περιήγησης ή εφαρμογή κινητού που διανέμεται στους πελάτες. Μια μεταβλητή περιβάλλοντος είναι πρακτική για τοπικό παράδειγμα· οι εγκαταστάσεις παραγωγής πρέπει να χρησιμοποιούν τους ελέγχους διαχείρισης μυστικών του οργανισμού σας.
Διαβάστε την απόκριση σε τρία επίπεδα
Ένας αξιόπιστος χειριστής απόκρισης απαντά σε τρία ξεχωριστά ερωτήματα: έφτασε το αίτημα στην υπηρεσία, αποδέχτηκε η υπηρεσία τη λειτουργία και τι συνέβη σε κάθε αποστολή;
1. Αποτέλεσμα HTTP και μεταφοράς
Ένα timeout σύνδεσης, μια αποτυχία TLS ή μια διακοπείσα απόκριση δεν σας ενημερώνει απαραίτητα αν ο διακομιστής επεξεργάστηκε το αίτημα. Σημειώστε το αποτέλεσμα ως αβέβαιο μέχρι να μπορέσετε να το συμφωνήσετε. Μια επιτυχής κατάσταση HTTP επιβεβαιώνει μια επιτυχή ανταλλαγή HTTP, αλλά πρέπει και πάλι να ελέγξετε την απόκριση της εφαρμογής.
2. Αποτέλεσμα σε επίπεδο αιτήματος
Ελέγξτε το τεκμηριωμένο αποτέλεσμα ανώτατου επιπέδου του API και τα πεδία σφάλματος. Τα σφάλματα αυθεντικοποίησης, το μη έγκυρο JSON και οι περιορισμοί λογαριασμού απαιτούν διαφορετικές ενέργειες. Αποθηκεύστε τον αρχικό κωδικό και το μήνυμα σφάλματος του παρόχου αντί να περιορίζετε κάθε αποτυχία σε «ο εντοπισμός δεν είναι διαθέσιμος».
3. Αποτέλεσμα σε επίπεδο αποστολής
Για μαζικές καταχωρίσεις, υπολογίστε κάθε στοιχείο που υποβλήθηκε. Μια απόκριση μπορεί να διακρίνει τις αποδεκτές από τις απορριφθείσες αποστολές· ο parser σας πρέπει να ακολουθεί το ακριβές σχήμα που τεκμηριώνεται για την επιλεγμένη έκδοση. Μην επισημαίνετε ολόκληρη τη δέσμη ως καταχωρισμένη απλώς επειδή πέτυχε ένα στοιχείο.
Κανονικοποιήστε τις αποκρίσεις του παρόχου στις δικές σας σταθερές καταστάσεις εφαρμογής. Για παράδειγμα, η βάση δεδομένων σας μπορεί να χρησιμοποιεί accepted, rejected και uncertain. Αυτές είναι προτεινόμενες εσωτερικές καταστάσεις και όχι κυριολεκτικές τιμές απόκρισης του 17TRACK. Διατηρήστε διαθέσιμη την αρχική απόκριση του παρόχου σύμφωνα με κατάλληλη πολιτική διατήρησης και πρόσβασης, ώστε οι προγραμματιστές να μπορούν να διερευνούν αποκλίσεις.
Διαχειριστείτε τις επαναλήψεις χωρίς ατέρμονο βρόχο
Η πολιτική επανάληψης πρέπει να εξαρτάται από την αποτυχία και όχι απλώς από το αν προέκυψε εξαίρεση.
- Μη έγκυρη είσοδος: διορθώστε το πεδίο πριν από την επανάληψη.
- Αποτυχία αυθεντικοποίησης: επαληθεύστε τα διαπιστευτήρια και τη ρύθμιση του λογαριασμού.
- Περιορισμός ρυθμού: ακολουθήστε τα τεκμηριωμένα όρια και τις οδηγίες επανάληψης.
- Προσωρινή αποτυχία υπηρεσίας: επαναλάβετε εντός καθορισμένου ορίου προσπαθειών και χρόνου.
- Timeout μετά την υποβολή: συμφωνήστε την κατάσταση καταχώρισης πριν θεωρήσετε ότι η πρώτη προσπάθεια απέτυχε.
- Απόκριση σχετική με διπλότυπο: ελέγξτε αν η αποστολή έχει ήδη καταχωριστεί.
Μην υποθέτετε ότι η καταχώριση είναι idempotent, εκτός αν η τεκμηρίωση ορίζει αυτήν τη συμπεριφορά. Η αποδιπλοποίηση στην πλευρά της εφαρμογής μειώνει τις τυχαίες επαναλαμβανόμενες υποβολές, αλλά δεν καθορίζει την πολιτική του παρόχου για τα διπλότυπα.
Παρακολουθήστε την καταχώριση ξεχωριστά από τις ενημερώσεις εντοπισμού
Η παρακολούθηση API πρέπει να διακρίνει μια αποτυχία ενσωμάτωσης από μια αποστολή που απλώς δεν έχει νέο συμβάν μεταφορέα. Αυτές οι συνθήκες απαιτούν διαφορετικούς υπευθύνους και διαφορετικές διορθώσεις.
Για την καταχώριση, παρακολουθήστε μετρήσεις αποδοχών και απορρίψεων, κατηγορίες σφαλμάτων, αβέβαια αποτελέσματα, εκκρεμότητες επαναλήψεων και καθυστέρηση αποκρίσεων. Για τον επακόλουθο εντοπισμό, παρακολουθήστε ξεχωριστά την παραλαβή ενημερώσεων ή τις αποτυχίες ανάκτησης.
Συχνές ερωτήσεις
Μπορώ να καταχωρίσω έναν αριθμό εντοπισμού πριν από την πρώτη σάρωση του μεταφορέα;
Η καταχώριση και οι σαρώσεις του μεταφορέα είναι ξεχωριστά συμβάντα. Μια υπηρεσία μπορεί να αποδεχτεί έναν αριθμό πριν γίνουν διαθέσιμα τα συμβάντα εντοπισμού, ανάλογα με τους κανόνες επικύρωσής της. Μην ερμηνεύετε την αποδοχή ως απόδειξη ότι ο μεταφορέας παρέλαβε το δέμα.
Χρειάζεται πάντα να παρέχω κωδικό μεταφορέα;
Αυτό εξαρτάται από την τεκμηριωμένη συμπεριφορά ανίχνευσης του API και τη συγκεκριμένη αποστολή. Αν ο μεταφορέας είναι γνωστός, ένα ρητό και σωστά αντιστοιχισμένο αναγνωριστικό μπορεί να μειώσει την ασάφεια. Αν είναι άγνωστος, χρησιμοποιήστε την τεκμηριωμένη μέθοδο αυτόματης ανίχνευσης.
Γιατί το API επέστρεψε επιτυχία HTTP ενώ μια αποστολή απέτυχε;
Το αίτημα HTTP μπορεί να πετύχει ενώ η εφαρμογή απορρίπτει ένα μεμονωμένο στοιχείο. Διαβάστε το αποτέλεσμα της εφαρμογής ανώτατου επιπέδου και τα αποτελέσματα σε επίπεδο αποστολής. Αυτή η διάκριση είναι ιδιαίτερα σημαντική για μαζικά αιτήματα.
Τι πρέπει να κάνω όταν ένα αίτημα καταχώρισης λήξει λόγω timeout;
Αντιμετωπίστε το αποτέλεσμα ως αβέβαιο. Ο διακομιστής μπορεί να επεξεργάστηκε το αίτημα πριν αποτύχει η σύνδεση. Ελέγξτε την τεκμηριωμένη συμπεριφορά για διπλότυπα και τις διαθέσιμες μεθόδους αναζήτησης καταχώρισης ή εντοπισμού και, στη συνέχεια, συμφωνήστε ή επαναλάβετε βάσει περιορισμένης πολιτικής.
Η καταχώριση ρυθμίζει αυτόματα τις ειδοποιήσεις εντοπισμού;
Μην το υποθέτετε. Η καταχώριση, η ανάκτηση εντοπισμού και η ρύθμιση webhook είναι ξεχωριστές ανάγκες ενσωμάτωσης. Επαληθεύστε τη σχετική τεκμηρίωση και δοκιμάστε ολόκληρη τη διαδρομή ενημέρωσης πριν βασιστείτε σε αυτή για ειδοποιήσεις πελατών.
Πηγές
- Τεκμηρίωση API 17TRACK — αναφορά για endpoints καταχώρισης, αυθεντικοποίηση, πεδία αιτημάτων, αναγνωριστικά μεταφορέων, σχήματα αποκρίσεων και χειρισμό σφαλμάτων.
- Επισκόπηση Tracking API 17TRACK — επίσημο σημείο εκκίνησης για το προϊόν Tracking API και τους πόρους ενσωμάτωσης προγραμματιστών.


