Επεξεργασία της κατάστασης «εκτελείται» κατά τον έλεγχο παραγγελίας μέσω API

Τι σημαίνει processing στην απάντηση του API

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

Το processing δεν επιβεβαιώνει επιτυχή εκτέλεση και δεν σημαίνει σφάλμα. Μετά από αυτό η παραγγελία μπορεί να μεταβεί σε completed, partial, canceled ή failed. Όσο ο πάροχος επιστρέφει ενδιάμεση κατάσταση, μην δημιουργείτε νέο αίτημα για τον ίδιο σύνδεσμο και τον ίδιο όγκο.

HTTP 200 με κατάσταση processing σημαίνει επιτυχής απάντηση του API, όχι επιτυχής ολοκλήρωση της παραγγελίας. Αυτά τα γεγονότα πρέπει να αποθηκεύονται και να επεξεργάζονται ξεχωριστά.

Ποια δεδομένα χρειάζονται για τον έλεγχο παραγγελίας

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

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

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

Παράδειγμα αιτήματος κατάστασης μέσω curl

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

Αίτημα GET για μία παραγγελία

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Παράδειγμα απάντησης:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Τα πεδία completed_quantity και remains δίνονται μόνο ως παράδειγμα δομής. Ο πάροχος μπορεί να χρησιμοποιεί progress, start_count, balance ή άλλα ονόματα. Το μειονέκτημα της προσέγγισης GET είναι ότι ορισμένα API δέχονται έλεγχο κατάστασης μόνο μέσω POST.

Παράδειγμα αιτήματος POST και μαζικού ελέγχου

Αίτημα POST κατάστασης μίας παραγγελίας

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

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

Μαζικό αίτημα ενεργών παραγγελιών

Αν το API υποστηρίζει μαζικό έλεγχο, στείλτε πολλά ID με ένα αίτημα:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

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

Πώς να ορίζετε το polling για το processing

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

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

• Μετά τη δημιουργία της παραγγελίας μην ελέγχετε αμέσως την κατάσταση πολλές φορές συνεχόμενα: η υπηρεσία μπορεί να χρειάζεται χρόνο για την τοποθέτηση σε ουρά.
• Σε επαναλαμβανόμενο processing αυξάνετε το διάστημα μεταξύ των αιτημάτων, αντί να διατηρείτε σταθερή συχνότητα.
• Προσθέστε μια μικρή τυχαία απόκλιση στον χρόνο εκκίνησης των εργασιών, ώστε οι παραγγελίες να μην ερωτούν το API ταυτόχρονα.
• Αν ο πάροχος μεταδίδει Retry-After ή παρόμοια σύσταση, χρησιμοποιήστε την κατά προτεραιότητα.
• Για παραγγελίες με webhooks διατηρήστε έλεγχο polling: η ειδοποίηση μπορεί να μην φτάσει.

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

Ποιους χρόνους να αποθηκεύετε για τον έλεγχο του processing

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

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

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

Τι να κάνετε αν το processing δεν αλλάζει

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

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

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

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

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

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

Σε 429 λάβετε υπόψη το Retry-After, αν η κεφαλίδα έχει μεταδοθεί. Σε προσωρινά σφάλματα δικτύου και 5xx αυξήστε την παύση μεταξύ των προσπαθειών. Σε σφάλμα εξουσιοδότησης, υπογραφής ή δικαιωμάτων πρόσβασης μην κάνετε συχνές επαναλήψεις: πρέπει να ελέγξετε το κλειδί, τη διάρκεια ισχύος του token, τους περιορισμούς IP και τις ρυθμίσεις πρόσβασης.

Αν το API επέστρεψε HTTP 200, αλλά το JSON δεν αναλύεται ή στην απάντηση δεν υπάρχουν order_id και status, αποθηκεύστε ολόκληρο το σώμα της απάντησης και σημειώστε τον έλεγχο ως μη έγκυρο. Μην αντικαθιστάτε την απουσία κατάστασης με completed, canceled ή processing.

Πότε να σταματάτε τα αυτόματα επαναληπτικά αιτήματα

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

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

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

Πώς να δέχεστε την τελική κατάσταση μετά το processing

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

• new και pending μπορούν να μεταβούν σε processing, canceled ή failed.
• processing μπορεί να μεταβεί σε completed, partial, canceled ή failed.
• Το partial δεν πρέπει να θεωρείται αυτόματα completed.
• Τα completed, canceled και failed συνήθως θεωρούνται τελικά και εμποδίζουν την αυτόματη επιστροφή πίσω.
• Άγνωστη κατάσταση ή μη επιτρεπτή μετάβαση απαιτούν ξεχωριστό έλεγχο.

Ο αυστηρός πίνακας μεταβάσεων έχει επίσης μειονέκτημα: ο πάροχος μπορεί να προσθέσει μια έγκυρη νέα κατάσταση. Γι' αυτό αποθηκεύετε την αρχική κατάσταση και μην την αντικαθιστάτε με την εσωτερική ταξινόμηση.

Πώς να επεξεργάζεστε το partial και το υπόλοιπο της παραγγελίας

Το partial σημαίνει ότι έχει επιβεβαιωθεί μόνο μέρος του αρχικού όγκου. Στην απάντηση του API μπορεί να υπάρχει η πραγματικά εκτελεσμένη ποσότητα, το υπόλοιπο, η αιτία και δεδομένα αποζημίωσης. Αποθηκεύστε αυτές τις τιμές ξεχωριστά: ο αρχικός όγκος της παραγγελίας δεν πρέπει να αντικαθίσταται από την εκτελεσμένη ποσότητα.

Ένα παράδειγμα τελικής απάντησης μπορεί να μοιάζει έτσι:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

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

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

Τα webhooks δεν αντικαθιστούν τον έλεγχο ελέγχου

Το webhook επιτρέπει την ενημέρωση της κάρτας παραγγελίας αμέσως μετά το γεγονός, χωρίς αναμονή για το επόμενο polling. Στον χειριστή βρείτε την παραγγελία βάσει του εξωτερικού ID, ελέγξτε την υπογραφή ή το μυστικό, αποθηκεύστε το ID του γεγονότος και εφαρμόστε τη μετάβαση μόνο αφού ελέγξετε την επιτρεπτότητα.

Η επαναλαμβανόμενη παράδοση webhook πρέπει να είναι ασφαλής: το ίδιο γεγονός δεν πρέπει να θεωρείται νέα αλλαγή. Τα γεγονότα μπορεί επίσης να φτάσουν εκτός σειράς, γι' αυτό μην επαναφέρετε μια τελική παραγγελία μόνο βάσει καθυστερημένου processing.

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

Τι να εμφανίζετε στον πελάτη κατά το processing και το κόλλημα

Στη διεπαφή δεν χρειάζεται να εμφανίζεται ολόκληρο το τεχνικό JSON. Για το processing αρκεί η κατάσταση «η παραγγελία βρίσκεται σε επεξεργασία». Αν το API μετέδωσε αξιόπιστη πρόοδο, εμφανίστε τον επιβεβαιωμένο όγκο ξεχωριστά από τον αρχικό και μην τον παρουσιάζετε ως τελικό αποτέλεσμα.

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

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

Ποιες εγγραφές χρειάζονται στο αρχείο καταγραφής επεξεργασίας

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

Μην καταγράφετε στα κοινά αρχεία καταγραφής κλειδιά API, tokens, υπογραφές και άλλα μυστικά. Περιορίστε την πρόσβαση στις ακατέργαστες απαντήσεις: μπορεί να περιέχουν δεδομένα που δεν πρέπει να βρίσκονται στη διεπαφή υποστήριξης.

Πριν από την εκκίνηση ελέγξτε σενάρια με επαναλαμβανόμενο processing, απουσία προόδου, χρονικό όριο, 429, σφάλμα 5xx, μη έγκυρο JSON, καθυστερημένο webhook, duplicate-webhook, partial, canceled και άγνωστη κατάσταση. Η δοκιμαστική λειτουργία είναι χρήσιμη για τη δομή της ενσωμάτωσης, αλλά το μειονέκτημά της είναι ότι μπορεί να μην αναπαράγει τις πραγματικές ουρές και καθυστερήσεις του API παραγωγής.