Verificarea soldului prin API înainte de lansarea în masă a comenzilor

De ce să solicităm soldul înainte de lansarea cozii

Lansarea în masă a comenzilor fără o verificare recentă a soldului duce la refuzuri parțiale: primele cereri sunt create, iar următoarele primesc eroare de fonduri insuficiente. Cel mai greu este să gestionezi o astfel de situație la trimiterea în paralel, cu servicii diferite și mai multe procese care lucrează cu același cont.

Pentru lansare nu contează volumul total al încărcărilor și nici soldul contabil din panoul personal. Este nevoie de suma pe care serviciul o permite la debitare în momentul creării unei comenzi noi. Banii pentru cererile active pot fi deja în rezervare, chiar dacă debitarea finală nu este încă reflectată în istoricul operațiunilor.

Comparați bugetul cozii cu câmpul soldului disponibil, nu cu suma totală din cont.

Cum arată răspunsul metodei de sold

Numele câmpurilor sunt stabilite de documentația fiecărei platforme, dar un contract convenabil al metodei de sold returnează de obicei total, available, reserved, currency și updated_at. Mai jos este un exemplu de structură care poate servi drept orientare la integrare. Nu este un răspuns universal pentru fiecare serviciu, ci un exemplu de schemă de date clară.

Cererea poate arăta astfel:

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

Răspuns:

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

În acest exemplu total reprezintă toate fondurile contului, available — banii pentru comenzile noi, reserved — suma pentru operațiunile create anterior. Verificarea se potrivește: 125.80 minus 41.30 este egal cu 84.50. Câmpul currency stabilește unitatea de calcul, iar updated_at ajută la înțelegerea cât de recente sunt datele.

Cum să interpretați available și reserved

Câmpul available este folosit pentru decizia de lansare. Dacă coada costă 80.00, iar available este 84.50, fondurile sunt suficiente doar cu condiția ca API-ul să nu adauge un comision separat sau să recalculeze prețul în momentul creării cererii. Câmpul reserved nu se adaugă la soldul disponibil: această sumă este deja ocupată.

reserved poate include costul comenzilor cu statusurile processing, pending sau review — setul exact depinde de regulile platformei. Uneori rezervarea este eliberată după anulare, executare parțială sau verificare manuală. De aceea, calcularea ei pe cont propriu după lista de comenzi poate fi folosită doar ca verificare suplimentară.

• total este potrivit pentru reconcilierea cu istoricul încărcărilor și debitarilor;
• available este potrivit pentru admiterea unei cozi noi la lansare;
• reserved arată cât de multe fonduri sunt deja blocate pentru operațiuni active;
• currency nu poate fi ignorat chiar și atunci când lucrezi cu un singur cont;
• updated_at este util pentru jurnal și diagnosticarea unui răspuns învechit.

Un răspuns doar cu câmpul balance este mai simplu de procesat, dar are un dezavantaj: nu se poate înțelege dacă acești bani sunt disponibili imediat sau o parte din sumă este deja reținută pentru alte comenzi.

Verificați formatul sumelor în documentația API

În exemplu sumele sunt transmise ca șiruri: "84.50", nu ca număr 84.5. Acest format păstrează valoarea exactă returnată de serviciu. Dacă API-ul folosește șiruri cu punct zecimal, nu ar trebui să le convertiți imediat în numere cu virgulă mobilă și să faceți comparații prin float.

De exemplu, calculul dvs. poate da 84.499999 în loc de 84.50 așteptat. La limita bugetului acest lucru poate omite în mod eronat coada sau, dimpotrivă, o poate opri. Pentru operațiunile cu valori zecimale sub formă de șiruri, folosiți un tip de date zecimal care suportă precizia părții fracționare fixe.

Un alt contract răspândit este cel al unităților minime întregi. Atunci răspunsul poate conține "available_minor": 8450 și "currency": "USD", iar prețul comenzii — "price_minor": 1250. În interiorul unui astfel de API, 8450 înseamnă 84.50, dacă regulile valutei presupun două poziții fracționare. Împărțirea valorii la 100 se face doar când acest lucru este specificat explicit în documentație.

Nu amestecați valutele și formatele de preț

Înainte de calcularea cozii, comparați currency din sold cu valuta metodei de preț sau a răspunsului la crearea comenzii. Dacă soldul returnează o valută, iar catalogul de servicii — alta, nu puteți introduce cifrele direct. Este nevoie fie de un calcul oferit de platformă, fie de o metodă de conversie separată și confirmată.

Conversia preliminară pe partea dvs. este comodă pentru planificare, dar are un dezavantaj: serviciul poate aplica un alt curs, un comision sau o regulă de rotunjire în momentul debitării. Este mai sigur să trimiteți comanda cu parametrii pentru care API-ul returnează costul final în valuta soldului sau să obțineți calculul prețului imediat înainte de creare.

Dacă metoda de preț răspunde "price": "12.345", iar soldul stochează valori cu două zecimale, clarificați regula de rotunjire. Nu rotunjiți automat în jos: debitarea efectivă poate fi mai mare. Pentru admiterea cozii folosiți exact suma pe care API-ul o numește cost final al comenzii.

Calculați bugetul cozii înainte de prima cerere

Înainte de lansare, colectați toate cererile și calculați costul lor ținând cont de volum, serviciul ales, regiune, opțiunile suplimentare și comisionul, dacă acesta este transmis separat. Nu comparați available cu prețul de bază din interfață: în API totalul poate depinde de parametrii comenzii concrete.

Să presupunem că în coadă sunt trei comenzi. API-ul de calcul al prețului a returnat pentru ele 18.40, 27.15 și 31.60 în aceeași valută indicată în balance.currency. Bugetul este 77.15. Dacă balance.available este 84.50, după lansarea planificată rămân 7.35. Dacă available este 76.90, nu se poate lansa întreaga coadă.

1. Obțineți prețurile după parametrii reali ai fiecărei comenzi.
2. Adunați costurile finale fără a le schimba formatul și valuta.
3. Comparați bugetul cu available din răspunsul recent al soldului.
4. Dacă soldul este suficient, fixați suma ca rezervare locală de lansare.
5. După crearea fiecărei cereri, reduceți rezervarea locală cu costul confirmat.

Marja reduce riscul de refuz la o debitare suplimentară, dar are un dezavantaj: o parte din fondurile disponibile va rămâne neutilizată, deși coada ar fi putut trece integral.

Faceți o a doua verificare chiar înainte de trimitere

Soldul obținut la pregătirea campaniei își pierde rapid actualitatea. În timpul dintre calcul și lansare, un alt operator, automatizarea sau o comandă activă pot modifica available și reserved. O cerere repetată este necesară după formarea cozii și imediat înainte de prima cerere.

Schema de lucru constă din două etape: mai întâi obțineți prețurile și estimați bugetul, apoi solicitați balance încă o dată. Dacă valoarea available a scăzut și a devenit mai mică decât suma calculată, coada nu se trimite integral. Între verificarea finală și lansare nu trebuie efectuate alte debitări din același cont.

O singură cerere pentru întreaga lansare reduce încărcarea pe API, dar dezavantajul ei este că soldul disponibil se poate schimba cât timp coada lungă este încă procesată.

Cum să lansați coada când fondurile sunt insuficiente

Dacă available este mai mic decât bugetul, nu trimiteți toate cererile în speranța că o parte va trece. Împărțiți coada în pachete al căror cost se încadrează în limita disponibilă. În exemplul cu soldul 76.90 puteți trimite primele două comenzi pentru 45.55, apoi să vă opriți: a treia, pentru 31.60, necesită o verificare repetată.

Stabiliți explicit ordinea cererilor la împachetare. Puteți trimite mai întâi comenzile prioritare sau puteți forma pachete cu cost apropiat. Fiecare variantă are un dezavantaj: ordinea prioritară va amâna pozițiile mai puțin importante, iar sortarea după preț poate perturba planul inițial al campaniei.

• Formați un pachet cu suma nu mai mare decât available curent.
• Creați comenzile din pachet și salvați identificatorii lor.
• Așteptați răspunsurile sau verificați statusurile operațiunilor după expirarea timpului.
• Faceți o pauză dacă acest lucru este cerut de limitele API sau de regulile serviciului.
• Solicitați din nou balance înainte de următorul pachet.

După fiecare pachet orientați-vă după noul răspuns al API, nu doar după deducerea locală din soldul anterior. Calculul local este util pentru control, dar nu vede rambursările, debitările externe și recalcularea rezervărilor.

Protejați bugetul la trimiterea în paralel

La procesarea secvențială este suficient să reduceți limita locală după confirmarea comenzii. În modelul paralel, doi workeri pot vedea simultan available 84.50 și fiecare poate planifica o cheltuială de 60.00. Ambele decizii par admisibile separat, dar împreună depășesc soldul disponibil.

Pentru protecție este nevoie de un contor comun al rezervării locale sau de o coadă accesată atomic. Înainte de trimitere, workerul încearcă să ocupe suma comenzii în acest contor. Dacă limita liberă nu este suficientă, cererea rămâne în așteptare pentru o verificare repetată a soldului.

• Coada secvențială este mai ușor de controlat, dar pornește mai lent.
• Trimiterea în paralel scurtează timpul de lansare, dar necesită blocarea bugetului comun.
• Rezervarea locală reduce conflictele, dar poate rămâne blocată după o defecțiune a workerului.
• Rezervarea pe partea API este mai sigură, dar nu este disponibilă la fiecare platformă.

Dacă procesul s-a încheiat înainte de primirea răspunsului, rezervarea locală nu poate fi considerată imediat cheltuită sau liberă. Mai întâi verificați dacă comanda a fost creată, după identificatorul ei extern sau prin metoda de căutare a operațiunilor.

Folosiți rezervarea API, dacă este prevăzută

Unele API-uri permit crearea unei rezervări pentru un set de operațiuni sau efectuarea unei comenzi în doi pași: calcul, blocarea sumei, confirmare. Într-o astfel de schemă, fereastra în care un alt proces poate cheltui fondurile contului între verificare și debitare este mai mică.

Dacă această metodă există, salvați identificatorul rezervării, suma, valuta, termenul de valabilitate și statusul. Apoi transmiteți acest identificator la crearea comenzilor, dacă acest lucru este cerut de contractul API. După finalizarea cozii, verificați partea neutilizată și faptul ridicării blocării.

Rezervarea API nu rezolvă toate problemele: poate avea un termen scurt de valabilitate, poate să nu acopere comisioanele sau poate fi eliberată după o eroare de confirmare. Rezervarea locală este mai simplu de implementat, dar dezavantajul ei este că nu protejează de cheltuielile create în afara aplicației dvs.

Separați eroarea de sold de soldul zero

Un răspuns cu cod de eroare, un timeout sau o limitare a frecvenței cererilor nu înseamnă că available este zero. Nu introduceți automat ultima valoare cunoscută dacă de ea depinde o lansare mare. Dacă nu este posibil să obțineți un sold recent, coada trebuie pusă pe pauză.

Tratați separat refuzul la crearea comenzii. El poate fi legat de fonduri insuficiente, dar și de un identificator de serviciu greșit, un volum nepermis, o restricție pe canal sau repetarea aceleiași operațiuni. Salvați codul și textul erorii împreună cu identificatorul extern al cererii.

• La eroare de autorizare, reînnoiți accesul și abia apoi repetați cererea.
• La limita de cereri, respectați o pauză conform regulilor API.
• La timeout la creare, verificați mai întâi dacă operațiunea a apărut efectiv.
• La eroare de fonduri insuficiente, opriți pachetul și solicitați balance din nou.

Nu creați duplicate după timeout

Timeout înseamnă că clientul dvs. nu a primit răspuns, nu că serverul nu a procesat cererea. Retrimiterea fără verificare poate crea o a doua comandă și poate ocupa din nou bani. Acest lucru este deosebit de periculos într-o coadă în care reîncercarea automată este configurată pentru mai multe încercări.

Transmiteți un identificator extern unic al comenzii dacă API-ul suportă câmpul client_order_id, external_id sau idempotency_key. Salvați-l înainte de trimiterea cererii. După timeout, găsiți operațiunea după această valoare sau solicitați statusul după identificatorul primit anterior.

Repetarea fără verificare este mai rapidă, dar dezavantajul ei este direct: sunt posibile comenzi duplicate, rezervare dublă și discrepanțe între calculul dvs. al bugetului și debitările efective.

Ce să păstrați în jurnalul de lansare

Jurnalul ajută la reconstituirea desfășurării operațiunii în masă și la explicarea motivului pentru care un anumit pachet s-a oprit. Pentru fiecare lansare salvați timpul celor două verificări, total, available, reserved, currency, bugetul calculat, dimensiunea rezervării locale și lista identificatorilor externi ai cererilor.

Pentru fiecare încercare de creare înregistrați costul, codul răspunsului, identificatorul tehnic al operațiunii și statusul final. Secretele nu ajung în jurnal: tokenurile de autorizare, cheile API, anteturile complete ale cererilor și datele personale trebuie mascate sau excluse înainte de înregistrare.

Logarea completă este comodă la depanare, dar are un dezavantaj: fără filtrare, în stocare pot ajunge date de acces și informații despre clienți.

Testați schema pe o coadă mică

Înainte de o lansare mare, parcurgeți un scenariu scurt: obțineți balance, solicitați prețurile finale, creați un pachet limitat, solicitați din nou balance și comparați modificarea așteptată a available și reserved cu răspunsul efectiv. Astfel puteți observa când serviciul rezervă suma și când o debitează definitiv.

Pachetul de test nu garantează același comportament sub sarcină mare: pot interveni limite, procese paralele sau restricții ale serviciului concret. De aceea, în coada în masă continuați să împărțiți lansarea în pachete, să verificați soldul disponibil între ele și să analizați fiecare refuz separat.