Egyenleg ellenőrzése API-n keresztül a rendelések tömeges indítása előtt

Miért kérjük le az egyenleget a sor indítása előtt

A rendelések tömeges indítása friss egyenlegellenőrzés nélkül részleges elutasításokhoz vezet: az első kérések létrejönnek, a következők pedig elégtelen fedezet hibát kapnak. Ezt a helyzetet a legnehezebb párhuzamos küldés, különböző szolgáltatások és több, ugyanazon a fiókon dolgozó folyamat esetén kezelni.

Az indításhoz nem a feltöltések teljes összege és nem a fiók könyvelési egyenlege a fontos. Arra az összegre van szükség, amelyet a szolgáltatás egy új rendelés létrehozásakor levonhat. Az aktív kérésekre szánt pénz már foglalásban lehet, még akkor is, ha a végleges levonás még nem jelenik meg az tranzakciótörténetben.

A sor költségvetését az elérhető egyenleg mezőjével hasonlítsa össze, ne a számlán lévő teljes összeggel.

Hogyan néz ki az egyenleg metódus válasza

A mezőneveket az adott platform dokumentációja határozza meg, de egy kényelmes egyenleg metódus szerződése általában total, available, reserved, currency és updated_at mezőket ad vissza. Az alábbiakban egy példa szerkezet látható, amelyet az integráció során iránymutatásként használhat. Ez nem univerzális válasz minden szolgáltatáshoz, hanem egy érthető adatséma példája.

A kérés így nézhet ki:

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

Válasz:

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

Ebben a példában a total a fiók összes pénzeszköze, az available az új rendelésekre fordítható pénz, a reserved pedig a korábban létrehozott műveletekre foglalt összeg. Az ellenőrzés stimmel: 125.80 mínusz 41.30 egyenlő 84.50. A currency mező adja meg a számítás egységét, az updated_at pedig segít megérteni, mennyire friss az adat.

Hogyan értelmezzük az available és reserved mezőket

Az available mezőt az indításról szóló döntéshez használjuk. Ha a sor 80.00-ba kerül, az available pedig 84.50, akkor csak akkor van elég fedezet, ha az API nem számít fel külön díjat, és nem számolja újra az árat a kérés létrehozásakor. A reserved mezőt nem adjuk hozzá az elérhető egyenleghez: ez az összeg már le van foglalva.

A reserved tartalmazhatja a processing, pending vagy review állapotú rendelések költségét — a pontos kör a platform szabályaitól függ. Néha a foglalás törlés, részleges teljesítés vagy manuális ellenőrzés után szabadul fel. Ezért csak kiegészítő egyeztetésként számíthatjuk ki magunk a rendelések listája alapján.

• a total a feltöltések és levonások történetével való egyeztetéshez alkalmas;
• az available az új sor indításra való engedélyezéséhez alkalmas;
• a reserved megmutatja, mennyi pénz van már lefoglalva az aktív műveletekre;
• a currency nem hagyható figyelmen kívül még egyetlen fiók esetén sem;
• az updated_at hasznos a naplózáshoz és az elavult válasz diagnosztizálásához.

A csak balance mezőt tartalmazó választ egyszerűbb feldolgozni, de van egy hátránya: nem lehet megérteni, hogy ez a pénz azonnal elérhető-e, vagy az összeg egy részét már más rendelésekre visszatartották.

Ellenőrizze az összegek formátumát az API dokumentációjában

A példában az összegek szövegként szerepelnek: "84.50", nem pedig 84.5 számként. Ez a formátum megőrzi a szolgáltatás által visszaadott pontos értéket. Ha az API tizedespontos szövegeket használ, nem érdemes ezeket azonnal lebegőpontos számokká alakítani és float-tal összehasonlítani.

Például a számítása 84.499999-et adhat a várt 84.50 helyett. A költségvetés határán ez tévesen átengedheti a sort, vagy éppen ellenkezőleg, leállíthatja azt. A szöveges tizedesértékekkel végzett műveletekhez használjon olyan decimális adattípust, amely támogatja a rögzített törtrész pontosságát.

Egy másik gyakori szerződés az egész minimális egységek. Ekkor a válasz tartalmazhatja a "available_minor": 8450 és "currency": "USD" mezőket, a rendelés ára pedig "price_minor": 1250 lehet. Egy ilyen API-n belül a 8450 84.50-et jelent, ha a valuta szabályai két tizedesjegyet feltételeznek. Az értéket csak akkor osszuk el 100-zal, ha ezt a dokumentáció kifejezetten előírja.

Ne keverje a valutákat és az árformátumokat

A sor kiszámítása előtt hasonlítsa össze az egyenleg currency mezőjét az árazási metódus vagy a rendelés létrehozásakor kapott válasz valutájával. Ha az egyenleg az egyik valutát adja vissza, a szolgáltatáskatalógus pedig a másikat, nem lehet a számokat közvetlenül behelyettesíteni. Vagy a platform által biztosított számításra van szükség, vagy egy külön, megerősített átváltási metódusra.

A saját oldalon végzett előzetes átváltás kényelmes a tervezéshez, de van egy hátránya: a szolgáltatás a levonás pillanatában más árfolyamot, díjat vagy kerekítési szabályt alkalmazhat. Megbízhatóbb a rendelést olyan paraméterekkel elküldeni, amelyekre az API a végösszeget az egyenleg valutájában adja vissza, vagy közvetlenül a létrehozás előtt lekérni az ár számítását.

Ha az árazási metódus "price": "12.345"-öt ad vissza, az egyenleg pedig két tizedesjegyű értékeket tárol, tisztázza a kerekítési szabályt. Ne kerekítsen automatikusan lefelé: a tényleges levonás magasabb lehet. A sor engedélyezéséhez pontosan azt az összeget használja, amelyet az API a rendelés végösszegeként megad.

Számítsa ki a sor költségvetését az első kérés előtt

Az indítás előtt gyűjtse össze az összes kérést, és számítsa ki a költségüket a mennyiség, a kiválasztott szolgáltatás, a régió, a további opciók és a díj figyelembevételével, ha azt külön adják meg. Ne hasonlítsa össze az available mezőt a felület alapárával: az API-ban a végösszeg az adott rendelés paramétereitől függhet.

Tegyük fel, hogy a sorban három rendelés van. Az árazási API 18.40, 27.15 és 31.60 értéket adott vissza ugyanabban a valutában, amely a balance.currency mezőben szerepel. A költségvetés 77.15. Ha a balance.available 84.50, a tervezett indítás után 7.35 marad. Ha az available 76.90, a teljes sort nem lehet elindítani.

1. Kérje le az árakat az egyes rendelések tényleges paraméterei alapján.
2. Adja össze a végösszegeket anélkül, hogy megváltoztatná a formátumukat és a valutájukat.
3. Hasonlítsa össze a költségvetést a friss egyenlegválasz available mezőjével.
4. Elegendő egyenleg esetén rögzítse az összeget helyi indítási foglalásként.
5. Minden kérés létrehozása után csökkentse a helyi foglalást a megerősített költséggel.

A tartalék csökkenti az elutasítás kockázatát egy további levonás esetén, de van egy hátránya: az elérhető pénzeszközök egy része kihasználatlan marad, pedig a sor teljes egészében átmehetett volna.

Végezzen második ellenőrzést közvetlenül a küldés előtt

A kampány előkészítésekor kapott egyenleg gyorsan elveszíti aktualitását. A számítás és az indítás közötti időben egy másik operátor, az automatizálás vagy egy aktív rendelés megváltoztathatja az available és reserved értékeket. Ismételt kérésre a sor kialakítása után és közvetlenül az első kérés előtt van szükség.

A működő séma két szakaszból áll: először lekérjük az árakat és felmérjük a költségvetést, majd még egyszer lekérjük a balance-t. Ha az available értéke csökkent és a számított összeg alá esett, a sort nem küldjük el teljes egészében. A végső ellenőrzés és az indítás között ne hajtson végre más levonásokat ugyanazon a fiókon.

Egyetlen kérés a teljes indításhoz csökkenti az API terhelését, de hátránya, hogy az elérhető egyenleg megváltozhat, míg a hosszú sor még feldolgozás alatt áll.

Hogyan indítsuk a sort elégtelen fedezet esetén

Ha az available kevesebb a költségvetésnél, ne küldje el az összes kérést abban a reményben, hogy egy részük átmegy. Ossza a sort olyan csomagokra, amelyek költsége belefér az elérhető limitbe. A 76.90 egyenlegű példában elküldheti az első két rendelést 45.55-ért, majd álljon meg: a harmadik 31.60-ért ismételt ellenőrzést igényel.

A kötegelésnél a kérések sorrendjét kifejezetten adja meg. Küldheti először a prioritásos rendeléseket, vagy képezhet hasonló költségű csomagokat. Mindkét változatnak van hátránya: a prioritásos sorrend elhalasztja a kevésbé fontos tételeket, az ár szerinti rendezés pedig felboríthatja a kampány eredeti tervét.

• Képezzen egy csomagot, amelynek összege nem haladja meg az aktuális available értéket.
• Hozza létre a csomag rendeléseit, és mentse el az azonosítóikat.
• Várja meg a válaszokat, vagy időtúllépés után ellenőrizze a műveletek állapotát.
• Tartson szünetet, ha ezt az API limitek vagy a szolgáltatás szabályai megkövetelik.
• A következő csomag előtt ismét kérje le a balance-t.

Minden csomag után az új API-válaszra támaszkodjon, ne csak a korábbi egyenlegből való helyi levonásra. A helyi számítás hasznos az ellenőrzéshez, de nem látja a visszatérítéseket, a külső levonásokat és a foglalások újraszámítását.

Védje a költségvetést párhuzamos küldés esetén

Szekvenciális feldolgozásnál elég a helyi limitet a rendelés megerősítése után csökkenteni. Párhuzamos modellben két worker egyszerre láthatja az available 84.50-et, és mindegyik 60.00 költést tervezhet. Mindkét döntés külön-külön elfogadhatónak tűnik, együtt azonban meghaladják az elérhető egyenleget.

A védelemhez közös helyi foglalásszámlálóra vagy atomikusan elérhető sorra van szükség. Küldés előtt a worker megpróbálja lefoglalni a rendelés összegét ebben a számlálóban. Ha nincs elég szabad limit, a kérés várakozásban marad az egyenleg ismételt ellenőrzésére.

• A szekvenciális sor könnyebben ellenőrizhető, de lassabban indul.
• A párhuzamos küldés csökkenti az indítási időt, de a közös költségvetés zárolását igényli.
• A helyi foglalás csökkenti az ütközéseket, de worker-hiba után elakadhat.
• Az API oldali foglalás megbízhatóbb, de nem minden platformnál érhető el.

Ha a folyamat a válasz megérkezése előtt befejeződött, a helyi foglalás nem tekinthető azonnal elköltöttnek vagy szabadnak. Először ellenőrizze, létrejött-e a rendelés, a külső azonosítója vagy a műveletkereső metódus segítségével.

Használja az API foglalást, ha van ilyen

Egyes API-k lehetővé teszik foglalás létrehozását műveletek csoportjára, vagy a rendelés két lépésben való lebonyolítását: számítás, összeg zárolása, megerősítés. Egy ilyen sémában kisebb az az ablak az ellenőrzés és a levonás között, amelyben egy másik folyamat elköltheti a fiók pénzeszközeit.

Ha van ilyen metódus, mentse el a foglalás azonosítóját, összegét, valutáját, lejárati idejét és állapotát. Ezután adja át ezt az azonosítót a rendelések létrehozásakor, ha ezt az API szerződése megköveteli. A sor befejezése után egyeztesse a fel nem használt részt és a zárolás feloldásának tényét.

Az API foglalás nem old meg minden problémát: lehet rövid a lejárati ideje, nem fedezheti a díjakat, vagy a megerősítési hiba után felszabadulhat. A helyi foglalást egyszerűbb bevezetni, de hátránya, hogy nem véd az alkalmazáson kívül létrehozott költségektől.

Különítse el az egyenleghibát a nulla egyenlegtől

A hibakódos válasz, az időtúllépés vagy a kérési gyakoriság korlátozása nem jelenti azt, hogy az available nulla. Ne helyettesítse automatikusan az utolsó ismert értéket, ha egy nagy indítás függ tőle. Ha nem lehet friss egyenleget lekérni, a sort szüneteltetni kell.

Külön kezelje a rendelés létrehozásakor kapott elutasítást. Ez összefügghet elégtelen fedezettel, de hibás szolgáltatásazonosítóval, érvénytelen mennyiséggel, csatornakorlátozással vagy egy művelet ismétlésével is. A hibakódot és a hibaüzenetet a kérés külső azonosítójával együtt mentse el.

• Hitelesítési hiba esetén frissítse a hozzáférést, és csak utána ismételje meg a kérést.
• Kérési limit esetén tartson szünetet az API szabályai szerint.
• Létrehozási időtúllépés esetén először ellenőrizze, megjelent-e a művelet ténylegesen.
• Elégtelen fedezet hiba esetén állítsa le a csomagot, és kérje le újra a balance-t.

Ne hozzon létre duplikátumokat időtúllépés után

Az időtúllépés azt jelenti, hogy az ügyfél nem kapott választ, nem pedig azt, hogy a szerver nem dolgozta fel a kérést. Az ellenőrzés nélküli ismételt küldés második rendelést hozhat létre, és ismét lefoglalhatja a pénzt. Ez különösen veszélyes olyan sorban, ahol az automatikus ismétlés több próbálkozásra van beállítva.

Adjon át egyedi külső rendelésazonosítót, ha az API támogatja a client_order_id, external_id vagy idempotency_key mezőt. Mentse el a kérés elküldése előtt. Időtúllépés után keresse meg a műveletet ezen érték alapján, vagy kérje le az állapotát a korábban kapott azonosítóval.

Az ellenőrzés nélküli ismétlés gyorsabb, de a hátránya egyértelmű: lehetségesek a rendelésduplikátumok, a kettős foglalás és az eltérések a költségvetés-számítása és a tényleges levonások között.

Mit mentse az indítási naplóba

A napló segít visszaállítani a tömeges művelet lefolyását, és megmagyarázni, miért állt le egy adott csomag. Minden indításhoz mentse el a két ellenőrzés idejét, a total, available, reserved, currency értékeket, a kiszámított költségvetést, a helyi foglalás méretét és a kérések külső azonosítóinak listáját.

Minden létrehozási kísérlethez rögzítse a költséget, a válaszkódot, a művelet technikai azonosítóját és a végleges állapotot. Titkok nem kerülnek a naplóba: az engedélyezési tokeneket, API-kulcsokat, a teljes kérésfejléceket és a személyes adatokat maszkolni kell vagy ki kell zárni a rögzítés előtt.

A teljes naplózás kényelmes a hibakereséshez, de van egy hátránya: szűrés nélkül hozzáférési adatok és ügyféladatok kerülhetnek a tárolóba.

Tesztelje a sémát egy kis soron

Nagy indítás előtt futtasson le egy rövid forgatókönyvet: kérje le a balance-t, kérje le a végösszegeket, hozzon létre egy korlátozott csomagot, ismét kérje le a balance-t, és hasonlítsa össze az available és reserved várható változását a tényleges válasszal. Így észreveheti, mikor foglalja le a szolgáltatás az összeget, és mikor vonja le véglegesen.

A tesztcsomag nem garantálja ugyanazt a viselkedést nagy terhelés alatt: életbe léphetnek a limitek, a párhuzamos folyamatok vagy az adott szolgáltatás korlátozásai. Ezért a tömeges sorban továbbra is ossza a indítást csomagokra, ellenőrizze az elérhető egyenleget közöttük, és minden elutasítást külön dolgozzon fel.