Dokumentacija API

Vse kar potrebujete za integracijo e-Račun Hub API v vašo aplikacijo.

Osnovni naslov

https://www.podjetnikovpomocnik.net/e-invoicing

Vse spodaj navedene poti so relativne glede na ta naslov. Celoten naslov končne točke je torej npr. https://www.podjetnikovpomocnik.net/e-invoicing/api/v1/validate-raw-xml.

POST /api/v1/convert

Pretvori univerzalni JSON model v e-SLOG 2.0 XML in/ali PDF račun. PDF različica lahko vključuje UPN QR kodo za takojšnje plačilo — pišite na info@podjetnikovpomocnik.net.

Query parametri

Parameter Vrednosti Privzeto
formateslog20eslog20
outputxml · pdf · bothxml

Primer zahteve

POST https://www.podjetnikovpomocnik.net/e-invoicing/api/v1/convert?format=eslog20&output=xml
Content-Type: application/json

{
  "invoiceIdentifier": "2026-0001",
  "issueDate": "2026-04-23",
  "serviceDate": "2026-04-23",
  "dueDate": "2026-05-08",
  "purchaseOrder": "PO-12345",
  "seller": {
    "name": "Moje Podjetje d.o.o.",
    "taxId": "12345679",
    "iban": "SI56020170014356205",
    "isVatObligated": true
  },
  "buyer": { "name": "Kupec d.o.o.", "taxId": "87654326" },
  "items": [{ "description": "Svetovanje", "quantity": 10, "unitPrice": 85, "vatRate": 0.22 }],
  "paymentInfo": { "iban": "SI56020170014356205", "reference": "SI1220260008" }
}

Primer odgovora

{
  "success": true,
  "xmlContent": "<?xml version=\"1.0\" ...><Invoice xmlns=\"urn:eslog:2.00\">...</Invoice>",
  "pdfBase64": null,
  "issues": []
}

Številka naročilnice

Polje purchaseOrder zapiše številko naročilnice kupca (EN 16931 BT-13). V e-SLOG 2.0 se zapiše kot referenca ON v skupini G_SG1, na PDF-ju pa se izpiše med opombami. Polje je neobvezno — če ga izpustite, se skupina G_SG1 ne zapiše.

Neprepoznana polja

Polja, ki jih model ne pozna, se pri pretvorbi prezrejo — pretvorba se izvede, v odgovoru pa za vsako tako polje dobite opozorilo (severity: "Warning"). Tako tipkarska napaka v imenu polja ne ostane neopazna. 

{
  "success": true,
  "xmlContent": "<?xml version=\"1.0\" ...>",
  "issues": [
    {
      "field": "purchaseOrderNumber",
      "message": "Polje 'purchaseOrderNumber' ni prepoznano in je bilo prezrto.",
      "severity": "Warning"
    }
  ]
}
POST /api/v1/validate

3-nivojsko preverjanje JSON modela (poslovna pravila + slovenska skladnost + XSD shema).

{
  "isValid": false,
  "issues": [
    {
      "field": "seller.taxId",
      "message": "Davčna številka prodajalca ni veljavna.",
      "severity": "Error"
    }
  ]
}
POST /api/v1/validate-raw-xml

Preverjanje obstoječe XML datoteke: struktura po e-SLOG 2.0 XSD shemi, nato pa še seštevki in zneski postavk, davčne kode in stopnje, davčna številka, IBAN in sklic za plačilo ter elektronski podpis, če je priložen. Telo zahteve mora biti application/xml, text/xml ali text/plain.

Vsebinska preverjanja se izvedejo le, kadar XSD validacija ne najde napak — ugotovitve o seštevkih na strukturno pokvarjenem dokumentu so šum. Izklopite jih lahko z ?consistency=false, preverjanje podpisa pa z ?signature=false. 

POST https://www.podjetnikovpomocnik.net/e-invoicing/api/v1/validate-raw-xml
Content-Type: application/xml

<?xml version="1.0" encoding='UTF-8'?>
<Invoice xmlns="urn:eslog:2.00">...</Invoice>

Odgovor je vedno HTTP 200, tudi kadar račun ni veljaven. Veljavnost preverite v polju isValid, ne prek statusne kode.

Nivoji preverjanja

Nivo 1 XSD shema POST /api/v1/validate & /api/v1/validate-raw-xml

Preverja strukturno ustreznost XML glede na uradno e-SLOG 2.0 XSD shemo (UJP/GZS).

Nivo 2 Poslovna pravila POST /api/v1/validate

Preverja SI davčno številko (kontrolna številka), veljavnost IBAN, datumsko logiko in obvezna polja.

Nivo 3 Slovenska skladnost POST /api/v1/validate

UJP-specifična pravila: zaokroževanje zneskov, kontrolna številka za SI12 sklice, pravilna uporaba DDV kategorij (S, E, AE).

Nivo 4 Preverjanje izdelanega dokumenta POST /api/v1/validate-raw-xml

Nivoja 2 in 3 potrebujeta JSON model, zato se na naloženem XML izvedejo preverjanja, ki jih je mogoče opraviti neposredno na dokumentu: seštevki in zneski postavk, razčlenitev DDV, ujemanje davčnih kod in stopenj, davčna številka in ID za DDV, IBAN in sklic ter elektronski podpis.

Nivoji se torej ne seštevajo v eno lestvico: /api/v1/validate preverja vhodne podatke pred izdelavo e-računa, /api/v1/validate-raw-xml pa že izdelan dokument. Noben od njiju ni nadmnožica drugega.

POST /api/v1/visualize

Pretvori e-SLOG 2.0 XML v berljiv dokument HTML — tako, kot ga vidi prejemnik. Uporabno za predogled, tiskanje ali prilogo k e-računu. Isti tipi vsebine kot pri validate-raw-xml. 

POST https://www.podjetnikovpomocnik.net/e-invoicing/api/v1/visualize
Content-Type: application/xml

<?xml version="1.0" encoding='UTF-8'?>
<Invoice xmlns="urn:eslog:2.00">...</Invoice>

Odgovor je samostojen dokument text/html, pripravljen za tiskanje na A4. Namenjen je prikazu v ločenem oknu ali v okviru iframe; ne vstavljajte ga v obstoječo stran, saj prinese svoje oblikovanje. Dokument, ki ni e-SLOG 2.0 račun, vrne HTTP 400.