Kontostand-Prüfung über die API vor dem massenhaften Start von Bestellungen

Warum der Kontostand vor dem Start der Warteschlange abgefragt werden sollte

Ein massenhafter Start von Bestellungen ohne aktuelle Kontostandsprüfung führt zu teilweisen Ablehnungen: Die ersten Anfragen werden erstellt, die folgenden erhalten einen Fehler wegen unzureichender Mittel. Am schwierigsten ist es, eine solche Situation bei parallelem Versand, verschiedenen Dienstleistungen und mehreren Prozessen zu analysieren, die mit einem Konto arbeiten.

Für den Start ist nicht das Gesamtvolumen der Einzahlungen und nicht der buchhalterische Kontostand im persönlichen Bereich wichtig. Benötigt wird der Betrag, den der Dienst zum Zeitpunkt der Erstellung einer neuen Bestellung abbuchen darf. Geld für aktive Anfragen kann sich bereits in der Reservierung befinden, obwohl die endgültige Abbuchung noch nicht in der Transaktionshistorie erscheint.

Vergleichen Sie das Budget der Warteschlange mit dem Feld des verfügbaren Restbetrags, nicht mit dem Gesamtbetrag auf dem Konto.

Wie die Antwort der Kontostandsmethode aussieht

Die Feldnamen legt die Dokumentation der jeweiligen Plattform fest, aber ein praktischer Vertrag der Kontostandsmethode gibt üblicherweise total, available, reserved, currency und updated_at zurück. Unten ist ein Beispiel einer Struktur angeführt, die als Orientierung bei der Integration dienen kann. Dies ist keine universelle Antwort für jeden Dienst, sondern ein Beispiel eines verständlichen Datenschemas.

Die Anfrage kann so aussehen:

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

Antwort:

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

In diesem Beispiel ist total das gesamte Guthaben des Kontos, available das Geld für neue Bestellungen, reserved der Betrag für zuvor erstellte Vorgänge. Die Prüfung geht auf: 125.80 minus 41.30 ergibt 84.50. Das Feld currency legt die Berechnungseinheit fest, und updated_at hilft zu verstehen, wie aktuell die Daten sind.

Wie available und reserved zu interpretieren sind

Das Feld available wird für die Entscheidung über den Start verwendet. Wenn die Warteschlange 80.00 kostet und available 84.50 beträgt, reichen die Mittel nur unter der Bedingung, dass die API keine separate Provision hinzufügt oder den Preis im Moment der Erstellung der Anfrage nicht neu berechnet. Das Feld reserved wird nicht zum verfügbaren Restbetrag hinzugerechnet: Dieser Betrag ist bereits belegt.

reserved kann die Kosten von Bestellungen mit den Status processing, pending oder review enthalten — der genaue Umfang hängt von den Regeln der Plattform ab. Manchmal wird die Reservierung nach einer Stornierung, teilweisen Ausführung oder manuellen Prüfung freigegeben. Daher kann man sie nur als zusätzliche Abgleichung selbst anhand der Bestellliste berechnen.

• total eignet sich für den Abgleich mit der Historie von Einzahlungen und Abbuchungen;
• available eignet sich für die Zulassung einer neuen Warteschlange zum Start;
• reserved zeigt, wie viele Mittel bereits für aktive Vorgänge blockiert sind;
• currency darf selbst bei der Arbeit mit nur einem Konto nicht ignoriert werden;
• updated_at ist nützlich für das Journal und die Diagnose einer veralteten Antwort.

Eine Antwort nur mit dem Feld balance ist einfacher zu verarbeiten, hat aber einen Nachteil: Man kann nicht verstehen, ob dieses Geld sofort verfügbar ist oder ein Teil des Betrags bereits für andere Bestellungen einbehalten wurde.

Prüfen Sie das Format der Beträge in der API-Dokumentation

Im Beispiel sind die Beträge als Zeichenketten übergeben: "84.50", nicht als Zahl 84.5. Ein solches Format bewahrt den genauen Wert, den der Dienst zurückgegeben hat. Wenn die API Zeichenketten mit Dezimalpunkt verwendet, sollte man sie nicht sofort in Gleitkommazahlen umwandeln und Vergleiche über float durchführen.

Zum Beispiel kann Ihre Berechnung 84.499999 statt der erwarteten 84.50 ergeben. An der Budgetgrenze kann dies eine Warteschlange fälschlicherweise durchlassen oder umgekehrt stoppen. Für Operationen mit dezimalen Zeichenkettenwerten verwenden Sie einen Dezimaldatentyp, der die Genauigkeit eines festen Bruchteils unterstützt.

Ein weiterer verbreiteter Vertrag sind ganzzahlige kleinste Einheiten. Dann kann die Antwort "available_minor": 8450 und "currency": "USD" enthalten, und der Preis der Bestellung — "price_minor": 1250. Innerhalb einer solchen API bedeutet 8450 84.50, wenn die Währungsregeln zwei Nachkommastellen vorsehen. Das Teilen des Werts durch 100 ist nur zulässig, wenn dies ausdrücklich in der Dokumentation angegeben ist.

Vermischen Sie keine Währungen und Preisformate

Vergleichen Sie vor der Berechnung der Warteschlange die currency aus dem Kontostand mit der Währung der Preismethode oder der Antwort bei der Erstellung der Bestellung. Wenn der Kontostand eine Währung zurückgibt und der Dienstkatalog eine andere, dürfen die Zahlen nicht direkt eingesetzt werden. Benötigt wird entweder eine Berechnung, die die Plattform selbst bereitstellt, oder eine separate bestätigte Konvertierungsmethode.

Eine vorläufige Konvertierung auf Ihrer Seite ist für die Planung praktisch, hat aber einen Nachteil: Der Dienst kann im Moment der Abbuchung einen anderen Kurs, eine Provision oder eine Rundungsregel anwenden. Zuverlässiger ist es, die Bestellung mit Parametern zu senden, für die die API die Endkosten in der Währung des Kontostands zurückgibt, oder den Preis unmittelbar vor der Erstellung berechnen zu lassen.

Wenn die Preismethode "price": "12.345" zurückgibt und der Kontostand Werte mit zwei Stellen speichert, klären Sie die Rundungsregel. Runden Sie nicht automatisch ab: Die tatsächliche Abbuchung kann höher ausfallen. Für die Zulassung der Warteschlange verwenden Sie genau den Betrag, den die API als Endkosten der Bestellung bezeichnet.

Berechnen Sie das Budget der Warteschlange vor der ersten Anfrage

Sammeln Sie vor dem Start alle Anfragen und berechnen Sie deren Kosten unter Berücksichtigung des Volumens, der gewählten Dienstleistung, der Region, zusätzlicher Optionen und der Provision, falls diese separat übergeben wird. Vergleichen Sie available nicht mit dem Basispreis aus der Oberfläche: In der API kann das Ergebnis von den Parametern der konkreten Bestellung abhängen.

Angenommen, in der Warteschlange stehen drei Bestellungen. Die Preisberechnungs-API hat für sie 18.40, 27.15 und 31.60 in derselben Währung zurückgegeben, die in balance.currency angegeben ist. Das Budget beträgt 77.15. Wenn balance.available 84.50 beträgt, bleiben nach dem geplanten Start 7.35 übrig. Wenn available 76.90 beträgt, darf die gesamte Warteschlange nicht gestartet werden.

1. Rufen Sie die Preise anhand der tatsächlichen Parameter jeder Bestellung ab.
2. Addieren Sie die Endkosten, ohne deren Format und Währung zu ändern.
3. Vergleichen Sie das Budget mit available aus einer frischen Kontostandsantwort.
4. Bei ausreichendem Restbetrag fixieren Sie den Betrag als lokale Startreserve.
5. Nach der Erstellung jeder Anfrage verringern Sie die lokale Reserve um die bestätigten Kosten.

Ein Puffer senkt das Risiko einer Ablehnung bei einer zusätzlichen Abbuchung, hat aber einen Nachteil: Ein Teil der verfügbaren Mittel bleibt ungenutzt, obwohl die Warteschlange vollständig hätte durchlaufen können.

Führen Sie eine zweite Prüfung unmittelbar vor dem Versand durch

Der bei der Vorbereitung der Kampagne abgerufene Kontostand verliert schnell an Aktualität. In der Zeit zwischen Berechnung und Start können ein anderer Operator, eine Automatisierung oder eine aktive Bestellung available und reserved verändern. Eine erneute Anfrage ist nach der Bildung der Warteschlange und unmittelbar vor der ersten Anfrage erforderlich.

Ein praktikables Schema besteht aus zwei Etappen: Zuerst die Preise abrufen und das Budget schätzen, dann balance erneut abfragen. Wenn der Wert von available gesunken und unter die berechnete Summe gefallen ist, wird die Warteschlange nicht vollständig versendet. Zwischen der abschließenden Prüfung und dem Start sollten keine anderen Abbuchungen vom selben Konto durchgeführt werden.

Eine einzige Anfrage für den gesamten Start verringert die Last auf die API, hat aber den Nachteil, dass sich der verfügbare Restbetrag ändern kann, während eine lange Warteschlange noch abgearbeitet wird.

Wie die Warteschlange bei unzureichenden Mitteln zu starten ist

Wenn available kleiner als das Budget ist, senden Sie nicht alle Anfragen in der Hoffnung, dass ein Teil durchgeht. Teilen Sie die Warteschlange in Pakete auf, deren Kosten in das verfügbare Limit passen. Im Beispiel mit einem Restbetrag von 76.90 können die ersten beiden Bestellungen für 45.55 gesendet werden, dann muss man anhalten: Die dritte für 31.60 erfordert eine erneute Prüfung.

Legen Sie die Reihenfolge der Anfragen beim Batching explizit fest. Man kann zuerst priorisierte Bestellungen senden oder Pakete mit ähnlichen Kosten bilden. Jede Variante hat einen Nachteil: Eine priorisierte Reihenfolge verschiebt weniger wichtige Positionen, und eine Sortierung nach Preis kann den ursprünglichen Kampagnenplan stören.

• Bilden Sie ein Paket mit einer Summe, die das aktuelle available nicht übersteigt.
• Erstellen Sie die Bestellungen aus dem Paket und speichern Sie deren Identifikatoren.
• Warten Sie auf Antworten oder prüfen Sie die Status der Vorgänge nach Zeitüberschreitungen.
• Legen Sie eine Pause ein, wenn die API-Limits oder die Regeln des Dienstes dies erfordern.
• Fragen Sie balance vor dem nächsten Paket erneut ab.

Orientieren Sie sich nach jedem Paket an der neuen API-Antwort und nicht nur am lokalen Abzug vom vorherigen Kontostand. Die lokale Berechnung ist für die Kontrolle nützlich, sieht aber keine Rückerstattungen, externen Abbuchungen und Neuberechnungen von Reservierungen.

Schützen Sie das Budget beim parallelen Versand

Bei der sequenziellen Verarbeitung reicht es, das lokale Limit nach der Bestätigung der Bestellung zu verringern. Bei einem parallelen Modell können zwei Worker gleichzeitig available 84.50 sehen und jeweils Ausgaben von 60.00 einplanen. Beide Entscheidungen wirken einzeln zulässig, überschreiten aber zusammen den verfügbaren Restbetrag.

Für den Schutz wird ein gemeinsamer Zähler der lokalen Reserve oder eine Warteschlange benötigt, auf die atomar zugegriffen wird. Vor dem Versand versucht der Worker, den Betrag der Bestellung in diesem Zähler zu belegen. Wenn das freie Limit nicht ausreicht, bleibt die Anfrage in Erwartung einer erneuten Kontostandsprüfung.

• Eine sequenzielle Warteschlange ist einfacher zu kontrollieren, startet aber langsamer.
• Paralleler Versand verkürzt die Startzeit, erfordert aber eine Sperrung des gemeinsamen Budgets.
• Lokale Reservierung verringert Konflikte, kann aber nach einem Ausfall eines Workers hängen bleiben.
• Reservierung auf der API-Seite ist zuverlässiger, aber nicht bei jeder Plattform verfügbar.

Wenn der Prozess vor dem Erhalt einer Antwort beendet wurde, darf die lokale Reserve nicht sofort als verbraucht oder frei betrachtet werden. Prüfen Sie zuerst anhand der externen Kennung oder mit der Methode der Vorgangssuche, ob die Bestellung erstellt wurde.

Nutzen Sie die API-Reservierung, falls sie vorgesehen ist

Einige APIs ermöglichen es, eine Reservierung für eine Reihe von Vorgängen zu erstellen oder eine Bestellung in zwei Schritten durchzuführen: Berechnung, Blockierung des Betrags, Bestätigung. In einem solchen Schema ist das Fenster zwischen Prüfung und Abbuchung kleiner, in dem ein anderer Prozess die Mittel des Kontos verbrauchen kann.

Wenn eine solche Methode vorhanden ist, speichern Sie die Kennung der Reservierung, ihren Betrag, die Währung, die Gültigkeitsdauer und den Status. Übergeben Sie diese Kennung dann bei der Erstellung von Bestellungen, wenn der API-Vertrag dies erfordert. Vergleichen Sie nach Abschluss der Warteschlange den ungenutzten Teil und die Tatsache der Aufhebung der Blockierung.

Eine API-Reservierung löst nicht alle Probleme: Sie kann eine kurze Gültigkeitsdauer haben, Provisionen nicht abdecken oder nach einem Bestätigungsfehler freigegeben werden. Eine lokale Reserve ist einfacher einzuführen, hat aber den Nachteil, dass sie nicht vor Ausgaben schützt, die außerhalb Ihrer Anwendung entstehen.

Trennen Sie einen Kontostandsfehler von einem Nullsaldo

Eine Antwort mit einem Fehlercode, eine Zeitüberschreitung oder eine Begrenzung der Anfragefrequenz bedeuten nicht, dass available gleich null ist. Setzen Sie nicht automatisch den letzten bekannten Wert ein, wenn von ihm ein großer Start abhängt. Ist es unmöglich, einen frischen Kontostand abzurufen, muss die Warteschlange pausiert werden.

Behandeln Sie die Ablehnung bei der Erstellung einer Bestellung gesondert. Sie kann mit unzureichenden Mitteln zusammenhängen, aber auch mit einer falschen Dienstleistungskennung, einem unzulässigen Volumen, einer Beschränkung für den Kanal oder einer Wiederholung eines Vorgangs. Speichern Sie den Code und den Text des Fehlers zusammen mit der externen Kennung der Anfrage.

• Bei einem Autorisierungsfehler aktualisieren Sie den Zugang und wiederholen Sie erst dann die Anfrage.
• Bei einem Anfragelimit halten Sie eine Pause gemäß den API-Regeln ein.
• Bei einer Zeitüberschreitung der Erstellung prüfen Sie zuerst, ob der Vorgang tatsächlich erschienen ist.
• Bei einem Fehler wegen unzureichender Mittel stoppen Sie das Paket und fragen Sie balance erneut ab.

Erzeugen Sie nach einer Zeitüberschreitung keine Duplikate

Eine Zeitüberschreitung bedeutet, dass Ihr Client keine Antwort erhalten hat, und nicht, dass der Server die Anfrage nicht verarbeitet hat. Ein erneuter Versand ohne Prüfung kann eine zweite Bestellung erstellen und das Geld erneut belegen. Besonders gefährlich ist dies in einer Warteschlange, in der eine automatische Wiederholung auf mehrere Versuche eingestellt ist.

Übergeben Sie eine eindeutige externe Kennung der Bestellung, wenn die API das Feld client_order_id, external_id oder idempotency_key unterstützt. Speichern Sie diese vor dem Versand der Anfrage. Suchen Sie nach einer Zeitüberschreitung den Vorgang anhand dieses Werts oder fragen Sie den Status anhand der zuvor erhaltenen Kennung ab.

Eine Wiederholung ohne Prüfung ist schneller, hat aber einen direkten Nachteil: Es sind doppelte Bestellungen, doppelte Reservierungen und Abweichungen zwischen Ihrer Budgetberechnung und den tatsächlichen Abbuchungen möglich.

Was im Startjournal zu speichern ist

Das Journal hilft, den Verlauf eines Massenvorgangs wiederherzustellen und zu erklären, warum ein bestimmtes Paket angehalten wurde. Speichern Sie für jeden Start die Zeit der beiden Prüfungen, total, available, reserved, currency, das berechnete Budget, die Größe der lokalen Reserve und die Liste der externen Kennungen der Anfragen.

Fixieren Sie für jeden Versuch der Erstellung die Kosten, den Antwortcode, die technische Kennung des Vorgangs und den endgültigen Status. Geheimnisse gelangen nicht ins Journal: Autorisierungstoken, API-Schlüssel, vollständige Anfrage-Header und personenbezogene Daten müssen maskiert oder vor der Aufzeichnung ausgeschlossen werden.

Vollständiges Logging ist beim Debugging praktisch, hat aber einen Nachteil: Ohne Filterung können Zugangsdaten und Kundeninformationen in den Speicher gelangen.

Prüfen Sie das Schema an einer kleinen Warteschlange

Führen Sie vor einem großen Start ein kurzes Szenario durch: balance abrufen, Endpreise abfragen, ein begrenztes Paket erstellen, balance erneut abfragen und die erwartete Änderung von available und reserved mit der tatsächlichen Antwort vergleichen. So lässt sich erkennen, wann der Dienst einen Betrag reserviert und wann er ihn endgültig abbucht.

Ein Testpaket garantiert nicht dasselbe Verhalten unter hoher Last: Es können Limits, parallele Prozesse oder Beschränkungen der konkreten Dienstleistung greifen. Teilen Sie daher in einer Massenwarteschlange den Start weiterhin in Pakete auf, prüfen Sie den verfügbaren Restbetrag zwischen ihnen und analysieren Sie jede Ablehnung separat.