Stripe integracija v Račun123 (vodič korak za korakom)

Ta vodič te bo v nekaj minutah pripeljal do tega, da se po Stripe plačilu
račun samodejno ustvari, davčno potrdi in pošlje stranki.

1. Odpri Stripe integracijo v Račun123

Pojdi na Nastavitve → Več nastavitev → Integracije → Stripe.

Tukaj vidiš:

• Webhook URL
• Webhook skrivnost (prazno polje)
• ID podjetja (companyId)

Produkcijski Webhook URL je:

https://moj.racun123.si/api/integrations/stripe-invoicing

👉 To stran pusti odprto, ker boš podatke potreboval v naslednjih korakih.

2. Dodaj webhook v Stripe

Odpri Stripe Dashboard:

👉 Odpri Webhooks direktno

Nato klikni Add endpoint.

Korak 1 (Stripe ekran, ki zmede)

Ko klikneš Add endpoint, Stripe najprej vpraša, za kateri račun želiš prejemati dogodke.

• izberi Your account (levo)
• klikni Continue

Alternativa: najdi Webhooks preko iskanja

Če v meniju ne najdeš “Developers”, lahko uporabiš iskanje v Stripe:

• v zgornje iskalno polje vpiši: webhooks
• klikni na Webhooks ali Create a webhook

V polje Endpoint URL prilepi:

https://moj.racun123.si/api/integrations/stripe-invoicing

Obvezna eventa za izdajanje računov

Nato klikni Select events in izberi:

checkout.session.completed
invoice.paid

Po želji lahko dodaš še:

customer.subscription.updated

Ta event je uporaben za spremljanje sprememb naročnin (paket, status, dostop), ni pa potreben za samo izdajanje računov.

3. Poveži webhook skrivnost

Odpri webhook, ki si ga pravkar ustvaril.

Pri “Signing secret” klikni Reveal.

Kopiraj vrednost, ki se začne z whsec_, in jo prilepi v Račun123 v polje:

Webhook skrivnost

Kako veš, da je webhook pravilno nastavljen?

Ko je webhook pravilno dodan, moraš v Stripe videti:

• status Active
• pravilen Endpoint URL
• izbrana eventa checkout.session.completed in invoice.paid
• viden Signing secret (whsec_…)

Če si dodatno vključil tudi customer.subscription.updated, je to samo plus.

👉 Če vidiš to, je webhook pravilno nastavljen.

Pogosta napaka: napačen način (Test / Live)

Stripe ima ločen Test in Live način.

• Webhook mora biti dodan v istem načinu, kot delaš test ali produkcijo

👉 Če testiraš v Test mode, webhook v Live mode ne bo deloval.

4. Dodaj companyId v Stripe plačilni flow

V vsak Stripe flow moraš poslati:

metadata: {
  companyId: "tvoj-id"
}

In email kupca:

customer_email: user.email

Če imaš enkratne nakupe

Običajno zadostuje:

• Stripe Checkout
• checkout.session.completed
• metadata.companyId
• email kupca

V tem primeru je nastavitev praviloma enostavnejša.

Če imaš naročnine, obnovitve ali nadgradnje

Poleg osnovne nastavitve moraš paziti še na to:

• da uporabljaš tudi invoice.paid
• da uporabljaš isti Stripe customer za istega kupca
• da je logika povezave med Stripe stranko in podjetjem v Račun123 dosledna
• da so nadgradnje in proracije pravilno vezane na isti subscription/customer flow

Če uporabljaš naročnine:

mode: 'subscription'

Hitri povzetek: končna konfiguracija

customer_email: user.email,
metadata: {
  companyId: "VAŠ_COMPANY_ID"
}

mode: 'subscription',
customer_email: user.email,
metadata: {
  companyId: "VAŠ_COMPANY_ID"
}

5. Testiraj povezavo

V Stripe vklopi Test mode.

Če imaš enkratne nakupe

Testiraj vsaj:

• enkratno plačilo

Preveri:

• ali se pojavi checkout.session.completed
• ali se v Račun123 zabeleži dogodek
• ali se ustvari pravilen račun

Če imaš naročnine

Testiraj vsaj:

• novo naročnino
• obnovo naročnine
• nadgradnjo obstoječe naročnine

Preveri:

• ali se pojavi invoice.paid
• ali se zapis pojavi v dnevniku webhookov v Račun123
• ali se ustvari pravilen račun

Če uporabljaš Sandbox način v Račun123:

• dogodek se zabeleži v dnevnik
• račun se še ne ustvari zares

6. Vklopi avtomatiko

Ko test deluje, vklopi:

• ✅ Samodejno davčno potrjevanje
• ✅ Samodejno pošiljanje računa po e-pošti

Po potrebi nastavi še:

• oznako poslovnega prostora
• oznako naprave
• operaterja

7. Izklopi Sandbox

Ko vse dela:

Izklopi Sandbox način

👉 Od tega trenutka naprej se računi dejansko ustvarjajo.

Kako Stripe integracija deluje v praksi?

Ključno pravilo je naslednje:

To pomeni, da se račun ne ustvari ob vsakem Stripe eventu, ampak ob pravem plačilnem eventu za posamezen scenarij.

A) Enkratno plačilo preko Stripe Checkout

• uporabnik opravi enkratni nakup
• Stripe pošlje checkout.session.completed
• Račun123 ustvari račun

B) Prva sklenitev naročnine

• uporabnik začne naročnino
• običajno dobiš checkout.session.completed, pogosto pa tudi invoice.paid
• pri naročninah je za zanesljivo računovodsko logiko pomemben tudi invoice.paid

C) Obnova naročnine

• Stripe praviloma ne naredi novega checkouta
• ustvari invoice in po uspešnem plačilu pošlje invoice.paid
• račun se zato ustvari na invoice.paid

D) Nadgradnja paketa med obračunskim obdobjem

• Stripe lahko izračuna razliko oziroma proracijo
• v takem primeru lahko pride samo invoice.paid, brez novega checkout.session.completed
• zato mora integracija za nadgradnje poslušati tudi invoice.paid

E) Sprememba statusa naročnine

• sprememba paketa
• premor naročnine
• preklic
• sprememba obdobja

V teh primerih je customer.subscription.updated uporaben za sinhronizacijo stanja ali dostopa, ne pa kot glavni trigger za račun.

Hitra tabela: scenarij → kateri event ustvari račun?

Kako deluje na kratko?

1. Stripe pošlje ustrezen webhook
2. Račun123 prebere dogodek
3. ustvari račun v pravem podjetju
4. po potrebi ga davčno potrdi
5. pošlje PDF na email

Če nekaj ne dela (hitri checklist)

Ni webhooka?

• Preveri URL
• Preveri ali si v pravem načinu (Test / Live)

Ni računa pri enkratnem plačilu?

• Preveri checkout.session.completed
• Preveri companyId

Ni računa pri naročnini, obnovitvi ali nadgradnji?

• Preveri invoice.paid
• Preveri ali Stripe za ta scenarij sploh ustvari invoice
• Preveri metadata oziroma companyId logiko

Se je naročnina spremenila, račun pa ne?

• customer.subscription.updated sam po sebi še ne pomeni, da je bil invoice plačan
• račun se mora vezati na dejansko uspešno plačilo oziroma invoice flow

Ni emaila?

• Email ni poslan v Stripe flow
• Pošiljanje emaila ni vklopljeno

Pogosta vprašanja

Ali zadošča samo checkout.session.completed?

Ne, če uporabljaš naročnine. Za naročnine, obnovitve in nadgradnje potrebuješ tudi invoice.paid.

Ali moram vključiti customer.subscription.updated?

Priporočljivo da. Uporaben je za spremembe paketa, statusa in dostopa. Ni pa najboljši glavni trigger za izdajanje računa.

Ali se račun ustvari ob vsakem Stripe eventu?

Ne. Račun se ustvari ob eventu, ki pomeni dejansko uspešno plačilo za konkreten scenarij.

Ali se račun ustvari vsakič, ko podjetnik prejme denar prek Stripe?

Načeloma da. Pri enkratnih nakupih običajno ob checkout.session.completed, pri naročninah, obnovitvah in mnogih nadgradnjah pa ob invoice.paid.

Ali lahko imam več podjetij?

Da, vsako podjetje ima svoj companyId.

Ali moram imeti davčno potrjevanje?

Če posluješ z gotovino, karticami ali spletnimi plačili, je to pogosto potrebno. Več si lahko prebereš v članku
Kdaj je davčno potrjevanje potrebno?.