Korrektse e-arve programmaatiliseks loomiseks toodad UBL 2.1 XML-dokumendi, mille sisu vastab Euroopa standardile EN 16931 profiiliga Peppol BIS Billing 3.0. Need kolm nime ajavad igaüht korra segadusse: UBL on XML-sõnavara (elementide nimed ja struktuur), EN 16931 on semantiline standard (millised äriandmed arvel olema peavad) ja BIS 3.0 on EN 16931 kitsendatud rakendus UBL-is koos Peppol’i võrgureeglitega. BIS-arve deklareerib oma olemuse kahe elemendiga (`CustomizationID` (profiil) ja `ProfileID` (protsess)) ning valideerijad võtavad neid lepinguna, millised reeglid kehtivad.
Mida arve sisaldama peab?
EN 16931 määrab semantilise tuuma: müüja ja ostja identifitseerimine, arve number ja kuupäev, valuuta, arveread koguste ja netosummadega, käibemaksu jaotus määrade kaupa ning dokumendi kogusummad. Kaks omadust põhjustavad enamiku päris vigadest. Summad peavad aritmeetiliselt klappima – ridade summad, allahindlused, käibemaksukategooriate summad ja tasumisele kuuluv summa on ristkontrollitud, nii et sinu andmebaasi ja XML-i ümardamiserinevus kukutab valideerimise läbi. Ja tunnused on skeemiga kvalifitseeritud: müüja registrikood või ostja elektrooniline aadress kannab ISO 6523 skeemi (Eesti äriregistri kood näiteks skeemiga 0191).
Kuidas valideerimine käib?
Kahes kihis, ja see jaotus on silumisel oluline. XSD kontrollib struktuuri – elemendid, järjekord, andmetüübid; siin kukkumine tähendab vigast XML-i. Schematron kontrollib ärireegleid – EN 16931 reeglid (koodid algusega `BR-`) ja Peppol’i lisareeglid (koodid algusega `PEPPOL-`); siin kukkumine tähendab sisuprobleemi korrektses XML-is. Head ligipääsupunkti API-d jooksutavad mõlemad sünkroonselt enne dokumendi vastuvõtmist, mis muudab vastavusvea tavaliseks API-veaks, mille sinu testid kinni püüavad. Veaklassid võtame lahti juhendis Peppol’i valideerimisvead selgitatult.
Kas ehitada XML ise või lasta API-l genereerida?
Mõlemad on õiged; kaalul on kontroll versus hooldus. UBL-i ise ehitades (küpseid teeke leidub enamikus keeltes) saad täiskontrolli ja võrguühenduseta genereerimise, aga reeglistiku uuendused jäävad sinu kanda. Schematroni reeglid arenevad võrgu väljalasketsükliga. Struktureeritud JSON-i saatmine ligipääsupunkti API-sse, mis UBL-i ise genereerib ja valideerib, võtab selle hoolduse sinult ära ja tuleb tavaliselt koos liivakastiga, hinnaks käitusaegne sõltuvus. Mõistlik vaikevalik: kui e-arveldus on sinu toote tuum, oma XML-i ise; kui see on üks funktsioon, lase API-l teha ja kuluta säästetud nädalad mujale.
What is the difference between UBL, EN 16931 and Peppol BIS 3.0?
UBL 2.1 is the XML syntax, EN 16931 the semantic content standard, and BIS Billing 3.0 a conformant EN 16931 profile in UBL plus Peppol network rules, declared via CustomizationID/ProfileID.
Why does my UBL invoice fail validation even though the XML is well-formed?
Well-formed XML passes XSD but can still break Schematron business rules — BR-* (EN 16931) or PEPPOL-* codes — typically arithmetic disagreements in totals or missing scheme-qualified identifiers.
Can I send JSON instead of UBL XML?
Some Access Point APIs accept structured JSON and generate the UBL for you; support varies by provider. On the network itself the document travels as UBL XML.
Should I build UBL generation myself?
If e-invoicing is your core product, owning the XML and rule updates makes sense. If it is one feature, an Access Point API that generates and validates UBL removes the maintenance burden.