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.

Viimati kontrollitud:

Mis vahe on UBL-il, EN 16931-l ja Peppol BIS 3.0-l?

UBL 2.1 on XML-süntaks, EN 16931 on sisu määrav semantiline standard ning BIS Billing 3.0 on EN 16931-le vastav profiil UBL-is koos Peppol’i võrgureeglitega, mis deklareeritakse elementidega CustomizationID/ProfileID.

Miks mu UBL-arve ei läbi valideerimist, kuigi XML on korrektselt vormistatud?

Korrektselt vormistatud XML läbib XSD kontrolli, kuid võib siiski rikkuda Schematroni ärireegleid – EN 16931 reeglid (koodid algusega BR-) või Peppol’i reeglid (koodid algusega PEPPOL-) –, mis enamasti tähendab kogusummade aritmeetilist lahknevust või puuduvaid skeemiga kvalifitseeritud tunnuseid.

Kas UBL XML-i asemel võib saata JSON-i?

Mõned ligipääsupunkti API-d võtavad vastu struktureeritud JSON-i ja genereerivad UBL-i sinu eest; tugi erineb teenusepakkujate lõikes. Võrgus endas liigub dokument siiski UBL XML-ina.

Kas peaksin UBL-i genereerimise ise üles ehitama?

Kui e-arveldus on sinu toote tuum, on mõistlik XML ja reeglite uuendamine enda kätte võtta. Kui see on vaid üks funktsioon, võtab ligipääsupunkti API, mis UBL-i genereerib ja valideerib, selle hoolduskoormuse sinult ära.