Verwerking van de status ‘wordt uitgevoerd’ bij het controleren van een bestelling via de API

Wat processing betekent in het API-antwoord

De status processing, in_progress of een andere gelijkwaardige toestand betekent dat de leverancier de bestelling in behandeling heeft genomen, maar de uitkomst nog niet heeft vastgelegd. Voor promotiediensten kan dit een linkcontrole zijn, wachten op de wachtrij, het starten van een taak of het geleidelijk leveren van het bestelde volume.

Processing bevestigt geen succesvolle uitvoering en betekent geen fout. Daarna kan de bestelling overgaan naar completed, partial, canceled of failed. Zolang de leverancier een tussenstatus teruggeeft, maak dan geen nieuwe aanvraag aan voor dezelfde link en hetzelfde volume.

HTTP 200 met de status processing betekent een succesvol API-antwoord, niet een succesvolle afronding van de bestelling. Deze gebeurtenissen moeten afzonderlijk worden opgeslagen en verwerkt.

Welke gegevens zijn nodig om een bestelling te controleren

Voor polling is een extern bestel-ID nodig dat de leverancier bij het aanmaken heeft teruggegeven. Sla dit op samen met het interne ID, het oorspronkelijke volume, de serviceparameters, de link, het aanmaaktijdstip en het oorspronkelijke API-antwoord. Zoeken op kanaalnaam, link of volume is onbetrouwbaar: zulke waarden kunnen bij meerdere aanvragen overeenkomen.

Als na het aanmaken een time-out optreedt, verstuur de aanvraag dan niet automatisch opnieuw. De leverancier kan het verzoek hebben ontvangen, terwijl het antwoord onderweg verloren is gegaan. Gebruik eerst de methode om een bestelling op te zoeken, als die in de documentatie staat, of draag het geval over ter controle.

Het nadeel van alleen de huidige status opslaan is dat bij een geschil niet kan worden hersteld wanneer de bestelling naar processing ging, of er voortgang was en welke antwoorden eerder binnenkwamen.

Voorbeeld van een statusverzoek via curl

Haal het exacte adres, de autorisatiemethode en de veldnamen uit de documentatie van de leverancier. Hieronder staat een sjabloon: waarden tussen punthaken moeten worden vervangen door gegevens van de specifieke API.

GET-verzoek voor één bestelling

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

-H "Authorization: Bearer " \

-H "Accept: application/json"

Voorbeeld van een antwoord:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

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

}

De velden completed_quantity en remains zijn alleen als voorbeeld van de structuur gegeven. De leverancier kan progress, start_count, balance of andere namen gebruiken. Het nadeel van de GET-aanpak is dat een deel van de API's statuscontrole alleen via POST accepteert.

Voorbeeld van een POST-verzoek en batchcontrole

POST-verzoek voor de status van één bestelling

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

-H "Authorization: Bearer " \

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

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

Geef de API-sleutel niet door in de URL. Verzoekadressen belanden in proxylogs, analysesystemen, browsergeschiedenis en technische logs. Het nadeel van POST is dat het lastiger handmatig via de adresbalk te controleren is, maar dat is geen reden om het geheim naar de URL te verplaatsen.

Batchverzoek voor actieve bestellingen

Als de API batchcontrole ondersteunt, verstuur dan meerdere ID's in één verzoek:

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

-H "Authorization: Bearer " \

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

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

Koppel het antwoord aan de interne bestelling via het externe ID, niet via de positie van het element in de array. Nadeel van batchcontrole: de leverancier kan niet alle bestellingen teruggeven, de lijstgrootte beperken of alleen voor één ID een fout melden.

Hoe polling voor processing in te richten

Zet na het eerste processing-antwoord de volgende controle in de wachtrij. Kies het interval op basis van de API-documentatie, frequentielimieten en het karakter van de dienst. Voor taken waarbij de status snel verandert, is een frequentere controle in het begin acceptabel. Voor geleidelijke promotie leveren constante korte verzoeken meestal geen nieuwe informatie op.

Een praktisch schema is de pauze te verlengen na identieke processing-antwoorden. De eerste controle volgt na een startvertraging, daarna groeit het interval tot een vastgesteld maximum. Als de API voortgang of een nieuwe updatetijd teruggeeft, kan de telling vanaf die wijziging beginnen.

• Controleer de status na het aanmaken van een bestelling niet meteen vele malen achter elkaar: de dienst kan tijd nodig hebben om in de wachtrij te zetten.
• Verleng bij herhaald processing het interval tussen verzoeken in plaats van een constante frequentie aan te houden.
• Voeg een kleine willekeurige afwijking toe aan de starttijd van taken, zodat bestellingen de API niet tegelijk bevragen.
• Als de leverancier Retry-After of een vergelijkbare aanbeveling meegeeft, gebruik die dan als prioriteit.
• Laat voor bestellingen met webhooks een controle-polling actief: een melding kan niet aankomen.

Het nadeel van zeldzame polling is dat de interface na feitelijke afronding een oude status kan tonen. Het nadeel van te frequente polling is het risico op API-limieten, een 429 en extra belasting.

Welke tijden je moet opslaan om processing te controleren

Om normale uitvoering van een vastloper te onderscheiden is één huidige status niet genoeg. Sla voor elke actieve bestelling het aanmaaktijdstip op, de eerste keer dat processing werd ontvangen, het laatste succesvolle API-antwoord, de laatste wijziging van de externe status en de laatste wijziging van de voortgang.

Het is ook nuttig het oorspronkelijke volume, het bevestigde uitgevoerde volume, het restant en de originele status van de leverancier op te slaan. Als de API geen voortgang teruggeeft, is dat geen reden om de bestelling als vastgelopen te beschouwen: baseer je op het tijdstip van het laatste antwoord en de verwachte verwerkingsperiode, als die in de servicevoorwaarden staat.

De maximale wachttijd mag niet voor alle diensten met één getal worden ingesteld. Gebruik de termijn die de leverancier voor de specifieke dienst aangeeft, met een interne marge voor wachtrij en gegevensupdate. Als geen termijn is opgegeven, stel dan een aparte regel per servicecategorie in en herzie die op basis van de historie van de feitelijke verwerking.

Wat te doen als processing niet verandert

Langdurig processing bewijst geen fout. Controleer eerst of er succesvolle API-antwoorden binnenkwamen, of completed_quantity of remains veranderden, of er webhooks waren en of de serviceregels zijn gewijzigd. Het uitblijven van zichtbare groei kan komen door vertraging in de statistieken van het platform of doordat de leverancier de voortgang pas aan het einde bijwerkt.

Wanneer de interne wachttijd is overschreden, annuleer de bestelling dan niet automatisch. Voer een extra statuscontrole uit, vraag gegevens op via een aparte methode als die beschikbaar is, en controleer de meldingshistorie. Als de leverancier nog steeds processing bevestigt, zet de bestelling dan in de interne toestand ‘controle nodig’, maar behoud de externe status zonder die te vervangen.

• Leg het tijdstip van het laatste bevestigde antwoord en het volledige API-antwoord vast.
• Controleer of de voortgang sinds de vorige poll is gewijzigd.
• Verlaag de frequentie van automatische verzoeken na het bereiken van de interne drempel.
• Geef aan de support het externe ID, de link, de serviceparameters, de statushistorie en technische fouten door.
• Start het restant niet opnieuw tot het antwoord van de leverancier of een duidelijke eindstatus.

Het nadeel van handmatige controle is dat de bestelling aandacht van support vraagt. Maar automatische annulering of een duplicaat is gevaarlijker: de uitvoering kan bij de leverancier doorgaan.

Hoe een verzoekfout te onderscheiden van de bestelstatus

Een netwerkfout, time-out, HTTP 429 en een 5xx-antwoord melden niet de toestand van de bestelling zelf. Ze betekenen alleen dat er geen nieuwe betrouwbare status kon worden opgehaald. Laat in dat geval de laatste bevestigde status staan, registreer de technische fout en plan een nieuwe controle.

Houd bij 429 rekening met Retry-After als de header is meegegeven. Verleng bij tijdelijke netwerkfouten en 5xx de pauze tussen pogingen. Bij een fout in autorisatie, ondertekening of toegangsrechten moet je geen frequente retries doen: controleer de sleutel, de geldigheid van het token, IP-beperkingen en de toegangsinstellingen.

Als de API HTTP 200 teruggeeft, maar de JSON niet kan worden geparseerd of order_id en status ontbreken in het antwoord, sla dan de volledige antwoordbody op en markeer de controle als ongeldig. Vervang een ontbrekende status niet door completed, canceled of processing.

Wanneer automatische herhaalverzoeken te stoppen

Polling mag niet eindeloos zijn. Beperk het aantal technische herhalingen voor tijdelijke fouten en bewaak daarnaast afzonderlijk de totale tijd dat een bestelling in processing staat. Na het bereiken van de retrylimiet zet je de controletaak in de analysewachtrij, in plaats van elke minuut zonder resultaat nieuwe verzoeken te maken.

Een statusverzoek herhalen is meestal veilig als de methode alleen gegevens leest. Methoden voor aanmaken, annuleren, bijvullen, herstarten en terugbetalen mogen na een time-out niet mechanisch worden herhaald. Zonder idempotente sleutel of expliciete bevestiging van de leverancier kan zo'n herhaling de bestelling twee keer wijzigen.

Het nadeel van het beperken van retries is dat een deel van de updates een handmatige taak wordt. Eindeloze retries zijn erger: ze verbergen een storing, verbruiken limieten en maken het analyseren van logs ingewikkelder.

Hoe de eindstatus na processing te accepteren

Voorkom een teruggang van completed naar processing door een late polling-reactie of een oude webhook. Vergelijk bij elke update het tijdstip van de gebeurtenis van de leverancier, het volgnummer van de versie als dat bestaat, en de huidige interne toestand.

• new en pending kunnen overgaan naar processing, canceled of failed.
• processing kan overgaan naar completed, partial, canceled of failed.
• partial hoeft niet automatisch als completed te worden beschouwd.
• completed, canceled en failed gelden meestal als definitief en blokkeren automatische teruggang.
• Een onbekende status of ongeldige overgang vereist een aparte controle.

Een strikte overgangstabel heeft ook een nadeel: de leverancier kan een correcte nieuwe toestand toevoegen. Sla daarom de originele status op en overschrijf die niet met de interne classificatie.

Hoe partial en het restant van een bestelling te verwerken

Partial betekent dat alleen een deel van het oorspronkelijke volume is bevestigd. In het API-antwoord kunnen het feitelijk uitgevoerde aantal, het restant, de reden en gegevens over compensatie staan. Sla deze waarden afzonderlijk op: het oorspronkelijke bestelvolume mag niet worden vervangen door het uitgevoerde aantal.

Een voorbeeld van een eindantwoord kan er zo uitzien:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

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

}

Bepaal eerst wat de API precies bevestigt: is de terugbetaling al uitgevoerd, is de terugbetaling alleen gepland, is het restant geannuleerd of is een beroep op support nodig. Als er geen veld over terugbetaling is, beschouw het restant dan niet automatisch als gecompenseerd.

Herstart het niet-uitgevoerde deel niet zonder aparte beslissing. De leverancier kan de berekening nog afronden, de platformstatistieken kunnen met vertraging worden bijgewerkt, en een nieuwe aanvraag kan dubbele promotie veroorzaken. Het nadeel van wachten op bevestiging is dat het restant niet direct wordt afgesloten, maar er ontstaat geen extra bestelling.

Webhooks vervangen geen controlecontrole

Een webhook maakt het mogelijk de bestelkaart direct na een gebeurtenis bij te werken, zonder op de volgende polling te wachten. Zoek in de handler de bestelling op via het externe ID, controleer de handtekening of het geheim, sla het gebeurtenis-ID op en pas de overgang pas toe na controle van de geldigheid.

Herhaalde levering van een webhook moet veilig zijn: dezelfde gebeurtenis mag niet als nieuwe wijziging gelden. Gebeurtenissen kunnen ook buiten volgorde aankomen, dus zet een definitieve bestelling niet terug alleen op basis van een late processing.

Controle-polling is nodig, zelfs bij stabiele webhooks. Het nadeel van webhooks is de complexere configuratie: er is een bereikbare handler nodig, bescherming tegen vervalste verzoeken, deduplicatie en een gebeurtenissenlog.

Wat je de klant toont bij processing en vastlopen

In de interface hoeft niet de volledige technische JSON te worden getoond. Voor processing volstaat de toestand ‘bestelling in behandeling’. Als de API betrouwbare voortgang heeft doorgegeven, toon het bevestigde volume apart van het oorspronkelijke en presenteer het niet als eindresultaat.

Gebruik voor een bestelling die de interne controletijd heeft overschreden een begrijpelijke toestand zoals ‘we controleren de uitvoering’. Meld geen annulering, terugbetaling of volledige afronding voordat dit door het antwoord van de leverancier is bevestigd.

Meldingen zijn nuttig bij het accepteren van een bestelling, definitieve uitvoering, partial, annulering, fout en wanneer controle nodig is. Berichten na elke polling veroorzaken ruis en helpen de klant niet de werkelijke toestand van de aanvraag te begrijpen.

Welke registraties nodig zijn in het verwerkingslog

De antwoordhistorie helpt bij het analyseren van vastgelopen processing, een verloren webhook, een geschil over gedeeltelijke uitvoering en een verschil tussen interface en API. Sla voor elk verzoek het externe ID op, de bron van de update, het tijdstip van verzoek en antwoord, de HTTP-code, de originele status, de genormaliseerde status, de voortgang, het restant en de tekst van de technische fout.

Schrijf geen API-sleutels, tokens, handtekeningen en andere geheimen in gewone logs. Beperk de toegang tot ruwe antwoorden: daarin kunnen gegevens staan die niet in de supportinterface thuishoren.

Test vóór de lancering scenario's met herhaald processing, ontbrekende voortgang, time-out, 429, 5xx-fout, ongeldige JSON, late webhook, duplicate-webhook, partial, canceled en onbekende status. De testmodus is nuttig voor de structuur van de integratie, maar het nadeel is dat hij de echte wachtrijen en vertragingen van de productie-API mogelijk niet nabootst.