Gestionarea statusului „în execuție” la verificarea comenzii prin API

Ce înseamnă processing în răspunsul API

Statusul processing, in_progress sau o altă stare echivalentă înseamnă că furnizorul a preluat comanda în lucru, dar nu a înregistrat rezultatul final. Pentru serviciile de promovare, aceasta poate fi verificarea linkului, așteptarea la coadă, lansarea sarcinii sau livrarea treptată a volumului comandat.

Processing nu confirmă executarea cu succes și nu înseamnă o eroare. După el, comanda poate trece în completed, partial, canceled sau failed. Cât timp furnizorul returnează un status intermediar, nu crea o cerere nouă pentru același link și același volum.

HTTP 200 cu statusul processing înseamnă un răspuns API reușit, nu finalizarea cu succes a comenzii. Aceste evenimente trebuie stocate și gestionate separat.

Ce date sunt necesare pentru verificarea comenzii

Pentru polling este nevoie de ID-ul extern al comenzii, pe care furnizorul l-a returnat la creare. Salvează-l împreună cu ID-ul intern, volumul inițial, parametrii serviciului, linkul, timpul creării și răspunsul API inițial. Căutarea comenzii după numele canalului, link sau volum nu este fiabilă: aceste valori pot coincide pentru mai multe cereri.

Dacă după creare a venit un timeout, nu retrimite cererea automat. Furnizorul ar fi putut primi solicitarea, iar răspunsul s-ar fi putut pierde pe drum. Folosește mai întâi metoda de căutare a comenzii, dacă există în documentație, sau transmite cazul pentru verificare.

Dezavantajul stocării doar a statusului curent este că, în caz de dispută, nu se poate reconstitui când comanda a trecut în processing, dacă a existat progres și ce răspunsuri au venit anterior.

Exemplu de cerere de status prin curl

Adresa exactă, metoda de autorizare și numele câmpurilor trebuie preluate din documentația furnizorului. Mai jos este prezentat un șablon: valorile din paranteze unghiulare trebuie înlocuite cu datele API-ului concret.

Cerere GET pentru o singură comandă

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Exemplu de răspuns:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Câmpurile completed_quantity și remains sunt prezentate doar ca exemplu de structură. Furnizorul poate folosi progress, start_count, balance sau alte denumiri. Dezavantajul abordării GET este că unele API-uri acceptă verificarea statusului doar prin POST.

Exemplu de cerere POST și verificare în lot

Cerere POST pentru statusul unei singure comenzi

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Nu transmite cheia API în șirul URL. Adresele cererilor ajung în jurnalele proxy, sistemele de analiză, istoricul browserului și logurile tehnice. Dezavantajul POST este că este mai greu de verificat manual prin bara de adrese, dar acesta nu este un motiv pentru a muta secretul în URL.

Cerere în lot pentru comenzile active

Dacă API-ul acceptă verificare în lot, trimite mai multe ID-uri într-o singură cerere:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Asociază răspunsul cu comanda internă după ID-ul extern, nu după poziția elementului în masiv. Dezavantajul verificării în lot: furnizorul poate să nu returneze toate comenzile, să limiteze dimensiunea listei sau să raporteze o eroare doar pentru un singur ID.

Cum să stabilești polling-ul pentru processing

După primul răspuns processing, pune următoarea verificare în coadă. Alege intervalul în funcție de documentația API, limitele de frecvență și natura serviciului. Pentru sarcinile în care statusul se schimbă rapid, este acceptabilă o verificare mai frecventă la început. Pentru promovarea treptată, cererile scurte constante de obicei nu oferă informații noi.

O schemă practică este să mărești pauza după răspunsuri processing identice. Prima verificare are loc după o întârziere inițială, apoi intervalul crește până la un maxim stabilit. Dacă API-ul returnează progres sau un timp nou de actualizare, numărătoarea poate începe de la această modificare.

• După crearea comenzii, nu verifica statusul imediat de multe ori la rând: serviciului îi poate fi nevoie de timp pentru a o pune în coadă.
• La processing repetat, mărește intervalul dintre cereri, nu menține o frecvență constantă.
• Adaugă o mică variație aleatorie la timpul de lansare a sarcinilor, pentru ca comenzile să nu interogheze API-ul simultan.
• Dacă furnizorul transmite Retry-After sau o recomandare similară, folosește-o cu prioritate.
• Pentru comenzile cu webhook-uri, păstrează un polling de control: notificarea poate să nu ajungă.

Dezavantajul polling-ului rar este că interfața poate afișa un status vechi după finalizarea efectivă. Dezavantajul polling-ului prea frecvent este riscul de a atinge limitele API, de a primi 429 și de a crea o încărcare suplimentară.

Ce timpi să stochezi pentru controlul processing

Pentru a distinge execuția normală de o blocare, un singur status curent nu este suficient. Pentru fiecare comandă activă, stochează timpul creării, prima primire a processing, ultimul răspuns API reușit, ultima modificare a statusului extern și ultima modificare a progresului.

De asemenea, este util să salvezi volumul inițial, volumul executat confirmat, restul și statusul original al furnizorului. Dacă API-ul nu returnează progres, acesta nu este un motiv să consideri comanda blocată: orientează-te după timpul ultimului răspuns și perioada de procesare estimată, dacă este indicată în condițiile serviciului.

Timpul maxim de așteptare nu poate fi stabilit printr-un singur număr pentru toate serviciile. Folosește termenul pe care furnizorul îl indică pentru serviciul concret, cu o rezervă internă pentru coadă și actualizarea datelor. Dacă termenul nu este indicat, stabilește o regulă separată pentru fiecare categorie de servicii și revizuiește-o pe baza istoricului procesării efective.

Ce să faci dacă processing nu se schimbă

Un processing îndelungat nu dovedește o eroare. Verifică mai întâi dacă au venit răspunsuri API reușite, dacă completed_quantity sau remains s-au modificat, dacă au existat webhook-uri și dacă regulile serviciului s-au schimbat. Absența unei creșteri vizibile poate fi legată de întârzierea statisticilor platformei sau de faptul că furnizorul actualizează progresul doar la final.

Când termenul intern de așteptare este depășit, nu anula comanda automat. Efectuează o verificare de status în afara programului, solicită datele printr-o metodă separată, dacă este prevăzută, și verifică istoricul notificărilor. Dacă furnizorul confirmă în continuare processing, treci comanda într-o stare internă „necesită verificare”, dar păstrează statusul extern fără a-l substitui.

• Înregistrează timpul ultimului răspuns confirmat și întregul răspuns API.
• Verifică dacă progresul s-a modificat de la interogarea anterioară.
• Reduce frecvența cererilor automate după atingerea pragului intern.
• Transmite la suport ID-ul extern, linkul, parametrii serviciului, istoricul statusurilor și erorile tehnice.
• Nu relansa restul până la răspunsul furnizorului sau un status final explicit.

Dezavantajul verificării manuale este că comanda necesită atenția suportului. Dar anularea automată sau duplicatul sunt mai periculoase: execuția poate continua la furnizor.

Cum să distingi o eroare de cerere de statusul comenzii

O eroare de rețea, un timeout, HTTP 429 și un răspuns 5xx nu comunică starea comenzii în sine. Ele înseamnă doar că nu s-a putut obține un status nou fiabil. Într-o astfel de situație, păstrează ultimul status confirmat, înregistrează eroarea tehnică și planifică o nouă verificare.

La 429, ține cont de Retry-After, dacă antetul este transmis. La erori temporare de rețea și 5xx, mărește pauza dintre încercări. La eroare de autorizare, semnătură sau drepturi de acces, nu face retry-uri frecvente: trebuie verificate cheia, valabilitatea tokenului, restricțiile IP și setările de acces.

Dacă API-ul a returnat HTTP 200, dar JSON-ul nu poate fi parsat sau răspunsul nu conține order_id și status, salvează integral corpul răspunsului și marchează verificarea ca incorectă. Nu înlocui absența statusului cu completed, canceled sau processing.

Când să oprești cererile automate repetate

Polling-ul nu trebuie să fie infinit. Limitează numărul de reîncercări tehnice pentru erori temporare și controlează separat termenul total în care comanda se află în processing. După epuizarea limitei de retry-uri, treci sarcina de verificare în coada de analiză, nu crea cereri noi în fiecare minut fără rezultat.

Repetarea cererii de status este de obicei sigură dacă metoda doar citește date. Metodele de creare, anulare, alimentare, repornire și rambursare nu pot fi repetate mecanic după un timeout. Fără o cheie idempotentă sau o confirmare explicită a furnizorului, o astfel de repetare poate modifica comanda de două ori.

Dezavantajul limitării retry-urilor este că o parte din actualizări devine o sarcină manuală. Retry-urile infinite sunt mai rele: maschează eroarea, consumă limitele și complică analiza jurnalelor.

Cum să accepți statusul final după processing

Nu permite trecerea inversă din completed în processing din cauza unui răspuns de polling întârziat sau a unui webhook vechi. La fiecare actualizare, compară timpul evenimentului de la furnizor, numărul de ordine al versiunii, dacă există, și starea internă curentă.

• new și pending pot trece în processing, canceled sau failed.
• processing poate trece în completed, partial, canceled sau failed.
• partial nu trebuie considerat automat completed.
• completed, canceled și failed sunt de obicei considerate finale și blochează revenirea automată înapoi.
• Un status necunoscut sau o tranziție nepermisă necesită o verificare separată.

Nici tabelul rigid de tranziții nu este lipsit de dezavantaje: furnizorul poate adăuga o stare nouă corectă. De aceea, păstrează statusul original și nu îl suprascrie cu clasificarea internă.

Cum să gestionezi partial și restul comenzii

Partial înseamnă că a fost confirmată doar o parte din volumul inițial. Răspunsul API poate conține cantitatea efectiv executată, restul, motivul și datele despre compensare. Stochează aceste valori separat: volumul inițial al comenzii nu poate fi înlocuit cu cantitatea executată.

Un exemplu de răspuns final poate arăta astfel:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Stabilește mai întâi ce anume confirmă API-ul: rambursarea a fost deja efectuată, rambursarea este doar planificată, restul a fost anulat sau este necesară o solicitare la suport. Dacă nu există câmp despre rambursare, nu considera restul compensat automat.

Nu relansa partea neexecutată fără o decizie separată. Furnizorul poate încă finaliza calculul, statisticile platformei se pot actualiza cu întârziere, iar o cerere repetată poate crea o promovare duplicată. Dezavantajul așteptării confirmării este că restul nu va fi închis instantaneu, dar nu va apărea o comandă suplimentară.

Webhook-urile nu înlocuiesc verificarea de control

Webhook-ul permite actualizarea imediată a cardului comenzii după eveniment, fără a aștepta următorul polling. În handler, găsește comanda după ID-ul extern, verifică semnătura sau secretul, salvează ID-ul evenimentului și aplică tranziția doar după verificarea admisibilității.

Livrarea repetată a webhook-ului trebuie să fie sigură: același eveniment nu poate fi considerat o modificare nouă. Evenimentele pot sosi și în ordine greșită, așa că nu readuce o comandă finală înapoi doar pe baza unui processing întârziat.

Polling-ul de control este necesar chiar și cu webhook-uri stabile. Dezavantajul webhook-urilor este configurarea mai complexă: este nevoie de un handler disponibil, protecție împotriva cererilor false, deduplicare și jurnal de evenimente.

Ce să afișezi clientului la processing și blocare

În interfață nu este nevoie să afișezi întregul JSON tehnic. Pentru processing este suficientă starea „comandă în lucru”. Dacă API-ul a transmis un progres fiabil, afișează volumul confirmat separat de cel inițial și nu îl prezenta drept rezultat final.

Pentru o comandă care a depășit termenul intern de control, folosește o stare clară precum „verificăm execuția”. Nu anunța anularea, rambursarea sau finalizarea completă până când acestea nu sunt confirmate de răspunsul furnizorului.

Notificările sunt utile la acceptarea comenzii, execuția finală, partial, anulare, eroare și necesitatea verificării. Mesajele după fiecare polling creează zgomot și nu ajută clientul să înțeleagă starea reală a cererii.

Ce înregistrări sunt necesare în jurnalul de procesare

Istoricul răspunsurilor ajută la analiza unui processing blocat, a unui webhook pierdut, a unei dispute privind execuția parțială și a unei discrepanțe între interfață și API. Pentru fiecare solicitare, salvează ID-ul extern, sursa actualizării, timpul cererii și al răspunsului, codul HTTP, statusul original, statusul normalizat, progresul, restul și textul erorii tehnice.

Nu înregistra în logurile obișnuite chei API, tokenuri, semnături și alte secrete. Restrânge accesul la răspunsurile brute: acestea pot conține date care nu ar trebui să apară în interfața de suport.

Înainte de lansare, verifică scenariile cu processing repetat, absența progresului, timeout, 429, eroare 5xx, JSON incorect, webhook întârziat, webhook duplicat, partial, canceled și status necunoscut. Modul de test este util pentru structura integrării, dar dezavantajul său este că poate să nu reproducă cozile și întârzierile reale ale API-ului de producție.