Έλεγχος υπολοίπου μέσω API πριν από μαζική εκκίνηση παραγγελιών

Γιατί να ζητάτε το υπόλοιπο πριν από την εκκίνηση της ουράς

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

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

Συγκρίνετε τον προϋπολογισμό της ουράς με το πεδίο του διαθέσιμου υπολοίπου, όχι με το συνολικό ποσό στον λογαριασμό.

Πώς μοιάζει η απόκριση της μεθόδου υπολοίπου

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

Το αίτημα μπορεί να μοιάζει έτσι:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Απόκριση:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Σε αυτό το παράδειγμα το total είναι όλα τα κεφάλαια του λογαριασμού, το available είναι τα χρήματα για νέες παραγγελίες, το reserved είναι το ποσό για προηγούμενες πράξεις. Ο έλεγχος συμφωνεί: 125.80 μείον 41.30 ισούται με 84.50. Το πεδίο currency καθορίζει τη μονάδα υπολογισμού, ενώ το updated_at βοηθά να καταλάβετε πόσο πρόσφατα είναι τα δεδομένα.

Πώς να ερμηνεύετε τα available και reserved

Το πεδίο available χρησιμοποιείται για την απόφαση εκκίνησης. Αν η ουρά κοστίζει 80.00 και το available είναι 84.50, τα κεφάλαια επαρκούν μόνο υπό την προϋπόθεση ότι το API δεν θα προσθέσει ξεχωριστή προμήθεια ή δεν θα επανυπολογίσει την τιμή τη στιγμή της δημιουργίας της αίτησης. Το πεδίο reserved δεν προστίθεται στο διαθέσιμο υπόλοιπο: αυτό το ποσό είναι ήδη δεσμευμένο.

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

• Το total είναι κατάλληλο για επαλήθευση με το ιστορικό καταθέσεων και χρεώσεων;
• Το available είναι κατάλληλο για την έγκριση εκκίνησης μιας νέας ουράς;
• Το reserved δείχνει πόσα κεφάλαια είναι ήδη δεσμευμένα για ενεργές πράξεις;
• Το currency δεν πρέπει να αγνοείται ακόμη και όταν εργάζεστε με έναν μόνο λογαριασμό;
• Το updated_at είναι χρήσιμο για το αρχείο καταγραφής και τη διάγνωση παρωχημένης απόκρισης.

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

Ελέγξτε τη μορφή των ποσών στην τεκμηρίωση του API

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

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

Ένα άλλο συνηθισμένο συμβόλαιο είναι οι ακέραιες ελάχιστες μονάδες. Τότε η απόκριση μπορεί να περιέχει "available_minor": 8450 και "currency": "USD", ενώ η τιμή της παραγγελίας — "price_minor": 1250. Μέσα σε ένα τέτοιο API το 8450 σημαίνει 84.50, αν οι κανόνες του νομίσματος προβλέπουν δύο δεκαδικές θέσεις. Η διαίρεση της τιμής με το 100 επιτρέπεται μόνο όταν αυτό αναφέρεται ρητά στην τεκμηρίωση.

Μην αναμιγνύετε νομίσματα και μορφές τιμών

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

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

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

Υπολογίστε τον προϋπολογισμό της ουράς πριν από το πρώτο αίτημα

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

Ας υποθέσουμε ότι στην ουρά υπάρχουν τρεις παραγγελίες. Το API υπολογισμού τιμής επέστρεψε για αυτές 18.40, 27.15 και 31.60 στο ίδιο νόμισμα που αναφέρεται στο balance.currency. Ο προϋπολογισμός ισούται με 77.15. Αν το balance.available είναι 84.50, μετά την προγραμματισμένη εκκίνηση απομένουν 7.35. Αν το available είναι 76.90, δεν μπορείτε να εκκινήσετε ολόκληρη την ουρά.

1. Λάβετε τις τιμές με βάση τις πραγματικές παραμέτρους κάθε παραγγελίας.
2. Αθροίστε τα τελικά κόστη, χωρίς να αλλάξετε τη μορφή και το νόμισμά τους.
3. Συγκρίνετε τον προϋπολογισμό με το available από μια πρόσφατη απόκριση υπολοίπου.
4. Εφόσον το υπόλοιπο επαρκεί, καταγράψτε το ποσό ως τοπική δέσμευση εκκίνησης.
5. Μετά τη δημιουργία κάθε αίτησης, μειώστε την τοπική δέσμευση κατά το επιβεβαιωμένο κόστος.

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

Κάντε δεύτερο έλεγχο αμέσως πριν από την αποστολή

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

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

Ένα αίτημα για ολόκληρη την εκκίνηση μειώνει το φόρτο στο API, αλλά το μειονέκτημά του είναι ότι το διαθέσιμο υπόλοιπο μπορεί να αλλάξει όσο μια μεγάλη ουρά εξακολουθεί να επεξεργάζεται.

Πώς να εκκινείτε την ουρά όταν τα κεφάλαια δεν επαρκούν

Αν το available είναι μικρότερο από τον προϋπολογισμό, μην στέλνετε όλα τα αιτήματα ελπίζοντας ότι μέρος τους θα περάσει. Χωρίστε την ουρά σε πακέτα των οποίων το κόστος χωρά στο διαθέσιμο όριο. Στο παράδειγμα με υπόλοιπο 76.90 μπορείτε να στείλετε τις δύο πρώτες παραγγελίες για 45.55 και μετά να σταματήσετε: η τρίτη για 31.60 απαιτεί νέο έλεγχο.

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

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

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

Προστατέψτε τον προϋπολογισμό κατά την παράλληλη αποστολή

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

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

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

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

Χρησιμοποιήστε τη δέσμευση του API, αν προβλέπεται

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

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

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

Διαχωρίστε το σφάλμα υπολοίπου από το μηδενικό υπόλοιπο

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

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

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

Μη δημιουργείτε διπλότυπα μετά από χρονικό όριο

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

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

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

Τι να αποθηκεύετε στο αρχείο καταγραφής εκκίνησης

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

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

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

Δοκιμάστε το σχήμα σε μια μικρή ουρά

Πριν από μια μεγάλη εκκίνηση εκτελέστε ένα σύντομο σενάριο: λάβετε το balance, ζητήστε τις τελικές τιμές, δημιουργήστε ένα περιορισμένο πακέτο, ζητήστε ξανά το balance και συγκρίνετε την αναμενόμενη μεταβολή των available και reserved με την πραγματική απόκριση. Έτσι μπορείτε να παρατηρήσετε πότε η υπηρεσία δεσμεύει το ποσό και πότε το χρεώνει οριστικά.

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