Chei de idempotență într-un API SaaS B2B: cum eviți operațiunile duplicate la reîncercare
Cum proiectezi cheile de idempotență pentru operațiunile de scriere dintr-un API SaaS B2B: identitatea cererii, expirarea, răspunsurile și testele necesare.

Echipa Pentru Fondatori
Platforma fondatorilor din România

O cheie de idempotență permite clientului să repete aceeași cerere de scriere fără să creeze încă o dată obiectul dorit. Problema apare când un API a înregistrat comanda, dar răspunsul s-a pierdut pe rețea. Integrarea nu știe dacă trebuie să trimită din nou cererea; fără o regulă de deduplicare, poate crea două comenzi sau două facturi.

Imagine editorială generată cu OpenAI; interfață ilustrativă, fără date reale.
Unde este necesară cheia
Identifică operațiunile cu efecte care nu pot fi repetate orbește: creare de cont, comandă, transfer, rezervare sau lansarea unei lucrări care trimite ulterior un mesaj. Dacă un client face POST pentru a crea o comandă și conexiunea se întrerupe, a doua cerere trebuie să poată găsi rezultatul primei. Documentația Stripe arată acest mecanism pentru crearea și actualizarea obiectelor sale: clientul trimite o cheie unică, iar reîncercarea cu aceeași cheie poate primi rezultatul cererii inițiale.
Cheia nu înlocuiește limitele de cereri ale API-ului. Prima controlează efectul repetării aceleiași operațiuni; cota controlează cât trafic acceptă serviciul. O integrare poate respecta cota și totuși dubla o comandă dacă reîncearcă o scriere după un răspuns pierdut.
Definește ce înseamnă „aceeași operațiune”
Clientul generează o cheie pentru intenția sa, o păstrează până primește un rezultat clar și o reutilizează numai pentru aceeași cerere. Dacă utilizatorul plasează altă comandă, chiar cu produse identice, este o intenție nouă și cere altă cheie. Propunerea IETF pentru antetul Idempotency-Key recomandă o valoare unică, precum un UUID, și interzice refolosirea ei cu un corp diferit. Documentul este încă un draft, nu un standard final; specificația produsului tău trebuie să definească explicit comportamentul oferit clienților.
Pe server, leagă cheia de organizația clientului și de operațiunea vizată. O cheie folosită de firma A nu ar trebui să blocheze aceeași valoare aleasă întâmplător de firma B. Compară și parametrii importanți ai cererii: dacă aceeași cheie vine cu o altă sumă sau alt destinatar, refuză cererea și explică eroarea. Stripe documentează compararea parametrilor pentru a preveni reutilizarea accidentală a cheii cu altă operațiune.
Salvează rezultatul în locul potrivit
O implementare utilă păstrează starea operațiunii, identificatorul obiectului creat și răspunsul care poate fi retrimis. Rezervă cheia înainte de începerea efectului, astfel încât două cereri sosite simultan să nu pornească amândouă procesarea. Stabilește ce răspuns primește a doua cerere cât timp prima este încă în lucru: așteptare, stare de procesare sau eroare care poate fi încercată din nou. Nu presupune că un simplu SELECT, urmat de INSERT, rezolvă cursa dintre două instanțe ale aplicației.
Persistența cheii trebuie coordonată cu schimbarea de stare pe care o protejează. Dacă baza marchează cererea drept finalizată, dar o operațiune externă încă poate eșua, răspunsul salvat poate descrie un succes inexistent. Pentru un flux cu mai multe servicii, stabilește separat ce efecte au avut loc și cum se reconciliază cele rămase. AWS descrie în Builders' Library tocmai riscul ca o cerere fără răspuns să fi produs deja efectul dorit și rolul unui identificator de cerere în reîncercări sigure.
Publică durata de păstrare și regulile de eroare
Cheile nu pot fi păstrate la nesfârșit fără cost. Specifică perioada în care serverul recunoaște o cerere repetată și ce se întâmplă după expirare. Stripe spune că, pentru API v1, poate elimina cheile după cel puțin 24 de ore; această durată este politica Stripe, nu un prag universal pentru un SaaS B2B. Alege perioada după întârzierile reale ale integrărilor și după riscul operațiunii, apoi documenteaz-o.
Spune și ce erori sunt memorate. Stripe precizează că API v1 păstrează codul și corpul primei cereri după începerea execuției, inclusiv unele răspunsuri 500, în timp ce API v2 are reguli diferite pentru lucrările eșuate sau parțiale. Nu copia mecanic unul dintre aceste comportamente. Decide ce poate recupera clientul, cum află starea obiectului și când o cerere poate fi retrimisă cu aceeași cheie.
Testează cazul în care răspunsul dispare
Într-un mediu de test, trimite o cerere de creare și întrerupe conexiunea după ce serverul a început procesarea. Repetă cererea cu aceeași cheie și verifică existența unui singur obiect, identificatorul din răspuns și lipsa unei a doua notificări sau facturări. Repetă testul cu două cereri simultane, apoi cu aceeași cheie și parametri schimbați. Include și o cheie expirată. Aceste probe arată dacă regula funcționează dincolo de exemplul simplu din documentație.
Jurnalizează cheia, organizația, operațiunea și starea de procesare, fără date sensibile în valoarea cheii. Leagă evenimentul de jurnalul de audit al produsului, dar păstrează separat jurnalul tehnic necesar pentru diagnostic. Dacă o integrare raportează două comenzi, echipa trebuie să poată vedea dacă a trimis aceeași cheie, chei diferite sau o cerere nouă după expirarea perioadei de deduplicare. În documentația pentru clienți, exemplul de reîncercare trebuie să folosească aceeași cheie pentru aceeași intenție și să genereze una nouă pentru următoarea comandă.
Transparență AI: acest conținut poate fi redactat sau structurat cu ajutorul unor instrumente AI și este verificat editorial înainte de publicare. Imaginile generate sau modificate cu AI sunt folosite cu rol ilustrativ.
Întrebări frecvente
Când trebuie clientul să refolosească o cheie de idempotență?
Când repetă aceeași operațiune după un răspuns pierdut sau o eroare temporară, cu aceiași parametri. O operațiune nouă primește o cheie nouă.
O cheie de idempotență garantează că nu apar niciodată duplicate?
Nu singură. Serverul trebuie să păstreze și să verifice rezultatul, să trateze cererile simultane și să coordoneze efectele externe ale operațiunii.