API za račune – integracija in dokumentacija za razvijalce

API po meri poveže vašo spletno trgovino, SaaS, ERP ali lastno aplikacijo z Račun123. Vaš sistem pošlje naročilo prek varne POST zahteve, Račun123 pa na podlagi prejetih podatkov ustvari račun, ga po nastavitvah po potrebi davčno potrdi in pošlje kupcu.

1. Kako deluje integracija?

1. Vaša trgovina ali aplikacija zazna naročilo (npr. po uspešnem plačilu).
2. Vaš strežnik pošlje POST zahtevo na individualni Webhook URL z API ključem in podatki naročila v JSON obliki.
3. Račun123 preveri zahtevo, podatke in identifikator naročila externalOrderId.
4. V produkciji ustvari račun in mu določi številko.
5. Če je omogočeno in pravilno nastavljeno davčno potrjevanje, račun posreduje FURS.
6. Če je omogočeno samodejno pošiljanje in je naveden e-naslov kupca, pošlje račun kupcu.
7. Vaš sistem prejme rezultat obdelave; dogodke lahko preverite v dnevniku webhookov.

Primer: kupcu uspe plačilo v vaši aplikaciji → aplikacija pošlje naročilo Račun123 → ustvari se plačan račun → po potrebi se izvede fiskalizacija → kupec prejme PDF po e-pošti.

2. Nastavitev v Račun123

1. Odprite Nastavitve podjetja → Integracije → API po meri.
2. Vključite integracijo.
3. Kopirajte svoj API ključ in Webhook URL.
4. Po potrebi izberite predlogo računa, predlogo e-pošte, poslovni prostor, elektronsko napravo in operaterja.
5. Nastavite možnosti Samodejno davčno potrdi račune in Samodejno pošlji račun po e-pošti glede na svoj proces.

Varnost: API ključ je skrivnost. Hranite ga na strežniku, ne v javni spletni kodi ali mobilni aplikaciji. Če je razkrit, ga regenerirajte v nastavitvah; stari ključ takoj preneha veljati.

3. Najprej preizkusite povezavo – Sandbox način

1. V nastavitvah API po meri vključite Sandbox način.
2. Pošljite testno POST zahtevo na svoj Webhook URL.
3. V odgovoru preverite normalizedOrder – tako vidite, kako so bili interpretirani podatki naročila.
4. Odprite Dnevnik webhookov in preverite testni dogodek, prejete podatke in morebitne napake.
5. Popravite preslikavo podatkov in test ponovite, dokler ni rezultat pravilen.

Primer testne zahteve (cURL)

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "externalOrderId": "SANDBOX-001",
    "customerName": "Testni kupec",
    "customerEmail": "test@example.com",
    "items": [
      {"name": "Testna storitev", "quantity": 1, "unitPrice": 10, "taxRate": 22}
    ],
    "subtotal": 10,
    "tax": 2.2,
    "total": 12.2,
    "currency": "EUR",
    "isPaid": true
  }'

Primer predpostavlja ceno postavke 10,00 € brez DDV, 22 % DDV in končni znesek 12,20 €. Zamenjajte YOUR_WEBHOOK_URL in YOUR_API_KEY s svojima podatkoma.

Alternativni test: v skladu s tehnično dokumentacijo lahko v JSON dodate "metadata": {"test_connection": true} za posamični preizkus, ne da bi spreminjali globalno nastavitev Sandbox. Za celovito začetno testiranje priporočamo vključen Sandbox način.

Pomembno: v Sandbox načinu ne pričakujte prave številke računa ali PDF povezave. Preverjajte validacijo, preslikavo podatkov in dnevnik dogodkov.

4. Konkreten primer: izdaja računa po uspešnem plačilu

Predstavljajte si, da kupec v spletni trgovini plača letno licenco za 610,00 € (500,00 € osnove + 110,00 € DDV). Ko trgovina potrdi plačilo, njen strežnik Račun123 pošlje naslednjo zahtevo:

Korak 1: POST zahteva z naročilom

POST {webhook_url}
Content-Type: application/json
x-api-key: {api_key}

{
  "externalOrderId": "ORD-2026-0041",
  "customerName": "Podjetje d.o.o.",
  "customerEmail": "racuni@podjetje.si",
  "customerTaxNumber": "SI12345678",
  "items": [
    {
      "name": "Letna licenca za programsko opremo",
      "quantity": 1,
      "unitPrice": 500.00,
      "taxRate": 22
    }
  ],
  "subtotal": 500.00,
  "tax": 110.00,
  "total": 610.00,
  "currency": "EUR",
  "isPaid": true
}

{webhook_url} in {api_key} nadomestite s podatkoma iz nastavitev API po meri. API ključ pošiljajte samo iz strežniškega okolja.

Korak 2: Primer uspešnega odgovora

{
  "received": true,
  "invoiceId": "a7e35f...",
  "invoiceNumber": "R-2026-0041",
  "pdfUrl": "https://..."
}

Opomba: številka računa, ID in URL so ilustrativni. Dejanske podatke vrne API.

Korak 3: Kaj se izvede samodejno?

1. Račun123 na podlagi naročila ustvari račun s podatki podjetja in postavko za 610,00 € skupaj z DDV.
2. Ker je poslano "isPaid": true, se račun označi kot plačan.
3. Če je samodejno davčno potrjevanje omogočeno in pravilno nastavljeno, se izvede tudi postopek fiskalizacije.
4. Če je omogočeno pošiljanje računov in je e-naslov kupca naveden, lahko kupec samodejno prejme račun PDF.
5. Integracija lahko iz odgovora shrani številko računa in PDF povezavo.

Pomembno: polji zoi in eor nista del tukaj dokumentiranega standardnega odgovora. Uspešno davčno potrditev je treba preveriti ločeno. Primer izvedite v produkciji samo z resnično transakcijo; za varen preizkus predhodno uporabite Sandbox.

5. Prehod v produkcijo

1. Preverite pravilnost kupca, postavk, količin, cen, DDV, popustov in končnih zneskov.
2. Preverite, da vsako dejansko naročilo dobi enoličen externalOrderId.
3. Če boste uporabljali davčno potrjevanje, predhodno nastavite namensko digitalno potrdilo, poslovni prostor, elektronsko napravo in operaterja ter ustrezen interni akt.
4. Preverite nastavitve samodejnega pošiljanja e-pošte in predloge dokumentov.
5. Izključite Sandbox način in opravite nadzorovan produkcijski preizkus z dejanskim računom.
6. Preverite nastali račun, morebitno oznako EOR, PDF, e-pošto in dnevnik webhookov.

Navodila za davčno blagajno: Aktivacija davčne blagajne →. Produkcijski test ustvari pravi dokument, zato ga ne izvajajte z izmišljenimi poslovnimi transakcijami.

6. Kateri podatki in procesi so podprti?

• B2C in B2B: ime kupca, e-pošta, davčna številka in naslov kupca.
• Postavke: več izdelkov ali storitev, količine, cene brez DDV, davčne stopnje in opisi.
• Zneski: osnova, DDV, skupni znesek in popusti.
• Plačila: z isPaid: true označite že plačano naročilo; sicer se račun ustvari kot izdan.
• Naročnine: datumi obdobja storitve (serviceFromDate in serviceToDate), datum zapadlosti in opombe.
• Avtomatizacija: nastavljivo davčno potrjevanje, samodejno pošiljanje e-pošte, predloge ter dnevnik webhook dogodkov.
• PDF: pri uspešno ustvarjenem računu produkcijski odgovor vključuje povezavo pdfUrl.

Celoten seznam polj, podatkovnih tipov in primerov najdete v tehnični dokumentaciji.

7. Idempotentnost – preprečevanje dvojnih računov

Polje externalOrderId je obvezno in predstavlja enolično oznako naročila v vašem sistemu. Če isto naročilo pošljete ponovno z enako oznako, Račun123 v okviru istega podjetja ne ustvari drugega računa, ampak vrne podatke že ustvarjenega računa.

Primer: naročilo SHOP-1058 se pošlje dvakrat zaradi omrežne prekinitve. Obe zahtevi uporabljata externalOrderId: "SHOP-1058", zato se izognete podvojenemu računu. Pri ponovnih pošiljanjih ne generirajte nove oznake za isto naročilo.

8. Odgovori API in obravnava napak

Pri uspešno ustvarjenem produkcijskem računu odgovor praviloma vključuje:

{
  "received": true,
  "invoiceId": "uuid-of-created-invoice",
  "invoiceNumber": "R-2026-001",
  "pdfUrl": "https://moj.racun123.si/api/invoices/public-pdf?token=..."
}

Pozor: samo HTTP 200 ali received: true še ni zadostno dokazilo uspešne izdaje. Nekatere poslovne napake se vrnejo s HTTP 200 in poljem error. Vaš sistem mora preveriti celoten odgovor ter pri potrebi preveriti dejanski status dokumenta in davčne potrditve.

• 400: neveljaven JSON, manjkajoča polja ali nepravilen Webhook URL – popravite zahtevo.
• 401: manjkajoč ali napačen API ključ – preverite avtentikacijo.
• 200 z error: zahteva je bila sprejeta, vendar obdelava ni bila v celoti uspešna – preverite dnevnik in stanje računa.
• Prekinitev ali timeout: najprej preverite rezultat, nato po potrebi ponovite zahtevo z istim externalOrderId.

Če fiskalizacija ne uspe, je račun lahko ustvarjen, ne da bi bil uspešno potrjen pri FURS. ZOI ni enako EOR; za preverjanje davčne potrditve spremljajte EOR oziroma dejanski status fiskalizacije.

9. Dnevnik webhookov in diagnostika

V Nastavitve podjetja → Integracije → API po meri → Dnevnik webhookov preverite prejete zahteve, testne dogodke, identifikator naročila in morebitne napake. Pri težavah primerjajte poslan JSON, odgovor API-ja in nastali dokument.

10. Predloge računov in samodejna e-pošta

V nastavitvah integracije lahko izberete predlogo računa in e-pošte. Če omogočite samodejno pošiljanje in posredujete customerEmail, Račun123 po ustrezni obdelavi pošlje račun kupcu. Če želite pošiljanje urejati sami, to možnost izključite in uporabite povezavo do PDF iz uspešnega produkcijskega odgovora.

11. Zmogljivosti in zahtevnejše integracije

Standardni API po meri je namenjen avtomatskemu pošiljanju posameznih naročil in ustvarjanju računov. Za večje obremenitve, več pravnih oseb ali davčnih identifikacij, zahtevne statuse, delna vračila, posebne računovodske tokove in dodatno spremljanje se obrnite na našo ekipo za individualno tehnično presojo.

Pomembno: standardna integracija ni splošni API za poljubno upravljanje vseh dokumentov in podjetij. Dinamična izbira drugega izdajatelja za vsak račun in namenske množične (bulk) končne točke niso del potrjenega standardnega obsega. Zmogljivosti pri velikem številu naročil in morebitni SLA se dogovorijo posebej; brez dogovora ne predpostavljajte zagotovljenega števila zahtev na sekundo.

Pogosta vprašanja

Ali lahko API preizkusim brez pravih računov?

Da. Vključite Sandbox način: preveri avtentikacijo in naročilo, vendar ne ustvari računa, ne fiskalizira in ne pošlje e-pošte.

Ali lahko ponovno pošljem isto naročilo?

Da. Ohranite isti externalOrderId; tako preprečite ustvarjanje dvojnika.

Ali so vsi računi avtomatsko fiskalizirani?

Ne. Davčno potrjevanje je odvisno od nastavitev integracije, pravilno aktivirane davčne blagajne in zakonske obveznosti glede na način plačila.

Ali Račun123 sam pošlje račun kupcu?

Da, če omogočite samodejno pošiljanje in zagotovite ustrezen e-naslov kupca.

Kako vem, da je račun dejansko ustvarjen?

V produkciji preverite invoiceId, invoiceNumber, odsotnost napake in stanje računa v Račun123. Za davčno potrditev preverite tudi EOR.