Integrare Stripe SmartBill înseamnă să legi webhook-urile Stripe de API-ul SmartBill astfel încât fiecare plată confirmată să genereze exact o factură, nu două. Duplicatele apar pentru că Stripe livrează evenimentele cel puțin o dată, deci același eveniment poate ajunge de mai multe ori la fluxul tău. Pe implementările noastre, fluxul standardizat se pune în aproximativ 30 de minute per client și scoate peste 4 ore de facturare manuală pe lună. În continuare: de unde vin duplicatele, ce cheie de deduplicare folosim și cum arată fluxul care rezistă la retry-uri.
De ce apar facturi duplicate la integrare Stripe SmartBill
Duplicatele apar din livrarea repetată a aceluiași eveniment. Stripe retrimite webhook-ul dacă nu primește un răspuns 2xx la timp. Dacă fluxul tău a emis deja factura și abia apoi a picat, a doua livrare emite a doua factură. Fără o cheie de deduplicare, sistemul nu are cum să știe că a mai văzut evenimentul.
Livrarea de tip at-least-once nu e un bug, e o garanție de proiectare. Stripe reîncearcă livrarea timp de mai multe zile dacă endpoint-ul răspunde cu eroare, exact ca să nu pierzi o plată, conform documentației oficiale Stripe pentru webhook-uri. Idempotența rămâne responsabilitatea ta.
Aici e capcana integrărilor făcute rapid. Toată lumea testează pe o plată reușită. Nimeni nu testează ce se întâmplă când API-ul de facturare răspunde în 12 secunde.
Trei surse de duplicate pe care le vedem în practică
Prima sursă e retry-ul Stripe pe timeout. A doua e coada internă de retry, care reîncearcă o cerere ce de fapt reușise. A treia e omul: cineva emite factura manual exact în intervalul în care fluxul automat încă reîncearcă.
A doua merită detaliată, pentru că e contraintuitivă. API-ul SmartBill nu publică oficial un rate limit, dar în practică peste 200 de cereri pe minut ne-a returnat 429. Când o cerere primește 429 sau se închide pe timeout de rețea, nu știi dacă factura a fost emisă. Un retry naiv o emite a doua oară.
A treia se rezolvă cu proces, nu cu cod. La noi, după trei eșecuri consecutive pleacă alertă pe Slack și factura se emite manual. Regula e simplă: cine emite manual marchează întâi evenimentul ca tratat.
Cheia de deduplicare: event ID-ul Stripe, nu numărul comenzii
Cheia corectă de deduplicare e ID-ul evenimentului Stripe, cel de forma evt_. Rămâne identic la toate retry-urile aceleiași livrări, deci un index unic pe el oprește duplicatul înainte să ajungă la SmartBill. Numărul comenzii nu funcționează ca lacăt, pentru că o comandă poate genera legitim mai multe documente.
Gândește-te la un abonament: plată inițială, stornare parțială, reînnoire luna următoare. Trei documente, o singură comandă. Dacă blochezi pe numărul comenzii, îți lipsesc facturi la închiderea lunii.
Tabelul de deduplicare are trei coloane care contează: event_id cu constrângere unică, status (primit, emis, eșuat) și numărul facturii returnat de SmartBill. Inserția se face înainte de apelul de emitere. Dacă pică pe cheie duplicată, fluxul răspunde 200 și se oprește acolo.
Pentru apelurile pornite din sistemul tău către Stripe ai și mecanismul de idempotency keys. Aceeași idee, în direcția cealaltă.
Cum arată fluxul de integrare Stripe SmartBill, pas cu pas
Fluxul are cinci pași. Verifici semnătura webhook-ului, inserezi event ID-ul în tabelul de deduplicare, mapezi datele pentru factură, apelezi endpoint-ul de emitere și salvezi numărul facturii înapoi în sistem. Fiecare pas are un singur motiv de existență, ceea ce face debugging-ul rapid.
Verificarea semnăturii vine prima, nu ultima. Fără ea, oricine cunoaște URL-ul endpoint-ului îți poate umple seria de facturare cu documente inventate.
Maparea ascunde efortul real. CUI-ul vine din metadata sesiunii de checkout, iar cota de TVA se decide după țara de facturare: 19% sau taxare inversă pentru clienți UE cu cod valid.
Seria de facturare trebuie să existe deja în cont. Nu se creează prin API, ci manual în aplicație, înainte de prima emitere. E detaliul care oprește orice integrare Stripe SmartBill la primul test dacă îl ratezi.
Emiterea se face pe endpoint-ul de facturi din API-ul SmartBill Cloud, cu autentificare Basic pe email și token. Răspunsul conține numărul facturii și link-ul PDF, pe care le scriem în CRM. Configurarea completă e pe pagina de integrare SmartBill.
Orchestrarea o ținem în n8n self-hosted, unde fiecare nod are retry propriu și logica de eroare e vizibilă, nu ascunsă în cod (documentația n8n).
Caz concret: 30 de minute de setup, 4 ore pe lună recuperate
Am construit fluxul pentru clienți din e-commerce, SaaS și servicii profesionale. Rezultatul agregat: peste 4 ore de muncă manuală eliminate lunar per client, aproximativ 30 de minute de implementare de la zero la facturare completă și zero facturi omise, pentru că webhook-ul prinde fiecare tranzacție.
Punctul în care o integrare Stripe SmartBill custom bate integrarea nativă e distribuția cazurilor. Integrările native acoperă bine scenariul standard, plată în RON, date complete, fără logică specială, adică circa 80% din tranzacții. Restul de 20%, plăți în valută, TVA cu regim special, câmpuri custom, clienți fără CUI completat, consumă cel mai mult timp manual.
Aceeași arhitectură rulează identic cu FGO și Oblio, doar conectorul de API diferă. Am documentat implementarea în studiul de caz despre automatizarea facturării cu Stripe, SmartBill, FGO și Oblio.
Ce monitorizezi după ce fluxul intră în producție
Monitorizezi patru lucruri: rata de erori 4xx și 5xx pe endpoint, latența p95, retry-urile pe oră și evenimentele care au ratat a treia încercare. Un flux de facturare care pică tăcut costă mai mult decât unul care nu există.
Pragurile noastre: alertă când rata de erori trece 1% pe 15 minute, plus alertă imediată la al treilea eșec al aceluiași eveniment. Lunar, compari plățile reușite din Stripe cu facturile emise în serie.
Cât costă realist o integrare Stripe SmartBill
Costul unei integrări Stripe SmartBill are două componente: abonamentele și implementarea. SmartBill Cloud pornește de la aproximativ 29 lei pe lună, iar pachetul cu acces API se situează în jur de 59 până la 119 lei pe lună. Stripe taxează per tranzacție, deci nu adaugă abonament fix.
Pe orchestrare, n8n Community Edition self-hosted e gratuit și fără limită de execuții. Un VPS modest acoperă circa 10.000 de execuții pe zi, deci fluxul rulează practic pe costul serverului.
Un flux standard durează în jur de 30 de minute. Unul cu condiții multiple, tratare de erori și stornare automată cere 1 până la 3 zile. Contextul mai larg e în ghidul complet de integrări API.
Ce poți face azi, în trei pași
Numără plățile reușite din Stripe pe ultima lună și compară-le cu facturile emise. Diferența îți spune dacă ai deja o problemă. Apoi creează tabelul de deduplicare cu index unic pe event ID, chiar dacă fluxul actual nu îl folosește. E o modificare de cinci minute care oprește o clasă întreagă de probleme, nu o instanță.
La final, scrie regula pentru intervenția manuală și pune-o unde o vede echipa de facturare. Fără ea, orice integrare Stripe SmartBill corectă tehnic produce duplicate prin oameni.
Întrebări frecvente despre integrare Stripe SmartBill
Cum previn facturile duplicate la o integrare Stripe SmartBill?
Folosește ID-ul evenimentului Stripe ca cheie unică într-un tabel de deduplicare și inserează-l înainte de apelul de emitere. Dacă inserția pică pe cheie duplicată, fluxul răspunde 200 și se oprește. Numărul comenzii nu e o cheie bună: o comandă poate genera legitim mai multe documente.
De ce trimite Stripe același webhook de mai multe ori?
Pentru că livrarea e de tip at-least-once. Dacă endpoint-ul tău nu răspunde 2xx rapid, Stripe reîncearcă timp de mai multe zile, ca să nu pierzi evenimente de plată. Comportamentul e intenționat. Sistemul care primește evenimentele trebuie să fie idempotent, adică să dea același rezultat oricâte livrări ar primi.
Cât durează o integrare Stripe SmartBill?
Un flux standard se implementează în aproximativ 30 de minute, pentru că arhitectura e reutilizabilă între clienți. Unul cu logică condițională, TVA special, conversii valutare și stornări automate cere între 1 și 3 zile. Diferența vine din cazurile de excepție, nu din conectare.
Ce fac dacă API-ul SmartBill returnează 429?
Pui cererea într-o coadă și o reîncerci exponențial, dar verifici întâi dacă factura a fost totuși emisă, ca să nu creezi un duplicat. Am văzut 429 la peste 200 de cereri pe minut. După trei eșecuri pleacă alertă pe Slack și factura se emite manual.
Merge aceeași soluție cu FGO sau Oblio?
Da. Logica e identică pentru toate trei, diferă doar conectorul de API și formatul payload-ului. Am rulat aceeași arhitectură pe SmartBill, FGO și Oblio, cu aceleași reguli de deduplicare. Dacă folosești altă aplicație de facturare cu API, fluxul se adaptează.
De ce nu folosesc pur și simplu integrarea nativă?
Integrarea nativă acoperă bine cazul simplu: plată în RON, date complete, fără logică specială, adică circa 80% din tranzacții. Restul de 20% generează cele mai multe ore de muncă manuală. Dacă vinzi în valută sau ai clienți UE cu taxare inversă, o integrare Stripe SmartBill custom rezolvă exact partea care doare.
Următorul pas
Dacă emiți facturi din Stripe și nu ai un tabel de deduplicare, ai deja riscul, chiar dacă nu s-a materializat încă. Vezi fluxul complet pe pagina de automatizare facturare sau scrie-ne pentru o evaluare de 30 de minute pe fluxul tău.