Cum să configurezi reîncărcarea automată a soldului în panoul SMM prin API

Ce trebuie pregătit înainte de configurarea reîncărcării automate

Reîncărcarea automată leagă soldul panoului SMM de un serviciu de plată sau de un sistem de facturare intern. Serviciul verifică soldul, creează o plată la atingerea pragului stabilit și creditează fondurile doar după confirmarea plății. Pentru funcționare sunt necesare documentația API a panoului, acces la API-ul de plată, chei separate pentru mediul de test și cel de producție, precum și un jurnal al tuturor operațiunilor.

Înainte de dezvoltare, verificați dacă API-ul panoului poate returna soldul, accepta o cerere de creditare, afișa istoricul reîncărcărilor și primi un identificator extern al operațiunii. Dacă panoul nu acceptă creditarea prin API, automatizarea va putea doar să creeze o solicitare sau să trimită o notificare operatorului. Dezavantajul acestei variante este că banii vor trebui totuși depuși manual.

Separați verificarea soldului de decizia de plată

Verificarea soldului este mai bine să fie rulată ca un proces separat, conform unui program. Acesta obține soldul, îl compară cu pragul și transmite rezultatul către handlerul de reîncărcare. Nu creați plata direct în momentul răspunsului API fără a verifica operațiunile în curs: procesele paralele pot vedea același sold scăzut și pot crea mai multe plăți.

Înainte de o plată nouă, handlerul trebuie să verifice dacă nu există o operațiune cu statusul „creată”, „în așteptarea plății” sau „în curs de confirmare”. Dacă o astfel de înregistrare există, o nouă încercare nu este pornită până la finalizarea reconcilierii. Dezavantajul procesării secvențiale este că, la un răspuns lent al API-ului extern, reîncărcarea poate începe mai târziu decât în cazul mai multor cereri paralele.

Alegeți pragul și logica sumei de reîncărcare

Pragul soldului se alege cu o marjă pentru comenzile active, coada la furnizori și întârzierile plăților. Pentru un canal cu activitate inegală, orientarea doar după consumul mediu este riscantă: după un stream, lansarea reclamelor sau o comandă în masă, debitările pot crește brusc. Separat se stabilește un nivel critic, la care vine o notificare, dar plata nu este neapărat creată automat.

Suma de reîncărcare poate fi fixă sau calculată în funcție de consumul pentru o perioadă aleasă. Suma fixă este mai simplă pentru control și reconciliere. Dezavantajul ei este că, într-o perioadă liniștită, pe sold pot rămâne fonduri în plus, iar la o creștere bruscă a comenzilor o singură reîncărcare poate să nu fie suficientă. Suma calculată este mai flexibilă, dar necesită curățarea statisticilor de debitările anormale și rambursări.

Configurați limitele financiare separat de prag

Pragul răspunde doar la întrebarea când sistemului i se permite să înceapă procesul de reîncărcare. Limitele răspund la o altă întrebare: câte fonduri are dreptul să debiteze. Stabiliți suma maximă a unei operațiuni, limita totală pentru o perioadă și soldul admisibil după creditare. Aceste reguli se verifică înainte de crearea plății, nu după achitarea ei.

Reîncărcarea automată nu trebuie să debiteze fonduri fără o limită pe operațiune și pe perioadă. Dacă suma calculată depășește limita permisă, operațiunea este mai bine să fie trecută în verificare manuală și să se trimită o notificare. Dezavantajul limitelor rigide este că, la o creștere rapidă a cheltuielilor, soldul poate fi epuizat înainte ca angajatul responsabil să confirme majorarea limitei.

Creați chei separate și protejați accesul

Pentru scriptul de reîncărcare automată folosiți chei API separate cu drepturi minime: citirea soldului, crearea plății, verificarea statusului și creditarea operațiunii confirmate. Accesul la utilizatori, setările serviciilor, comenzi și retragerea fondurilor nu este necesar pentru o astfel de cheie. Dacă serviciul acceptă restricționarea pe adrese IP, permiteți accesul doar de pe serverul de integrare.

Cheile se păstrează în variabile de mediu sau într-un seif securizat de secrete. Nu le transmiteți în codul din browser, în loguri, în depozite publice și în mesajele de eroare. Fiecare cheie trebuie să aibă un proprietar și o procedură clară de înlocuire. Dezavantajul rotației frecvente a cheilor este că reîncărcarea se va opri dacă noul secret nu este actualizat în toate procesele de lucru.

Creați plata cu un identificator unic

Fiecărei reîncărcări i se atribuie un identificator intern înainte de apelarea API-ului de plată. Acesta se salvează în jurnal și se transmite ca cheie de idempotență sau ca număr extern al operațiunii. La un timeout de rețea, aceeași cerere poate fi repetată cu același identificator: serviciul de plată trebuie să returneze operațiunea deja creată, nu să debiteze banii din nou.

Mai jos este un exemplu generic de cerere. Înlocuiți numele câmpurilor și adresele cu valorile din documentația furnizorului concret. În variabila PAYMENT_ID este stocat un ID unic creat în prealabil, iar CALLBACK_URL duce către handlerul de webhook-uri.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Nu determinați unicitatea plății doar după sumă și momentul creării. Două reîncărcări identice pot fi legitime, dar o cerere repetată după o eroare nu este. Dezavantajul ID-ului extern în propria bază de date este că trebuie stocat în siguranță și nu trebuie reutilizat după anularea operațiunii.

Verificați soldul și salvați starea operațiunii

Cererea de sold trebuie executată înainte de decizia privind o nouă reîncărcare și după creditarea reușită. O cerere generică poate arăta astfel: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". În răspuns salvați nu doar suma, ci și momentul verificării, pentru a nu lua decizii pe baza unor date învechite.

Pentru fiecare operațiune păstrați o înregistrare cu ID-ul intern, ID-ul plății la furnizor, suma, valuta, momentul creării, statusul, răspunsurile API și cauza erorii. O succesiune potrivită de stări: „creată”, „în așteptarea plății”, „achitată”, „se creditează”, „creditată”, „anulată”, „necesită verificare”.

Creditarea în panou este permisă doar pentru o plată confirmată și încă neprocesată. Nu rescrieți statusurile fără istoric: în cazul unui litigiu trebuie să se vadă ce cerere a fost trimisă și de ce operațiunea a fost modificată. Dezavantajul unui jurnal detaliat este că poate conține date sensibile, de aceea accesul la el este restricționat.

Primiți webhook-ul și reconciliați statusul plății

Pagina de plată reușită și redirecționarea utilizatorului nu confirmă primirea banilor. Confirmarea o reprezintă webhook-ul de la serviciul de plată sau reverificarea statusului prin API-ul acestuia. La primirea webhook-ului verificați semnătura, momentul trimiterii, ID-ul plății, ID-ul extern, suma și valuta. Abia după aceea treceți operațiunea în starea de plată confirmată.

După verificarea webhook-ului este util să solicitați statusul actual al plății de la furnizor. De exemplu: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Comparați statusul cu datele din jurnal, apoi trimiteți cererea de creditare către panoul SMM cu același ID intern.

Un webhook repetat nu trebuie să creeze o a doua creditare. Handlerul găsește operațiunea după ID-ul extern, vede statusul „creditată” și returnează un răspuns de succes fără acțiuni noi. Dezavantajul webhook-urilor este că pot întârzia sau nu pot ajunge dacă handlerul a fost indisponibil.

Gestionați timeout-urile, reîncercările și plățile blocate

La un timeout după crearea plății, nu trimiteți o cerere nouă cu alt ID. Mai întâi găsiți operațiunea după identificatorul intern sau repetați cererea cu aceeași cheie de idempotență. Dacă furnizorul a acceptat cererea inițială, va returna plata existentă. Acest lucru protejează împotriva debitării duble la întreruperea conexiunii.

Dacă webhook-ul nu a sosit în timpul stabilit, un proces de fundal solicită statusul plății prin API. Verificările repetate se fac cu o pauză crescătoare și un număr limitat de încercări, pentru a nu supraîncărca API-ul și jurnalul. Operațiunea care rămâne mult timp în așteptare este trecută în verificare manuală, nu considerată anulată fără reconciliere.

La răspunsuri privind o eroare temporară de rețea sau indisponibilitatea API-ului, reîncercările sunt acceptabile. La refuzul plății, suma incorectă, semnătura invalidă a webhook-ului sau depășirea limitei, nu merită repetată automat cererea. Dezavantajul reîncercărilor este că complică logica stărilor și pot crea o încărcare suplimentară în cazul unei defecțiuni în masă la furnizor.

Creditați plata confirmată în panoul SMM

Înainte de creditare, handlerul verifică încă o dată: suma nu depășește limita, valuta coincide, operațiunea nu a fost anulată și statusul ei nu este încă „creditată”. În cerere se transmit suma și identificatorul extern al plății. Dacă API-ul panoului acceptă o cheie de idempotență, folosiți același ID intern al operațiunii.

Forma generală a cererii: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

După răspunsul panoului, solicitați din nou soldul și salvați rezultatul în jurnal. Dacă banii au fost debitați de serviciul de plată, dar API-ul panoului a returnat o eroare, nu creați o plată nouă. Operațiunea rămâne în statusul „necesită verificare” până la o nouă încercare de creditare sau o reconciliere manuală. Dezavantajul acestei scheme prudente este că soldul poate să nu fie reîncărcat temporar automat.

Adăugați notificări, întrerupător și verificarea pornirii

Notificările sunt necesare pentru abateri: soldul a scăzut sub nivelul critic, plata a fost refuzată, webhook-ul nu a fost primit, limita a fost depășită, API-ul este indisponibil sau operațiunea necesită verificare manuală. În mesaj este suficient să indicați ID-ul intern, statusul și cauza. Nu includeți în el chei API, semnături de webhook și date de plată.

Lăsați un întrerupător separat pentru reîncărcarea automată, fără a elimina integrarea. Este necesar la schimbarea furnizorului, în timpul lucrărilor tehnice, la suspiciunea unei erori sau la o modificare bruscă a cheltuielilor. Dezavantajul întrerupătorului este evident: dacă nu este pornit din nou după lucrări, soldul poate fi epuizat în timpul comenzilor active.

Listă de verificare înainte de activarea reîncărcării automate

• Verificarea soldului nu creează o plată cât timp există o operațiune neterminată.
• Pentru fiecare plată se creează un ID intern unic și o cheie de idempotență.
• Sunt configurate limite pentru o operațiune și pentru perioada aleasă.
• Webhook-urile sunt verificate după semnătură, sumă, valută și identificator.
• În absența webhook-ului se pornește o reconciliere repetată a statusului prin API.
• Un timeout nu duce la crearea unei a doua plăți înainte de verificarea primeia.
• Creditarea în panou se execută o singură dată și se înregistrează în jurnal.
• Modul de test a fost verificat pe succes, refuz, webhook duplicat și indisponibilitatea API-ului.