Verarbeitung des Status „in Bearbeitung" bei der Bestellprüfung über die API

Was processing in der API-Antwort bedeutet

Der Status processing, in_progress oder ein anderer gleichwertiger Zustand bedeutet, dass der Anbieter die Bestellung in Bearbeitung genommen, aber das Ergebnis noch nicht festgehalten hat. Bei Promotion-Dienstleistungen kann das eine Linkprüfung, das Warten in der Warteschlange, den Start der Aufgabe oder die schrittweise Auslieferung des bestellten Volumens bedeuten.

Processing bestätigt keine erfolgreiche Ausführung und bedeutet keinen Fehler. Danach kann die Bestellung in completed, partial, canceled oder failed übergehen. Solange der Anbieter einen Zwischenstatus zurückgibt, erstellen Sie keine erneute Anfrage für denselben Link und dasselbe Volumen.

HTTP 200 mit dem Status processing bedeutet eine erfolgreiche API-Antwort, nicht den erfolgreichen Abschluss der Bestellung. Diese Ereignisse müssen getrennt gespeichert und verarbeitet werden.

Welche Daten für die Bestellprüfung benötigt werden

Für das Polling wird die externe Bestell-ID benötigt, die der Anbieter bei der Erstellung zurückgegeben hat. Speichern Sie sie zusammen mit der internen ID, dem ursprünglichen Volumen, den Dienstparametern, dem Link, der Erstellungszeit und der ursprünglichen API-Antwort. Eine Suche nach Kanalname, Link oder Volumen ist unzuverlässig: Solche Werte können bei mehreren Anfragen übereinstimmen.

Wenn nach der Erstellung ein Timeout auftritt, senden Sie die Anfrage nicht automatisch erneut. Der Anbieter könnte die Anfrage angenommen haben, während die Antwort unterwegs verloren ging. Nutzen Sie zunächst die Methode zur Bestellsuche, falls sie in der Dokumentation vorhanden ist, oder geben Sie den Fall zur Prüfung weiter.

Der Nachteil, nur den aktuellen Status zu speichern, besteht darin, dass bei einem Streitfall nicht rekonstruiert werden kann, wann die Bestellung in processing übergegangen ist, ob es Fortschritt gab und welche Antworten zuvor eingegangen sind.

Beispiel einer Statusabfrage über curl

Die genaue Adresse, die Autorisierungsmethode und die Feldnamen entnehmen Sie der Dokumentation des Anbieters. Unten ist eine Vorlage gezeigt: Werte in spitzen Klammern müssen durch die Daten der jeweiligen API ersetzt werden.

GET-Anfrage für eine einzelne Bestellung

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

-H "Authorization: Bearer " \

-H "Accept: application/json"

Beispielantwort:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

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

}

Die Felder completed_quantity und remains sind nur als Beispiel für die Struktur angegeben. Der Anbieter kann progress, start_count, balance oder andere Namen verwenden. Der Nachteil des GET-Ansatzes besteht darin, dass ein Teil der APIs die Statusprüfung nur über POST akzeptiert.

Beispiel einer POST-Anfrage und der Stapelprüfung

POST-Anfrage für den Status einer einzelnen Bestellung

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

-H "Authorization: Bearer " \

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

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

Übergeben Sie den API-Schlüssel nicht in der URL-Zeile. Anfrageadressen landen in Proxy-Protokollen, Analysesystemen, dem Browserverlauf und technischen Logs. Der Nachteil von POST besteht darin, dass er sich schwerer manuell über die Adresszeile prüfen lässt, aber das ist kein Grund, das Geheimnis in die URL zu verschieben.

Stapelanfrage für aktive Bestellungen

Wenn die API eine Stapelprüfung unterstützt, senden Sie mehrere IDs in einer Anfrage:

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

-H "Authorization: Bearer " \

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

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

Ordnen Sie die Antwort der internen Bestellung anhand der externen ID zu, nicht anhand der Position des Elements im Array. Der Nachteil der Stapelprüfung: Der Anbieter gibt möglicherweise nicht alle Bestellungen zurück, begrenzt die Listengröße oder meldet einen Fehler nur für eine ID.

Wie das Polling für processing festgelegt wird

Planen Sie nach der ersten processing-Antwort die nächste Prüfung in die Warteschlange ein. Wählen Sie das Intervall nach der API-Dokumentation, den Ratenbegrenzungen und der Art der Dienstleistung. Bei Aufgaben, deren Status sich schnell ändert, ist eine häufigere Prüfung am Anfang zulässig. Bei schrittweiser Promotion liefern ständige kurze Anfragen in der Regel keine neuen Informationen.

Ein praktisches Schema ist, die Pause nach gleichbleibenden processing-Antworten zu verlängern. Die erste Prüfung erfolgt nach einer Startverzögerung, dann wächst das Intervall bis zu einem festgelegten Maximum. Wenn die API Fortschritt oder eine neue Aktualisierungszeit zurückgibt, kann die Zählung ab dieser Änderung beginnen.

• Prüfen Sie den Status nach der Erstellung der Bestellung nicht sofort viele Male hintereinander: Der Dienst benötigt möglicherweise Zeit für die Einreihung in die Warteschlange.
• Bei wiederholtem processing verlängern Sie das Intervall zwischen den Anfragen, statt eine konstante Frequenz beizubehalten.
• Fügen Sie eine kleine zufällige Abweichung zur Startzeit der Aufgaben hinzu, damit Bestellungen die API nicht gleichzeitig abfragen.
• Wenn der Anbieter Retry-After oder eine ähnliche Empfehlung übermittelt, verwenden Sie diese vorrangig.
• Bei Bestellungen mit Webhooks behalten Sie ein Kontroll-Polling bei: Eine Benachrichtigung kann verloren gehen.

Der Nachteil seltenen Pollings: Die Oberfläche zeigt möglicherweise einen alten Status nach der tatsächlichen Fertigstellung. Der Nachteil zu häufigen Pollings: das Risiko, an API-Limits zu stoßen, 429 zu erhalten und unnötige Last zu erzeugen.

Welche Zeiten zur Kontrolle von processing gespeichert werden sollten

Um normales Ausführen von einem Hängen zu unterscheiden, reicht ein einzelner aktueller Status nicht aus. Speichern Sie für jede aktive Bestellung die Erstellungszeit, den ersten Erhalt von processing, die letzte erfolgreiche API-Antwort, die letzte Änderung des externen Status und die letzte Änderung des Fortschritts.

Ebenso ist es sinnvoll, das ursprüngliche Volumen, das bestätigte ausgeführte Volumen, den Rest und den Originalstatus des Anbieters zu speichern. Wenn die API keinen Fortschritt liefert, ist das kein Grund, die Bestellung als hängend zu betrachten: Orientieren Sie sich an der Zeit der letzten Antwort und dem erwarteten Bearbeitungszeitraum, falls dieser in den Dienstbedingungen angegeben ist.

Die maximale Wartezeit darf nicht für alle Dienstleistungen mit einer einzigen Zahl festgelegt werden. Verwenden Sie die Frist, die der Anbieter für die jeweilige Dienstleistung angibt, mit einem internen Puffer für Warteschlange und Datenaktualisierung. Wenn keine Frist angegeben ist, legen Sie eine eigene Regel für jede Dienstkategorie fest und überprüfen Sie diese anhand der Historie der tatsächlichen Bearbeitung.

Was zu tun ist, wenn sich processing nicht ändert

Langes processing beweist keinen Fehler. Prüfen Sie zunächst, ob erfolgreiche API-Antworten eingegangen sind, ob sich completed_quantity oder remains geändert haben, ob Webhooks vorlagen und ob sich die Dienstregeln geändert haben. Das Ausbleiben sichtbaren Wachstums kann an der Verzögerung der Plattformstatistik liegen oder daran, dass der Anbieter den Fortschritt erst am Ende aktualisiert.

Wenn die interne Wartefrist überschritten ist, stornieren Sie die Bestellung nicht automatisch. Führen Sie eine außerplanmäßige Statusprüfung durch, fordern Sie die Daten über eine separate Methode an, falls eine vorgesehen ist, und prüfen Sie die Historie der Benachrichtigungen. Wenn der Anbieter weiterhin processing bestätigt, überführen Sie die Bestellung in den internen Zustand „Prüfung erforderlich", behalten aber den externen Status ohne Ersetzung bei.

• Halten Sie die Zeit der letzten bestätigten Antwort und die gesamte API-Antwort fest.
• Prüfen Sie, ob sich der Fortschritt seit der vorherigen Abfrage geändert hat.
• Reduzieren Sie die Frequenz automatischer Anfragen nach Erreichen der internen Schwelle.
• Übergeben Sie dem Support die externe ID, den Link, die Dienstparameter, die Statushistorie und technische Fehler.
• Starten Sie den Rest nicht erneut, bevor der Anbieter antwortet oder ein eindeutiger Endstatus vorliegt.

Der Nachteil der manuellen Prüfung: Die Bestellung erfordert die Aufmerksamkeit des Supports. Aber eine automatische Stornierung oder ein Duplikat ist gefährlicher: Die Ausführung kann beim Anbieter weiterlaufen.

Wie ein Anfragefehler vom Bestellstatus getrennt wird

Ein Netzwerkfehler, ein Timeout, HTTP 429 und eine 5xx-Antwort teilen den Zustand der Bestellung selbst nicht mit. Sie bedeuten nur, dass kein neuer verlässlicher Status abgerufen werden konnte. Belassen Sie in dieser Situation den letzten bestätigten Status, protokollieren Sie den technischen Fehler und planen Sie eine neue Prüfung.

Bei 429 berücksichtigen Sie Retry-After, falls der Header übermittelt wurde. Bei temporären Netzwerkfehlern und 5xx verlängern Sie die Pause zwischen den Versuchen. Bei einem Fehler der Autorisierung, Signatur oder Zugriffsrechte setzen Sie keine häufigen Wiederholungen an: Der Schlüssel, die Gültigkeitsdauer des Tokens, IP-Beschränkungen und Zugriffseinstellungen müssen geprüft werden.

Wenn die API HTTP 200 zurückgibt, aber das JSON nicht geparst werden kann oder in der Antwort order_id und status fehlen, speichern Sie den Antworttext vollständig und markieren Sie die Prüfung als fehlerhaft. Ersetzen Sie das Fehlen eines Status nicht durch completed, canceled oder processing.

Wann automatische Wiederholungsanfragen beendet werden

Polling darf nicht endlos sein. Begrenzen Sie die Anzahl technischer Wiederholungen für temporäre Fehler und kontrollieren Sie separat die Gesamtdauer, in der sich die Bestellung in processing befindet. Nach Erschöpfung des Retry-Limits überführen Sie die Prüfaufgabe in die Klärungswarteschlange, statt jede Minute neue Anfragen ohne Ergebnis zu erstellen.

Eine Wiederholung der Statusabfrage ist in der Regel sicher, wenn die Methode nur Daten liest. Methoden zum Erstellen, Stornieren, Aufladen, Neustarten und Erstatten dürfen nach einem Timeout nicht mechanisch wiederholt werden. Ohne idempotenten Schlüssel oder ausdrückliche Bestätigung des Anbieters kann eine solche Wiederholung die Bestellung zweimal ändern.

Der Nachteil der Begrenzung von Retries besteht darin, dass ein Teil der Aktualisierungen zur manuellen Aufgabe wird. Endlose Retries sind schlimmer: Sie verschleiern einen Fehler, verbrauchen Limits und erschweren die Auswertung der Logs.

Wie der Endstatus nach processing angenommen wird

Lassen Sie keinen Rückübergang von completed zu processing aufgrund einer verspäteten Polling-Antwort oder eines alten Webhooks zu. Vergleichen Sie bei jeder Aktualisierung die Ereigniszeit des Anbieters, die Versionsnummer, falls vorhanden, und den aktuellen internen Zustand.

• new und pending können in processing, canceled oder failed übergehen.
• processing kann in completed, partial, canceled oder failed übergehen.
• partial sollte nicht automatisch als completed betrachtet werden.
• completed, canceled und failed gelten in der Regel als final und blockieren den automatischen Rückübergang.
• Ein unbekannter Status oder ein unzulässiger Übergang erfordert eine separate Prüfung.

Auch eine starre Übergangstabelle hat einen Nachteil: Der Anbieter kann einen korrekten neuen Zustand hinzufügen. Speichern Sie daher den Originalstatus und überschreiben Sie ihn nicht mit der internen Klassifizierung.

Wie partial und der Bestellrest verarbeitet werden

Partial bedeutet, dass nur ein Teil des ursprünglichen Volumens bestätigt ist. In der API-Antwort können die tatsächlich ausgeführte Menge, der Rest, der Grund und Daten zur Kompensation enthalten sein. Speichern Sie diese Werte getrennt: Das ursprüngliche Bestellvolumen darf nicht durch die ausgeführte Menge ersetzt werden.

Ein Beispiel einer finalen Antwort kann so aussehen:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

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

}

Stellen Sie zunächst fest, was die API genau bestätigt: ob die Rückerstattung bereits durchgeführt wurde, ob sie nur geplant ist, ob der Rest storniert wurde oder ob eine Support-Anfrage erforderlich ist. Wenn kein Feld zur Rückerstattung vorhanden ist, betrachten Sie den Rest nicht automatisch als kompensiert.

Starten Sie den nicht ausgeführten Teil nicht ohne separate Entscheidung neu. Der Anbieter kann die Abrechnung noch abschließen, die Plattformstatistik kann sich mit Verzögerung aktualisieren, und eine erneute Anfrage kann eine doppelte Promotion erzeugen. Der Nachteil des Wartens auf die Bestätigung: Der Rest wird nicht sofort geschlossen, dafür entsteht keine zusätzliche Bestellung.

Webhooks ersetzen keine Kontrollprüfung

Ein Webhook ermöglicht es, die Bestellkarte sofort nach dem Ereignis zu aktualisieren, ohne auf das nächste Polling zu warten. Suchen Sie im Handler die Bestellung anhand der externen ID, prüfen Sie die Signatur oder das Secret, speichern Sie die Ereignis-ID und wenden Sie den Übergang erst nach Prüfung der Zulässigkeit an.

Eine wiederholte Zustellung eines Webhooks muss sicher sein: Dasselbe Ereignis darf nicht als neue Änderung betrachtet werden. Ereignisse können auch außer der Reihenfolge eintreffen, daher dürfen Sie eine finale Bestellung nicht allein aufgrund eines verspäteten processing zurücksetzen.

Ein Kontroll-Polling ist auch bei stabilen Webhooks erforderlich. Der Nachteil von Webhooks ist die aufwendigere Einrichtung: Es werden ein erreichbarer Handler, Schutz vor gefälschten Anfragen, Deduplizierung und ein Ereignisprotokoll benötigt.

Was dem Kunden bei processing und Hängen angezeigt werden sollte

In der Oberfläche müssen nicht alle technischen JSON-Daten ausgegeben werden. Für processing reicht der Zustand „Bestellung in Bearbeitung". Wenn die API einen verlässlichen Fortschritt übermittelt hat, zeigen Sie das bestätigte Volumen getrennt vom ursprünglichen an und geben Sie es nicht als Endergebnis aus.

Für eine Bestellung, die die interne Kontrollfrist überschritten hat, verwenden Sie einen verständlichen Zustand wie „Ausführung wird geprüft". Melden Sie keine Stornierung, Rückerstattung oder vollständige Fertigstellung, solange dies nicht durch die Antwort des Anbieters bestätigt ist.

Benachrichtigungen sind sinnvoll bei Annahme der Bestellung, finaler Ausführung, partial, Stornierung, Fehler und erforderlicher Prüfung. Nachrichten nach jedem Polling erzeugen Lärm und helfen dem Kunden nicht, den tatsächlichen Zustand der Anfrage zu verstehen.

Welche Einträge im Verarbeitungsprotokoll benötigt werden

Die Historie der Antworten hilft, hängendes processing, einen verlorenen Webhook, einen Streitfall bei teilweiser Ausführung und eine Abweichung zwischen Oberfläche und API zu klären. Speichern Sie für jede Anfrage die externe ID, die Quelle der Aktualisierung, die Zeit der Anfrage und der Antwort, den HTTP-Code, den Originalstatus, den normalisierten Status, den Fortschritt, den Rest und den Text des technischen Fehlers.

Schreiben Sie keine API-Schlüssel, Tokens, Signaturen und andere Geheimnisse in gewöhnliche Logs. Beschränken Sie den Zugriff auf Rohantworten: Sie können Daten enthalten, die nicht in der Support-Oberfläche erscheinen dürfen.

Prüfen Sie vor dem Start Szenarien mit wiederholtem processing, ausbleibendem Fortschritt, Timeout, 429, 5xx-Fehler, fehlerhaftem JSON, verspätetem Webhook, Duplikat-Webhook, partial, canceled und unbekanntem Status. Der Testmodus ist für die Struktur der Integration nützlich, sein Nachteil besteht jedoch darin, dass er reale Warteschlangen und Verzögerungen der Produktions-API möglicherweise nicht nachbildet.