UBL 2.1 e-račun: primjer XML s objašnjenjima

Što je UBL 2.1?

UBL (Universal Business Language) je otvoreni XML standard za razmjenu poslovnih dokumenata koji je razvila organizacija OASIS. Verzija 2.1, objavljena 2013. godine, podržava više od 60 tipova poslovnih dokumenata, od kojih je najvažniji Invoice (račun).

U kontekstu europskog e-fakturiranja, UBL 2.1 je jedan od dva prihvaćena sintaksna formata prema europskom standardu EN 16931. Drugi prihvaćeni format je UN/CEFACT CII (Cross-Industry Invoice). Većina europskih zemalja, uključujući Hrvatsku, u praksi koristi UBL 2.1 kao primarni format.

Odnos UBL-a i EN 16931

Važno je razumjeti razliku između ova dva pojma:

• EN 16931 je semantički standard. Definira koji podaci moraju biti na e-računu (prodavatelj, kupac, stavke, PDV, ukupni iznos) i koja su poslovna pravila (npr. ukupni iznos mora biti zbroj stavki).
• UBL 2.1 je sintaksna specifikacija. Definira kako se ti podaci zapisuju u XML formatu (nazivi elemenata, struktura, namespace).

Drugim riječima, EN 16931 kaže "račun mora sadržavati datum izdavanja", a UBL 2.1 kaže da se taj datum zapisuje u XML element <cbc:IssueDate>.

Struktura UBL 2.1 računa

UBL 2.1 Invoice dokument ima sljedeću visoku strukturu:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <!-- 1. Zaglavlje: broj računa, datum, valuta -->
  <!-- 2. Prodavatelj (AccountingSupplierParty) -->
  <!-- 3. Kupac (AccountingCustomerParty) -->
  <!-- 4. Uvjeti plaćanja (PaymentMeans, PaymentTerms) -->
  <!-- 5. PDV rekapitulacija (TaxTotal) -->
  <!-- 6. Ukupni iznosi (LegalMonetaryTotal) -->
  <!-- 7. Stavke računa (InvoiceLine) -->
</Invoice>

Svaki od ovih blokova sadrži ugniježđene elemente koji opisuju pojedine podatke. U nastavku slijedi kompletni primjer s objašnjenjima.

Kompletni primjer: UBL 2.1 hrvatski račun

Ovo je potpuni primjer UBL 2.1 XML računa za hrvatskog prodavatelja koji izdaje račun hrvatskom kupcu. Račun sadrži dvije stavke, PDV po stopi od 25% i podatke o plaćanju.

Zaglavlje i namespace deklaracije

<?xml version="1.0" encoding="UTF-8"?>
<Invoice
  xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
  xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
  xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:CustomizationID>
    urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0
  </cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>

  <cbc:ID>R-2026-0042</cbc:ID>
  <cbc:IssueDate>2026-03-11</cbc:IssueDate>
  <cbc:DueDate>2026-04-10</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
</Invoice>

Objašnjenje zaglavlja:

• xmlns atributi definiraju XML namespace za UBL 2.1 elemente. Prefiks cbc koristi se za jednostavne podatke (tekst, brojevi, datumi), a cac za složene strukture (adrese, stranke).
• CustomizationID označava da račun prati EN 16931 standard s PEPPOL BIS 3.0 prilagodbom.
• ProfileID označava poslovni proces (u ovom slučaju PEPPOL Billing).
• ID je jedinstveni broj računa.
• IssueDate je datum izdavanja u ISO 8601 formatu (YYYY-MM-DD).
• DueDate je datum dospijeća plaćanja.
• InvoiceTypeCode 380 označava standardni komercijalni račun. Druge vrijednosti: 381 (odobrenje), 384 (ispravljeni račun), 389 (samoobračun).
• DocumentCurrencyCode je valuta računa prema ISO 4217 (EUR za Hrvatsku).

Podaci o prodavatelju

  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:EndpointID schemeID="9934">12345678901</cbc:EndpointID>
      <cac:PartyIdentification>
        <cbc:ID schemeID="9934">12345678901</cbc:ID>
      </cac:PartyIdentification>
      <cac:PartyName>
        <cbc:Name>TehnoSoft d.o.o.</cbc:Name>
      </cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Ilica 100</cbc:StreetName>
        <cbc:CityName>Zagreb</cbc:CityName>
        <cbc:PostalZone>10000</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode>HR</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
      <cac:PartyTaxScheme>
        <cbc:CompanyID>HR12345678901</cbc:CompanyID>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:PartyTaxScheme>
      <cac:PartyLegalEntity>
        <cbc:RegistrationName>TehnoSoft d.o.o.</cbc:RegistrationName>
        <cbc:CompanyID schemeID="9934">12345678901</cbc:CompanyID>
      </cac:PartyLegalEntity>
      <cac:Contact>
        <cbc:ElectronicMail>racuni@tehnosoft.hr</cbc:ElectronicMail>
      </cac:Contact>
    </cac:Party>
  </cac:AccountingSupplierParty>

Objašnjenje podataka o prodavatelju:

• EndpointID s schemeID="9934" je PEPPOL identifikator sudionika. Za Hrvatsku se koristi shema 9934 (HR:OIB) s 11-znamenkastim OIB-om.
• PartyIdentification sadrži identifikator stranke (OIB prodavatelja: 12345678901).
• PartyName je trgovački naziv tvrtke.
• PostalAddress sadrži adresu s obveznim poljima: ulica, grad, poštanski broj i država (ISO 3166-1 kod HR).
• PartyTaxScheme sadrži PDV identifikacijski broj (HR + OIB) i oznaku porezne sheme (VAT).
• PartyLegalEntity sadrži službeni registracijski naziv i OIB.
• Contact je opcionalan, ali preporučen za komunikaciju o računu.

Podaci o kupcu

  <cac:AccountingCustomerParty>
    <cac:Party>
      <cbc:EndpointID schemeID="9934">98765432109</cbc:EndpointID>
      <cac:PartyIdentification>
        <cbc:ID schemeID="9934">98765432109</cbc:ID>
      </cac:PartyIdentification>
      <cac:PartyName>
        <cbc:Name>Gradska uprava Grada Zagreba</cbc:Name>
      </cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Trg Stjepana Radića 1</cbc:StreetName>
        <cbc:CityName>Zagreb</cbc:CityName>
        <cbc:PostalZone>10000</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode>HR</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
      <cac:PartyTaxScheme>
        <cbc:CompanyID>HR98765432109</cbc:CompanyID>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:PartyTaxScheme>
      <cac:PartyLegalEntity>
        <cbc:RegistrationName>Gradska uprava Grada Zagreba</cbc:RegistrationName>
        <cbc:CompanyID schemeID="9934">98765432109</cbc:CompanyID>
      </cac:PartyLegalEntity>
    </cac:Party>
  </cac:AccountingCustomerParty>

Objašnjenje podataka o kupcu:

Struktura kupca je identična strukturi prodavatelja. U ovom primjeru kupac je javni naručitelj (gradska uprava), što znači da se račun šalje putem FINA e-Račun servisa. OIB kupca (98765432109) koristi se i kao PEPPOL identifikator i kao porezni broj.

Uvjeti plaćanja

  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
    <cac:PayeeFinancialAccount>
      <cbc:ID>HR1234567890123456789</cbc:ID>
      <cbc:Name>TehnoSoft d.o.o.</cbc:Name>
      <cac:FinancialInstitutionBranch>
        <cbc:ID>PBZGHR2X</cbc:ID>
      </cac:FinancialInstitutionBranch>
    </cac:PayeeFinancialAccount>
  </cac:PaymentMeans>

  <cac:PaymentTerms>
    <cbc:Note>Rok plaćanja: 30 dana od datuma izdavanja računa.</cbc:Note>
  </cac:PaymentTerms>

Objašnjenje uvjeta plaćanja:

• PaymentMeansCode 30 označava bankovni prijenos (virman). Druge česte vrijednosti: 48 (kartica), 49 (direktno terećenje), 58 (SEPA prijenos).
• PayeeFinancialAccount/ID je IBAN prodavatelja na koji kupac uplaćuje iznos.
• FinancialInstitutionBranch/ID je BIC/SWIFT kod banke (u ovom primjeru PBZ).
• PaymentTerms/Note je tekstualni opis uvjeta plaćanja. Element je opcionalan, ali koristan jer se prikazuje na vizualnom prikazu računa.

PDV rekapitulacija

  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="EUR">330.00</cbc:TaxAmount>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">1320.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">330.00</cbc:TaxAmount>
      <cac:TaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>25.00</cbc:Percent>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:TaxCategory>
    </cac:TaxSubtotal>
  </cac:TaxTotal>

Objašnjenje PDV rekapitulacije:

• TaxTotal/TaxAmount je ukupni iznos PDV-a na računu (330,00 EUR).
• TaxSubtotal grupira stavke po PDV stopi. Ako račun ima stavke s različitim stopama (npr. 25% i 13%), svaka stopa ima vlastiti TaxSubtotal blok.
• TaxableAmount je osnovica za tu stopu (1.320,00 EUR).
• TaxCategory/ID označava vrstu PDV-a. Kod "S" znači standardna stopa (Standard rate). Drugi kodovi: "Z" (nulta stopa), "E" (oslobođeno), "AE" (reverse charge), "K" (intra-EU isporuka).
• Percent je postotna stopa PDV-a (25% za Hrvatsku).

Ukupni iznosi

  <cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="EUR">1320.00</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="EUR">1320.00</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="EUR">1650.00</cbc:TaxInclusiveAmount>
    <cbc:PayableAmount currencyID="EUR">1650.00</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>

Objašnjenje ukupnih iznosa:

• LineExtensionAmount je zbroj neto iznosa svih stavki (bez PDV-a): 1.320,00 EUR.
• TaxExclusiveAmount je ukupni iznos bez PDV-a (može se razlikovati od LineExtensionAmount ako postoje popusti ili naknade na razini dokumenta).
• TaxInclusiveAmount je ukupni iznos s PDV-om: 1.320,00 + 330,00 = 1.650,00 EUR.
• PayableAmount je iznos koji kupac mora platiti. Ako je već uplaćen predujam, ovaj iznos bit će manji od TaxInclusiveAmount.

Stavke računa

  <cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="HUR">40</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
    <cac:Item>
      <cbc:Description>Razvoj web aplikacije za upravljanje dokumentima</cbc:Description>
      <cbc:Name>Web development</cbc:Name>
      <cac:ClassifiedTaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>25.00</cbc:Percent>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:ClassifiedTaxCategory>
    </cac:Item>
    <cac:Price>
      <cbc:PriceAmount currencyID="EUR">25.00</cbc:PriceAmount>
    </cac:Price>
  </cac:InvoiceLine>

  <cac:InvoiceLine>
    <cbc:ID>2</cbc:ID>
    <cbc:InvoicedQuantity unitCode="MON">2</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">320.00</cbc:LineExtensionAmount>
    <cac:Item>
      <cbc:Description>Mjesečno održavanje servera i sigurnosne zakrpe</cbc:Description>
      <cbc:Name>Održavanje servera</cbc:Name>
      <cac:ClassifiedTaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>25.00</cbc:Percent>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:ClassifiedTaxCategory>
    </cac:Item>
    <cac:Price>
      <cbc:PriceAmount currencyID="EUR">160.00</cbc:PriceAmount>
    </cac:Price>
  </cac:InvoiceLine>

Objašnjenje stavki računa:

Svaka InvoiceLine predstavlja jednu stavku na računu:

• ID je redni broj stavke (1, 2, 3...).
• InvoicedQuantity je količina s obveznim unitCode atributom prema UN/ECE Recommendation 20. Česti kodovi: "HUR" (sati), "MON" (mjeseci), "EA" (komad), "KGM" (kilogram), "MTR" (metar).
• LineExtensionAmount je neto iznos stavke (količina x cijena): 40 sati x 25,00 EUR = 1.000,00 EUR.
• Item/Description je detaljan opis stavke, a Item/Name je kratki naziv.
• ClassifiedTaxCategory označava PDV kategoriju i stopu za tu stavku.
• Price/PriceAmount je jedinična cijena bez PDV-a.

U ovom primjeru račun ima dvije stavke: 40 sati razvoja po 25 EUR/sat (1.000,00 EUR) i 2 mjeseca održavanja servera po 160 EUR/mjesec (320,00 EUR). Ukupna osnovica je 1.320,00 EUR.

Obvezna i opcionalna polja prema EN 16931

EN 16931 standard definira koja polja moraju biti na svakom e-računu, a koja su opcionalna. Ova tablica pokriva najvažnije elemente.

Validacija UBL 2.1 računa

Validacija e-računa odvija se u tri koraka, od kojih su prva dva obavezna.

1. XSD validacija (strukturna provjera)

XSD (XML Schema Definition) provjerava je li XML dokument strukturno ispravan: jesu li svi elementi pravilno ugniježđeni, jesu li tipovi podataka ispravni (datum, broj, tekst) i jesu li namespace deklaracije točne.

Alati za XSD validaciju:

• xmllint (besplatan, CLI): xmllint --schema UBL-Invoice-2.1.xsd racun.xml
• Oxygen XML Editor: profesionalni XML editor s ugrađenom validacijom
• Online validatori: PEPPOL validator (https://peppol.helger.com/public/locale-en_US/menuitem-validation-upload)

2. Schematron validacija (poslovna pravila)

Schematron pravila provjeravaju logičku ispravnost računa prema EN 16931 i PEPPOL pravilima. Na primjer:

• Ukupni iznos mora biti jednak zbroju stavki
• PDV mora biti ispravno izračunan prema stopi
• Ako je InvoiceTypeCode 380, PayableAmount mora biti pozitivan
• Država prodavatelja mora odgovarati prefiksu poreznog broja

3. CIUS provjera (nacionalna pravila)

Hrvatski CIUS profil dodaje dodatna pravila specifična za hrvatski porezni sustav:

• OIB mora imati 11 znamenki i prolaziti kontrolnu provjeru
• Za hrvatske prodavatelje, CompanyID mora početi s "HR"
• PDV stope moraju odgovarati važećim hrvatskim stopama (25%, 13%, 5%)

Česte greške pri validaciji

Primjer s različitim PDV stopama

U praksi račun može sadržavati stavke s različitim PDV stopama. U tom slučaju, TaxTotal blok ima više TaxSubtotal elemenata:

  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="EUR">292.90</cbc:TaxAmount>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">1000.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">250.00</cbc:TaxAmount>
      <cac:TaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>25.00</cbc:Percent>
        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
      </cac:TaxCategory>
    </cac:TaxSubtotal>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">330.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">42.90</cbc:TaxAmount>
      <cac:TaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>13.00</cbc:Percent>
        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
      </cac:TaxCategory>
    </cac:TaxSubtotal>
  </cac:TaxTotal>

Ovdje račun ima stavke s 25% PDV-a (osnovica 1.000,00 EUR, PDV 250,00 EUR) i stavke s 13% PDV-a (osnovica 330,00 EUR, PDV 42,90 EUR). Ukupni PDV iznosi 292,90 EUR. Stopa od 13% primjenjuje se na ugostiteljske usluge, novine i neke prehrambene proizvode.

Česta pitanja

Povezani vodiči

• e-Račun (FINA) vs Fiskalizacija 2.0 - razlike između e-računa za javnu nabavu i fiskalizacije
• e-Arhiva - digitalna arhiva računa i dokumenata, obveza čuvanja 11 godina