Balanscontrole via de API voordat je bestellingen massaal start

Waarom je het saldo opvraagt voordat je een wachtrij start

Bestellingen massaal starten zonder een verse balanscontrole leidt tot gedeeltelijke weigeringen: de eerste aanvragen worden aangemaakt en de volgende krijgen een fout wegens onvoldoende middelen. Het lastigst is zo'n situatie bij parallel verzenden, verschillende diensten en meerdere processen die met hetzelfde account werken.

Voor de start is niet het totale bedrag aan opwaarderingen en niet het boekhoudkundige saldo in het dashboard belangrijk. Je hebt het bedrag nodig dat de dienst op het moment van het aanmaken van een nieuwe bestelling mag afschrijven. Geld voor actieve aanvragen kan al gereserveerd zijn, terwijl de definitieve afschrijving nog niet in de transactiegeschiedenis staat.

Vergelijk het budget van de wachtrij met het veld voor het beschikbare saldo, niet met het totale bedrag op de rekening.

Hoe het antwoord van de balansmethode eruitziet

De veldnamen worden bepaald door de documentatie van het specifieke platform, maar een handig contract voor de balansmethode retourneert meestal total, available, reserved, currency en updated_at. Hieronder staat een voorbeeldstructuur die je als richtlijn kunt gebruiken bij de integratie. Dit is geen universeel antwoord voor elke dienst, maar een voorbeeld van een duidelijk datamodel.

Het verzoek kan er zo uitzien:

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

Antwoord:

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

In dit voorbeeld is total alle middelen van het account, available het geld voor nieuwe bestellingen en reserved het bedrag voor eerder aangemaakte transacties. De controle klopt: 125.80 min 41.30 is gelijk aan 84.50. Het veld currency bepaalt de rekeneenheid en updated_at helpt te begrijpen hoe recent de gegevens zijn.

Hoe je available en reserved interpreteert

Het veld available gebruik je om te beslissen over de start. Als de wachtrij 80.00 kost en available is 84.50, zijn er alleen voldoende middelen op voorwaarde dat de API geen aparte commissie toevoegt of de prijs op het moment van aanmaken van de aanvraag herberekent. Het veld reserved tel je niet op bij het beschikbare saldo: dat bedrag is al bezet.

reserved kan de kosten bevatten van bestellingen met de status processing, pending of review — de exacte set hangt af van de regels van het platform. Soms komt de reservering vrij na annulering, gedeeltelijke uitvoering of handmatige controle. Daarom kun je die alleen zelf berekenen op basis van de lijst met bestellingen als extra controle.

• total is geschikt om te vergelijken met de geschiedenis van opwaarderingen en afschrijvingen;
• available is geschikt om een nieuwe wachtrij tot de start toe te laten;
• reserved laat zien hoeveel middelen al geblokkeerd zijn voor actieve transacties;
• currency mag je niet negeren, zelfs niet als je maar met één account werkt;
• updated_at is nuttig voor het logboek en voor het diagnosticeren van een verouderd antwoord.

Een antwoord met alleen het veld balance is eenvoudiger te verwerken, maar heeft een nadeel: je kunt niet zien of dat geld onmiddellijk beschikbaar is of dat een deel al is ingehouden voor andere bestellingen.

Controleer het formaat van bedragen in de API-documentatie

In het voorbeeld worden bedragen als strings doorgegeven: "84.50", niet als het getal 84.5. Dat formaat behoudt de exacte waarde die de dienst heeft geretourneerd. Als de API strings met een decimale punt gebruikt, kun je ze beter niet meteen omzetten naar floating-point getallen en vergelijkingen via float uitvoeren.

Je berekening kan bijvoorbeeld 84.499999 opleveren in plaats van de verwachte 84.50. Op de grens van het budget kan dat ertoe leiden dat een wachtrij onterecht wordt doorlaten of juist wordt gestopt. Gebruik voor bewerkingen met decimale stringwaarden een decimaal gegevenstype dat de precisie van een vaste fractie ondersteunt.

Een ander veelvoorkomend contract is gehele minimale eenheden. Dan kan het antwoord "available_minor": 8450 en "currency": "USD" bevatten, en de prijs van een bestelling "price_minor": 1250. Binnen zo'n API betekent 8450 dan 84.50, als de valutaregels twee decimalen veronderstellen. Delen door 100 mag alleen als dat expliciet in de documentatie staat.

Meng valuta en prijsformaten niet door elkaar

Vergelijk vóór de berekening van de wachtrij de currency uit de balans met de valuta van de prijsmethode of het antwoord bij het aanmaken van een bestelling. Als de balans één valuta retourneert en de dienstencatalogus een andere, mag je de cijfers niet rechtstreeks invullen. Je hebt dan ofwel een berekening nodig die het platform zelf levert, ofwel een aparte bevestigde conversiemethode.

Vooraf converteren aan jouw kant is handig voor de planning, maar heeft een nadeel: de dienst kan op het moment van afschrijving een andere koers, commissie of afrondingsregel toepassen. Betrouwbaarder is om de bestelling te verzenden met parameters waarvoor de API de uiteindelijke kosten in de valuta van de balans retourneert, of om de prijsberekening direct vóór het aanmaken op te halen.

Als de prijsmethode "price": "12.345" retourneert en de balans waarden met twee decimalen opslaat, controleer dan de afrondingsregel. Rond niet automatisch naar beneden af: de werkelijke afschrijving kan hoger uitvallen. Gebruik voor het toelaten van de wachtrij precies het bedrag dat de API de uiteindelijke kosten van de bestelling noemt.

Bereken het budget van de wachtrij vóór het eerste verzoek

Verzamel vóór de start alle aanvragen en bereken de kosten met inachtneming van het volume, de gekozen dienst, de regio, extra opties en de commissie als die apart wordt doorgegeven. Vergelijk available niet met de basisprijs uit de interface: in de API kan het totaal afhangen van de parameters van de specifieke bestelling.

Stel dat er drie bestellingen in de wachtrij staan. De prijsberekenings-API retourneerde daarvoor 18.40, 27.15 en 31.60 in dezelfde valuta als in balance.currency. Het budget is 77.15. Als balance.available gelijk is aan 84.50, blijft er na de geplande start 7.35 over. Als available gelijk is aan 76.90, mag je niet de hele wachtrij starten.

1. Haal de prijzen op basis van de werkelijke parameters van elke bestelling op.
2. Tel de uiteindelijke kosten op zonder hun formaat en valuta te wijzigen.
3. Vergelijk het budget met available uit een vers antwoord van de balans.
4. Leg bij voldoende saldo het bedrag vast als lokale reservering voor de start.
5. Verlaag na het aanmaken van elke aanvraag de lokale reservering met de bevestigde kosten.

Een marge verlaagt het risico op weigering bij een extra afschrijving, maar heeft een nadeel: een deel van de beschikbare middelen blijft ongebruikt, terwijl de wachtrij volledig had kunnen doorgaan.

Doe een tweede controle vlak vóór het verzenden

Een balans die je bij de voorbereiding van de campagne hebt opgehaald, verliest snel aan actualiteit. In de tijd tussen berekening en start kunnen een andere operator, automatisering of een actieve bestelling available en reserved wijzigen. Een herhaald verzoek is nodig nadat de wachtrij is samengesteld en direct vóór de eerste aanvraag.

Een werkbare aanpak bestaat uit twee fasen: eerst prijzen ophalen en het budget inschatten, daarna balance nogmaals opvragen. Als de waarde van available is gedaald en onder het berekende bedrag is gekomen, wordt de wachtrij niet in zijn geheel verzonden. Tussen de laatste controle en de start kun je beter geen andere afschrijvingen met hetzelfde account uitvoeren.

Eén verzoek voor de hele start vermindert de belasting van de API, maar het nadeel is dat het beschikbare saldo kan veranderen terwijl een lange wachtrij nog wordt verwerkt.

Hoe je een wachtrij start bij onvoldoende middelen

Als available kleiner is dan het budget, verzend dan niet alle verzoeken in de hoop dat een deel doorgaat. Verdeel de wachtrij in pakketten waarvan de kosten binnen de beschikbare limiet passen. In het voorbeeld met een saldo van 76.90 kun je de eerste twee bestellingen voor 45.55 verzenden en dan stoppen: de derde voor 31.60 vereist een nieuwe controle.

Leg de volgorde van de aanvragen bij batchen expliciet vast. Je kunt eerst prioriteitsbestellingen verzenden of pakketten met vergelijkbare kosten vormen. Elk van beide heeft een nadeel: een prioriteitsvolgorde stelt minder belangrijke posities uit, en sorteren op prijs kan het oorspronkelijke campagnep lan verstoren.

• Stel een pakket samen met een bedrag dat niet hoger is dan de huidige available.
• Maak de bestellingen uit het pakket aan en bewaar hun identifiers.
• Wacht op de antwoorden of controleer de statussen van de transacties na time-outs.
• Pauzeer als de API-limieten of de regels van de dienst dat vereisen.
• Vraag balance opnieuw op vóór het volgende pakket.

Baseer je na elk pakket op het nieuwe API-antwoord en niet alleen op de lokale aftrek van de vorige balans. Een lokale berekening is nuttig voor de controle, maar ziet geen terugbetalingen, externe afschrijvingen en herberekeningen van reserveringen.

Bescherm het budget bij parallel verzenden

Bij sequentiële verwerking volstaat het om de lokale limiet na bevestiging van een bestelling te verlagen. Bij een parallel model kunnen twee workers tegelijkertijd available 84.50 zien en elk een uitgave van 60.00 plannen. Beide beslissingen lijken afzonderlijk toelaatbaar, maar samen overschrijden ze het beschikbare saldo.

Voor bescherming is een gedeelde teller voor de lokale reservering nodig, of een wachtrij waartoe de toegang atomair verloopt. Vóór het verzenden probeert de worker het bedrag van de bestelling in die teller te reserveren. Als er onvoldoende vrije limiet is, blijft de aanvraag wachten op een nieuwe balanscontrole.

• Een sequentiële wachtrij is eenvoudiger te controleren, maar start langzamer.
• Parallel verzenden verkort de starttijd, maar vereist vergrendeling van het gedeelde budget.
• Lokaal reserveren vermindert conflicten, maar kan vastlopen na een storing van een worker.
• Reserveren aan de kant van de API is betrouwbaarder, maar niet elk platform biedt het.

Als het proces eindigde voordat een antwoord binnenkwam, mag je de lokale reservering niet meteen als besteed of als vrij beschouwen. Controleer eerst of de bestelling is aangemaakt, via de externe identifier of met een methode om transacties te zoeken.

Gebruik de reservering van de API als die wordt ondersteund

Sommige API's laten je een reservering voor een set transacties aanmaken of een bestelling in twee stappen uitvoeren: berekening, bedrag blokkeren, bevestigen. In zo'n schema is het venster waarin een ander proces de middelen van het account kan uitgeven tussen controle en afschrijving kleiner.

Als zo'n methode beschikbaar is, bewaar dan de identifier van de reservering, het bedrag, de valuta, de geldigheidsduur en de status. Geef die identifier vervolgens door bij het aanmaken van bestellingen, als het API-contract dat vereist. Vergelijk na afronding van de wachtrij het ongebruikte deel en of de blokkering is opgeheven.

Een API-reservering lost niet alle problemen op: ze kan een korte geldigheidsduur hebben, commissies niet dekken of vrijkomen na een fout bij de bevestiging. Een lokale reservering is eenvoudiger te implementeren, maar heeft als nadeel dat ze niet beschermt tegen uitgaven die buiten je applicatie om zijn gedaan.

Onderscheid een balansfout van een nulsaldo

Een antwoord met een foutcode, een time-out of een limiet op het aantal verzoeken betekent niet dat available nul is. Vul niet automatisch de laatst bekende waarde in als daarvan een grote start afhangt. Als je geen verse balans kunt ophalen, moet de wachtrij worden gepauzeerd.

Behandel een weigering bij het aanmaken van een bestelling apart. Die kan samenhangen met onvoldoende middelen, maar ook met een onjuiste dienstidentifier, een ongeldig volume, een beperking voor het kanaal of een herhaling van dezelfde transactie. Bewaar de foutcode en de fouttekst samen met de externe identifier van de aanvraag.

• Vernieuw bij een autorisatiefout de toegang en herhaal het verzoek pas daarna.
• Houd bij een verzoeklimiet een pauze aan volgens de API-regels.
• Controleer bij een time-out bij het aanmaken eerst of de transactie daadwerkelijk is verschenen.
• Stop bij een fout wegens onvoldoende middelen het pakket en vraag balance opnieuw op.

Maak geen duplicaten na een time-out

Een time-out betekent dat je client geen antwoord heeft ontvangen, niet dat de server het verzoek niet heeft verwerkt. Opnieuw verzenden zonder controle kan een tweede bestelling aanmaken en het geld opnieuw reserveren. Dat is vooral gevaarlijk in een wachtrij waarin automatische herhaling op meerdere pogingen is ingesteld.

Geef een unieke externe identifier van de bestelling door als de API een veld client_order_id, external_id of idempotency_key ondersteunt. Bewaar die voordat je het verzoek verzendt. Zoek na een time-out de transactie op via die waarde of vraag de status op via de eerder ontvangen identifier.

Herhalen zonder controle is sneller, maar het nadeel is direct: er kunnen dubbele bestellingen ontstaan, dubbele reserveringen en verschillen tussen je budgetberekening en de werkelijke afschrijvingen.

Wat je in het startlogboek bewaart

Het logboek helpt om het verloop van een massale operatie te reconstrueren en uit te leggen waarom een bepaald pakket is gestopt. Bewaar voor elke start het tijdstip van de twee controles, total, available, reserved, currency, het berekende budget, de omvang van de lokale reservering en de lijst met externe identifiers van de aanvragen.

Leg voor elke poging tot aanmaken de kosten, de responscode, de technische identifier van de transactie en de uiteindelijke status vast. Geheimen horen niet in het logboek: autorisatietokens, API-sleutels, volledige verzoekheaders en persoonsgegevens moeten worden gemaskeerd of vóór het opslaan worden uitgesloten.

Volledig loggen is handig bij het debuggen, maar heeft een nadeel: zonder filtering kunnen toegangsgegevens en klantinformatie in de opslag terechtkomen.

Test het schema op een kleine wachtrij

Voer vóór een grote start een kort scenario uit: haal balance op, vraag de uiteindelijke prijzen op, maak een beperkt pakket aan, vraag balance opnieuw op en vergelijk de verwachte wijziging van available en reserved met het werkelijke antwoord. Zo kun je zien wanneer de dienst een bedrag reserveert en wanneer ze het definitief afschrijft.

Een testpakket garandeert niet hetzelfde gedrag onder zware belasting: limieten, parallelle processen of beperkingen van een specifieke dienst kunnen optreden. Blijf daarom in een massale wachtrij de start opdelen in pakketten, het beschikbare saldo ertussen controleren en elke weigering apart behandelen.