Versionarea API Stripe: cum funcționează și ce poți copia

Versionarea API Stripe funcționează după dată. Fiecare cont e fixat pe o versiune de API numită după o dată de lansare, iar orice cerere individuală poate înlocui acea fixare printr-un header Stripe-Version. La momentul scrierii (octombrie 2026), versiunea curentă din documentația Stripe este 2026-09-30.endive, iar aceeași schemă o poate copia într-un weekend un API mult mai mic.

Fiecare fapt despre Stripe de mai jos vine din paginile proprii ale Stripe, cu link acolo unde e folosit.

Cum funcționează versionarea API Stripe?

Stripe dă fiecărui cont o versiune de API implicită, iar orice cerere care nu numește o versiune o folosește pe aceasta. Apelanții aleg când trec la alta, schimbând versiunea implicită sau setând o versiune pe cereri individuale.

Articolul de inginerie al Stripe spune că contul e fixat prima dată când face o cerere de API: contul e „automatically pinned to the most recent version available”, iar de atunci fiecare apel primește implicit acea versiune.

Șirul versiunii e o dată. De la lansarea 2024-09-30.acacia, poartă și un nume, ca în 2026-09-30.endive. Data ordonează versiunile, iar numele spune cărei familii de lansări majore îi aparține o versiune.

Cum alegi o versiune pe fiecare cerere?

Trimiteți header-ul Stripe-Version pe cerere sau setați versiunea în SDK. Ghidul de upgrade al Stripe arată forma cu header, iar același apel merge în mediile live și de test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Ghidul Stripe notează că, atunci când setați versiunea global sau pe cerere într-un SDK, obiectele din răspuns vin în acea versiune.

Stripe recomandă și să nu vă bazați pe versiunea implicită a contului. În cuvintele lui, specificați versiunea la fiecare cerere, cu header-ul sau cu un SDK fixat, ca să decidă codul vostru versiunea, nu o setare din dashboard.

SDK-urile se fixează diferit în funcție de limbaj. Documentația spune că versiunile recente ale bibliotecilor cu tipare dinamice folosesc versiunea de API care era cea mai nouă când a apărut lansarea acelui SDK, iar cele puternic tipizate (Java, Go și .NET) sunt fixate pe ea. Instalarea unei versiuni de bibliotecă înseamnă, de fapt, alegerea unei versiuni de API.

Ce se întâmplă cu webhook-urile când se schimbă versiunea?

Un eveniment webhook e randat în versiunea de API atașată endpoint-ului său, nu în versiunea pe care o folosește codul serverului vostru. Documentația Stripe spune că evenimentele folosesc versiunea setată la crearea endpoint-ului, iar în lipsa ei, versiunea implicită a contului. Schimbarea versiunii SDK nu schimbă ce primește handler-ul vostru de webhook.

Calea cererilor și calea evenimentelor pot sta deci pe două versiuni diferite. Pentru destinațiile de evenimente, snapshot_api_version se setează doar la crearea destinației, deci o altă versiune înseamnă o destinație nouă.

Calea de upgrade a Stripe pentru asta e o rulare în paralel. Creați un endpoint nou pe versiunea țintă, trimiteți aceleași evenimente la ambele, învățați handler-ul să proceseze unul și să-l ignore pe celălalt, apoi comutați și dezactivați endpoint-ul vechi. Pentru că fiecare eveniment sosește de două ori în timpul suprapunerii, handler-ul trebuie să fie idempotent. E un tipar bun de copiat pentru orice API care emite evenimente, iar un changelog de webhook-uri e locul în care anunțați schimbările de payload care îl fac necesar.

Ce sunt lansările lunare și cele majore?

De la lansarea 2024-09-30.acacia, Stripe lansează lunar o nouă versiune de API fără schimbări incompatibile și scoate de două ori pe an o lansare majoră, care începe cu o versiune ce conține schimbări incompatibile. Pagina lor de versionare spune că puteți trece la orice lansare lunară fără să vă actualizați codul, în timp ce o lansare majoră poate cere modificări.

Lansările majore poartă nume. Pagina de versionare dă ca exemplu Basil, iar anunțul Stripe despre proces spune că numele vin de la plante, începând cu Acacia, și că lansările lunare păstrează numele lansării majore dinainte, ca numele să semnaleze că e sigur să treceți la ele. Changelog-ul Stripe listează numele în uz, iar la momentul scrierii cea mai nouă intrare e 2026-09-30.endive.

Deci data răspunde la „cât de nou”, iar numele răspunde la „e o graniță de schimbare incompatibilă?” Anunțul Stripe lasă loc și pentru excepții: își rezervă dreptul de a livra în afara ciclului o schimbare incompatibilă acolo unde o integrare ar fi sever afectată fără ea. Anunțul e la Stripe’s new API release process.

Care este ultima versiune a API-ului Stripe?

La momentul scrierii (octombrie 2026), pagina de versionare a Stripe afirmă că versiunea curentă este 2026-09-30.endive, iar changelog-ul ei listează aceeași versiune ca fiind cea mai nouă. Stripe publică o versiune nouă lunar, deci orice șir tipărit într-un articol se învechește repede. Citiți changelog-ul live înainte să fixați ceva și fixați versiunea pe care ați testat-o.

Cum menține Stripe versiunile vechi funcționale?

Stripe menține versiunile vechi în viață scriind fiecare schimbare incompatibilă ca pe un modul autonom de schimbare de versiune și aplicând modulele înapoi, pornind de la forma cea mai nouă a datelor. Articolul lor de inginerie despre versionarea API descrie mecanismul.

Fiecare modul declară ce schimbă, documentează schimbarea și include o funcție de transformare. Articolul dă exemplul unui câmp care trece din șir de caractere în hash. Ca să construiască un răspuns, sistemul stabilește versiunea țintă, apoi merge înapoi în timp și aplică fiecare modul pe care îl găsește pe drum până ajunge la acea versiune.

Din acest design rezultă două efecte secundare, iar articolul le numește pe amândouă. Pentru că modulele declară câmpurile și resursele pe care le ating, Stripe își poate genera changelog-ul de API din ele la deployment. Și pentru că versiunea contului e cunoscută, documentația se poate adapta la ea și poate avertiza despre schimbările incompatibile de la acea versiune încoace.

Cât costă și ce ar trebui să copieze un API mai mic?

Versionarea costă atenție de inginerie, iar Stripe o spune. Articolul de inginerie recunoaște o povară de întreținere și enunță obiectivul că, cu cât e nevoie de mai puțină gândire pentru comportamentul vechi când scrii cod nou, cu atât mai bine. Descrie și revizuiri ușoare de API înainte de lansare, ca să nu mai fie nevoie deloc de o schimbare de versiune.

Un API mic nu își permite un lanț de module pentru fiecare versiune veche și nici nu are nevoie de el. Copiați părțile care poartă valoarea:

1. Versiuni datate. O dată nu cere o judecată despre ce înseamnă „major”, iar apelanții o pot citi. Articolul despre cele mai bune practici de versionare o compară cu schemele pe URL și pe header.
2. O versiune implicită fixată. Fixați contul sau cheia pe versiunea de la prima folosire, ca API-ul să nu se miște niciodată sub o integrare care funcționează.
3. Înlocuire per cerere. Un header care lasă un apelant să testeze o versiune nouă pe un singur apel, în producție, înainte să se angajeze.
4. O versiune pe endpoint-ul de webhook. Payload-urile evenimentelor sunt locul în care apelanții sunt cel mai des luați prin surprindere.
5. O intrare de changelog pe versiune. Faceți-o să numească versiunea, data, cine e afectat și ce trebuie făcut. Ce contează ca schimbare incompatibilă e testul pentru ce își are locul într-o versiune nouă, iar articolul despre changelog-ul API acoperă intrarea în sine.

Săriți peste lanțul de module până când numărul de versiuni acceptate vă obligă la el. Două sau trei versiuni active se pot gestiona cu câteva ramuri și o dată de încheiere, ceea ce închiderea unei versiuni de API explică pas cu pas.

Dacă publicați un changelog datat, istoricul versiunilor e la fel de bun ca intrările lui. În Changeloop, o intrare-ciornă e creată din fiecare pull request integrat și ținută până o aprobă un om, înainte să fie publicată pe pagina de changelog și în feed. Acolo se scrie intrarea pe versiune, iar singura poartă umană e revizuirea care spune ce trebuie să facă un apelant.

FAQ

Care este ultima versiune a API-ului Stripe? La momentul scrierii (octombrie 2026), pagina de versionare a Stripe afirmă că versiunea curentă este 2026-09-30.endive. Stripe scoate o versiune nouă lunar, deci verificați changelog-ul lor înainte să fixați și scrieți versiunea în cod în loc să vă bazați pe cea implicită a contului.

Cum setez versiunea API Stripe pe o cerere? Trimiteți header-ul Stripe-Version, de exemplu Stripe-Version: 2026-09-30.endive, sau setați versiunea în SDK-ul de server, global sau pe cerere. Fără niciuna, o cerere folosește versiunea implicită a contului, pe care o setați în Workbench.

Folosesc webhook-urile aceeași versiune de API Stripe ca cererile mele? Nu neapărat. Evenimentele webhook folosesc versiunea setată la crearea endpoint-ului, iar în lipsa ei versiunea implicită a contului. Actualizarea SDK-ului nu schimbă payload-ul pe care îl primește handler-ul de webhook, deci actualizați endpoint-urile separat și testați-le în paralel.

E versionarea datată în stil Stripe potrivită pentru un API mic? Versiunile datate, o versiune implicită fixată, un header pe cerere și o intrare de changelog pe versiune sunt ieftine și merită copiate. Lanțul intern de module de schimbare de versiune nu, până când susțineți multe versiuni vechi simultan. Porniți cu două versiuni active și o dată de încheiere pentru cea mai veche.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Documentație pentru dezvoltatori