Preverjanje stanja prek API pred množičnim zagonom naročil

Zakaj zahtevati stanje pred zagonom čakalne vrste

Množični zagon naročil brez svežega preverjanja stanja vodi v delne zavrnitve: prve zahteve se ustvarijo, naslednje pa prejmejo napako o pomanjkanju sredstev. Najtežje je takšno situacijo razrešiti pri vzporednem pošiljanju, različnih storitvah in več procesih, ki delujejo z istim računom.

Za zagon ni pomembna skupna količina pologov ali knjigovodsko stanje v osebnem računu. Potreben je znesek, ki ga storitev dovoli odpisati v trenutku ustvarjanja novega naročila. Denar za aktivne zahteve je lahko že v rezervaciji, čeprav končni odpis še ni prikazan v zgodovini transakcij.

Proračun čakalne vrste primerjajte s poljem razpoložljivega preostanka, ne s skupnim zneskom na računu.

Kako izgleda odgovor metode stanja

Imena polj določa dokumentacija posamezne platforme, vendar priročen pogodbeni dogovor metode stanja običajno vrne total, available, reserved, currency in updated_at. Spodaj je primer strukture, ki ga lahko uporabite kot smernico pri integraciji. To ni univerzalen odgovor za vsako storitev, ampak primer razumljive podatkovne sheme.

Zahteva je lahko takšna:

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

Odgovor:

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

V tem primeru je total vsa sredstva računa, available je denar za nova naročila, reserved pa znesek za predhodno ustvarjene operacije. Preverjanje se ujema: 125.80 minus 41.30 je enako 84.50. Polje currency določa obračunsko enoto, updated_at pa pomaga razumeti, kako sveži so podatki.

Kako razlagati available in reserved

Polje available se uporablja za odločitev o zagonu. Če čakalna vrsta stane 80.00, available pa je 84.50, so sredstva zadostna le pod pogojem, da API ne doda ločene provizije ali ne preračuna cene v trenutku ustvarjanja zahteve. Polja reserved se ne prišteva k razpoložljivemu preostanku: ta znesek je že zaseden.

reserved lahko vključuje stroške naročil s statusi processing, pending ali review — natančen nabor je odvisen od pravil platforme. Včasih se rezervacija sprosti po preklicu, delni izvedbi ali ročnem pregledu. Zato ga lahko samostojno izračunate po seznamu naročil le kot dodatno preverjanje.

• total je primeren za primerjavo z zgodovino pologov in odpisov;
• available je primeren za odobritev nove čakalne vrste za zagon;
• reserved prikazuje, koliko sredstev je že blokiranih za aktivne operacije;
• currency ne smete ignorirati tudi pri delu z samo enim računom;
• updated_at je koristen za dnevnik in diagnostiko zastarelega odgovora.

Odgovor samo s poljem balance je lažje obdelati, vendar ima pomanjkljivost: ni mogoče razumeti, ali je ta denar na voljo takoj ali je del zneska že zadržan za druga naročila.

Preverite format zneskov v dokumentaciji API

V primeru so zneski podani kot nizi: "84.50", ne kot število 84.5. Tak format ohrani natančno vrednost, ki jo je vrnila storitev. Če API uporablja nize z decimalno piko, jih ne pretvarjajte takoj v števila s plavajočo vejico in ne izvajajte primerjav prek float.

Na primer, vaš izračun lahko da 84.499999 namesto pričakovanih 84.50. Na meji proračuna to lahko napačno spusti čakalno vrsto ali jo, nasprotno, ustavi. Za operacije z nizi decimalnih vrednosti uporabite decimalni podatkovni tip, ki podpira natančnost fiksnega decimalnega dela.

Druga pogosta pogodba so cela minimalna enota. Takrat lahko odgovor vsebuje "available_minor": 8450 in "currency": "USD", cena naročila pa je "price_minor": 1250. Znotraj takega API 8450 pomeni 84.50, če pravila valute predvidevajo dve decimalni mesti. Vrednost delite s 100 le, kadar je to izrecno navedeno v dokumentaciji.

Ne mešajte valut in formatov cen

Pred izračunom čakalne vrste primerjajte currency iz stanja z valuto cenovne metode ali odgovora pri ustvarjanju naročila. Če stanje vrne eno valuto, katalog storitev pa drugo, številk ne smete vstavljati neposredno. Potreben je bodisi izračun, ki ga ponuja sama platforma, bodisi ločena potrjena metoda pretvorbe.

Predhodna pretvorba na vaši strani je priročna za načrtovanje, vendar ima pomanjkljivost: storitev lahko ob odpisovanju uporabi drugačen tečaj, provizijo ali pravilo zaokroževanja. Zanesljiveje je poslati naročilo s parametri, za katere API vrne končno ceno v valuti stanja, ali pridobiti izračun cene neposredno pred ustvarjanjem.

Če metoda cene odgovori "price": "12.345", stanje pa hrani vrednosti z dvema mestoma, preverite pravilo zaokroževanja. Ne zaokrožujte samodejno navzdol: dejanski odpis je lahko višji. Za odobritev čakalne vrste uporabite natanko znesek, ki ga API navaja kot končno ceno naročila.

Izračunajte proračun čakalne vrste pred prvo zahtevo

Pred zagonom zberite vse zahteve in izračunajte njihovo ceno ob upoštevanju obsega, izbrane storitve, regije, dodatnih možnosti in provizije, če se posreduje ločeno. Ne primerjajte available z osnovno ceno iz vmesnika: v API je lahko končni znesek odvisen od parametrov konkretnega naročila.

Recimo, da so v čakalni vrsti tri naročila. API za izračun cene je zanje vrnil 18.40, 27.15 in 31.60 v isti valuti, kot je navedena v balance.currency. Proračun je 77.15. Če je balance.available enak 84.50, po načrtovanem zagonu ostane 7.35. Če je available enak 76.90, celotne čakalne vrste ni mogoče zagnati.

1. Pridobite cene po dejanskih parametrih vsakega naročila.
2. Seštejte končne cene, ne da bi spremenili njihov format in valuto.
3. Primerjajte proračun z available iz svežega odgovora stanja.
4. Ob zadostnem preostanku zabeležite znesek kot lokalno rezervacijo zagona.
5. Po ustvarjanju vsake zahteve zmanjšajte lokalno rezervacijo za potrjeno ceno.

Rezerva zmanjšuje tveganje zavrnitve pri dodatnem odpisovanju, vendar ima pomanjkljivost: del razpoložljivih sredstev ostane neizkoriščen, čeprav bi čakalna vrsta lahko v celoti uspela.

Opravite drugo preverjanje tik pred pošiljanjem

Stanje, pridobljeno med pripravo kampanje, hitro izgubi veljavnost. V času med izračunom in zagonom lahko drug operater, avtomatizacija ali aktivno naročilo spremeni available in reserved. Ponovna zahteva je potrebna po oblikovanju čakalne vrste in neposredno pred prvo zahtevo.

Delovna shema je sestavljena iz dveh stopenj: najprej pridobite cene in ocenite proračun, nato znova zahtevajte balance. Če se je vrednost available zmanjšala in padla pod izračunani znesek, čakalne vrste ne pošljete v celoti. Med končnim preverjanjem in zagonom ne izvajajte drugih odpisov z istega računa.

Ena zahteva za celoten zagon zmanjša obremenitev API, vendar je njena pomanjkljivost v tem, da se razpoložljivi preostanek lahko spremeni, medtem ko se dolga čakalna vrsta še obdeluje.

Kako zagnati čakalno vrsto ob pomanjkanju sredstev

Če je available manjši od proračuna, ne pošiljajte vseh zahtev v upanju, da bo del uspel. Razdelite čakalno vrsto na pakete, katerih cena se ujema z razpoložljivim limitom. V primeru s preostankom 76.90 lahko pošljete prvi dve naročili za 45.55, nato se ustavite: tretje za 31.60 zahteva ponovno preverjanje.

Vrstni red zahtev pri paketnem pošiljanju določite izrecno. Lahko najprej pošljete prednostna naročila ali oblikujete pakete s podobno ceno. Vsaka možnost ima pomanjkljivost: prednostni vrstni red odloži manj pomembne postavke, razvrščanje po ceni pa lahko poruši prvotni načrt kampanje.

• Oblikujte paket z zneskom, ki ni višji od trenutnega available.
• Ustvarite naročila iz paketa in shranite njihove identifikatorje.
• Počakajte na odgovore ali preverite statuse operacij po časovnih omejitvah.
• Naredite premor, če to zahtevajo limiti API ali pravila storitve.
• Pred naslednjim paketom znova zahtevajte balance.

Po vsakem paketu se ravnajte po novem odgovoru API, ne le po lokalnem odbitku od prejšnjega stanja. Lokalni izračun je koristen za nadzor, vendar ne vidi vračil, zunanjih odpisov in preračuna rezervacij.

Zaščitite proračun pri vzporednem pošiljanju

Pri zaporedni obdelavi je dovolj, da po potrditvi naročila zmanjšate lokalni limit. Pri vzporednem modelu lahko dva delavca hkrati vidita available 84.50 in vsak načrtuje porabo 60.00. Obe odločitvi se zdita posamično dopustni, skupaj pa presegata razpoložljivi preostanek.

Za zaščito je potreben skupni števec lokalne rezervacije ali čakalna vrsta, do katere se dostopa atomsko. Pred pošiljanjem delavec poskusi zasedsti znesek naročila v tem števcu. Če prostega limita ni dovolj, zahteva ostane v čakanju na ponovno preverjanje stanja.

• Zaporedna čakalna vrsta se lažje nadzoruje, vendar se zažene počasneje.
• Vzporedno pošiljanje skrajša čas zagona, vendar zahteva zaklepanje skupnega proračuna.
• Lokalna rezervacija zmanjšuje konflikte, vendar se lahko po okvari delavca zatakne.
• Rezervacija na strani API je zanesljivejša, vendar ni na voljo pri vsaki platformi.

Če se je proces končal pred prejemom odgovora, lokalne rezervacije ni mogoče takoj šteti za porabljeno ali prosto. Najprej preverite, ali je bilo naročilo ustvarjeno, po njegovem zunanjem identifikatorju ali z metodo iskanja operacij.

Uporabite rezervacijo API, če je predvidena

Nekateri API-ji omogočajo ustvarjanje rezervacije za nabor operacij ali izvedbo naročila v dveh korakih: izračun, blokiranje zneska, potrditev. V taki shemi je med preverjanjem in odpisom manjše okno, v katerem lahko drug proces porabi sredstva računa.

Če je takšna metoda na voljo, shranite identifikator rezervacije, njen znesek, valuto, rok veljavnosti in status. Nato ta identifikator posredujte pri ustvarjanju naročil, če to zahteva pogodba API. Po zaključku čakalne vrste primerjajte neizkoriščeni del in dejstvo o sprostitvi blokade.

Rezervacija API ne reši vseh težav: lahko ima kratek rok veljavnosti, ne pokriva provizij ali se sprosti po napaki potrditve. Lokalno rezervacijo je lažje uvesti, vendar je njena pomanjkljivost v tem, da ne ščiti pred porabo, ustvarjeno zunaj vaše aplikacije.

Ločite napako stanja od ničelnega preostanka

Odgovor s kodo napake, časovna omejitev ali omejitev pogostosti zahtev ne pomenijo, da je available enak nič. Ne vstavljajte samodejno zadnje znane vrednosti, če je od nje odvisen velik zagon. Če svežega stanja ni mogoče pridobiti, je treba čakalno vrsto začasno ustaviti.

Ločeno obravnavajte zavrnitev pri ustvarjanju naročila. Lahko je povezana s pomanjkanjem sredstev, pa tudi z napačnim identifikatorjem storitve, nedopustnim obsegom, omejitvijo na kanal ali ponovitvijo iste operacije. Kodo in besedilo napake shranite skupaj z zunanjim identifikatorjem zahteve.

• Ob napaki avtorizacije osvežite dostop in šele nato ponovite zahtevo.
• Ob limitu zahtev upoštevajte premor po pravilih API.
• Ob časovni omejitvi ustvarjanja najprej preverite, ali se je operacija dejansko pojavila.
• Ob napaki pomanjkanja sredstev ustavite paket in znova zahtevajte balance.

Ne ustvarjajte dvojnikov po časovni omejitvi

Časovna omejitev pomeni, da vaš odjemalec ni prejel odgovora, ne pa, da strežnik zahteve ni obdelal. Ponovno pošiljanje brez preverjanja lahko ustvari drugo naročilo in znova zasede denar. To je še posebej nevarno v čakalni vrsti, kjer je samodejno ponavljanje nastavljeno na več poskusov.

Posredujte edinstven zunanji identifikator naročila, če API podpira polje client_order_id, external_id ali idempotency_key. Shranite ga pred pošiljanjem zahteve. Po časovni omejitvi poiščite operacijo po tej vrednosti ali zahtevajte status po predhodno pridobljenem identifikatorju.

Ponovitev brez preverjanja je hitrejša, vendar je njena pomanjkljivost neposredna: možni so dvojniki naročil, dvojna rezervacija in odstopanja med vašim izračunom proračuna in dejanskimi odpiski.

Kaj shraniti v dnevnik zagona

Dnevnik pomaga obnoviti potek množične operacije in pojasniti, zakaj se je določen paket ustavil. Za vsak zagon shranite čas dveh preverjanj, total, available, reserved, currency, izračunani proračun, velikost lokalne rezervacije in seznam zunanjih identifikatorjev zahtev.

Za vsak poskus ustvarjanja zabeležite ceno, kodo odgovora, tehnični identifikator operacije in končni status. Skrivnosti v dnevnik ne sodijo: avtorizacijske žetone, ključe API, celotne glave zahtev in osebne podatke je treba maskirati ali izključiti pred zapisom.

Popolno beleženje je priročno pri odpravljanju napak, vendar ima pomanjkljivost: brez filtriranja lahko v shrambo pridejo dostopni podatki in podatki o strankah.

Preizkusite shemo na majhni čakalni vrsti

Pred velikim zagonom izvedite kratek scenarij: pridobite balance, zahtevajte končne cene, ustvarite omejen paket, znova zahtevajte balance in primerjajte pričakovano spremembo available in reserved z dejanskim odgovorom. Tako lahko opazite, kdaj storitev znesek rezervira in kdaj ga dokončno odpiše.

Testni paket ne zagotavlja enakega vedenja pod veliko obremenitvijo: lahko se sprožijo limiti, vzporedni procesi ali omejitve konkretne storitve. Zato v množični čakalni vrsti še naprej delite zagon na pakete, med njimi preverjajte razpoložljivi preostanek in vsako zavrnitev obravnavajte ločeno.