← Back to all articles

UBL vs CII: którą składnię XML faktury wybrać?

SealDoc Team · · 5 min read

Dwie składnie XML mogą reprezentować zgodną z EN16931 fakturę elektroniczną: UBL 2.1 i UN/CEFACT Cross Industry Invoice (CII). Oba są poprawne. Oba są akceptowane przez EN16931. I oba są strukturalnie na tyle różne, że kod napisany dla jednego nie może parsować drugiego bez osobnej implementacji.

Jeśli budujesz system fakturowania w Europie w 2026 roku, prawdopodobnie napotkasz oba. Oto, co musisz wiedzieć, żeby wybrać właściwy i obsługiwać drugi.

Co mają wspólnego

Zarówno UBL, jak i CII to serializacje tego samego modelu semantycznego: EN16931. Nazwa sprzedawcy to nazwa sprzedawcy. Kwota VAT to kwota VAT. Terminy biznesowe (BT) i grupy biznesowe (BG) są identyczne w obu składniach.

EN 16931-2 definiuje oficjalne mapowanie każdego BT na jego ścieżkę XML w obu składniach. Dokument jest bezpłatny z CEN/TC 434 i jest autorytatywnym odniesieniem, gdy potrzebujesz zaimplementować oba formaty.

Oba formaty są oparte na standardach międzynarodowych i są akceptowane przez walidatory EN16931. Oba produkują czytelne maszynowo ustrukturyzowane faktury.

Jak różnią się strukturalnie

Różnice są znaczące i wszechobecne. Nazwy elementów, prefiksy przestrzeni nazw, struktury zagnieżdżenia i konwencje atrybutów są wszystkie różne.

Nazwa sprzedawcy (BT-27)

UBL 2.1:

<cac:AccountingSupplierParty>
  <cac:Party>
    <cac:PartyName>
      <cbc:Name>Acme GmbH</cbc:Name>
    </cac:PartyName>
  </cac:Party>
</cac:AccountingSupplierParty>

CII:

<rsm:SupplyChainTradeTransaction>
  <ram:SellerTradeParty>
    <ram:Name>Acme GmbH</ram:Name>
  </ram:SellerTradeParty>
</rsm:SupplyChainTradeTransaction>

UBL używa głębokiego zagnieżdżenia z przestrzeniami nazw komponentów agregujących (cac:) i podstawowych (cbc:). CII jest płaszy, z przestrzeniami nazw ram: (Reusable Aggregate Module) i rsm: (Reusable Schema Module).

Kwota netto pozycji faktury (BT-131)

UBL 2.1:

<cac:InvoiceLine>
  <cbc:LineExtensionAmount currencyID="EUR">250.00</cbc:LineExtensionAmount>
</cac:InvoiceLine>

CII:

<ram:IncludedSupplyChainTradeLineItem>
  <ram:SpecifiedLineTradeSettlement>
    <ram:SpecifiedTradeSettlementLineMonetarySummation>
      <ram:LineTotalAmount>250.00</ram:LineTotalAmount>
    </ram:SpecifiedTradeSettlementLineMonetarySummation>
  </ram:SpecifiedLineTradeSettlement>
</ram:IncludedSupplyChainTradeLineItem>

Kody walut w CII są atrybutami elementów w niektórych miejscach i nieobecne w innych (waluta zadeklarowana na poziomie nagłówka). UBL jest bardziej spójny: currencyID pojawia się na każdym elemencie kwoty pieniężnej.

Element główny i przestrzenie nazw

UBL 2.1 używa trzech przestrzeni nazw:

<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">

CII używa trzech różnych przestrzeni nazw:

<rsm:CrossIndustryInvoice
  xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
  xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
  xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">

Między dwoma zestawami przestrzeni nazw nie ma żadnego pokrywania się. Parser celujący w jeden format nie może przetwarzać drugiego.

Który format jest wymagany gdzie

Wybór rzadko należy do Ciebie. Format jest determinowany przez docelowy kraj, kanał dostawy i ramy zgodności.

FormatWymagany przez
UBL 2.1Peppol BIS Billing 3.0 (transport sieciowy)
CIIFactur-X, ZUGFeRD, XRechnung (akceptuje zarówno CII, jak i UBL)
CII lub UBLFrancja (Portail Public de Facturation: oba akceptowane)

Peppol BIS Billing 3.0 to wyłącznie UBL. Jeśli transmitujesz przez sieć Peppol, musisz produkować UBL.

Factur-X i ZUGFeRD to CII. Załącznik factur-x.xml wewnątrz PDF/A-3 jest zawsze CII.

XRechnung akceptuje zarówno CII, jak i UBL, ale CII (CrossIndustryInvoice) jest częściej testowany przez walidatory portali rządowych Niemiec.

Konwersja między formatami

Nie istnieje bezstratna automatyczna konwersja między UBL i CII. Zawartość semantyczna jest identyczna, ale:

  • Niektóre pola mapują na atrybuty w jednym formacie i na elementy w drugim
  • Głębokość zagnieżdżenia różni się, co wpływa na sposób odczytu sekwencyjnych elementów takich jak pozycje faktury
  • Umieszczenie kodu waluty różni się między formatami (niektóre implementacje CII zakładają, że waluta nagłówka dotyczy wszystkich pozycji)
  • Formaty dat różnią się: UBL używa YYYY-MM-DD, CII używa YYYYMMDD z atrybutem format="102"

Konwersja jest możliwa, ale wymaga dedykowanej warstwy mapowania. Powszechne jest stosowanie XSLT; społeczność OpenPEPPOL udostępnia referencyjne mapowania.

Wydajność i narzędzia

UBL jest szerzej obsługiwany w bibliotekach .NET i Java. OASIS UBL funkcjonuje od 2006 roku i większość korporacyjnych narzędzi XML ma dla niego jawną obsługę.

CII jest mniej powszechny w europejskich narzędziach deweloperskich poza Francją i Niemcami. Biblioteki parserów istnieją, ale są bardziej wyspecjalizowane.

Saxon HE obsługuje walidację Schematron dla obu formatów. Wstępnie skompilowane pliki XSLT z wydań GitHub Peppol BIS zawierają osobne pliki XSLT:

peppol-en16931-ubl.xsl    (for UBL invoices)
peppol-en16931-cii.xsl    (for CII invoices)

Uruchamiaj każdy z nich na odpowiednim formacie wejściowym.

Który implementować jako pierwszy

Dla większości deweloperów zaczynających nową europejską integrację faktur w 2026 roku, UBL jest lepszym punktem startowym:

  • Transport przez sieć Peppol wymaga UBL
  • Większość krajów UE akceptuje UBL na portalkach krajowych
  • Narzędzia .NET i Java są bardziej dojrzałe
  • Specyfikacja UBL jest bardziej spójna pod względem umieszczania atrybutów

Jeśli działasz konkretnie we Francji lub Niemczech, CII staje się konieczne dla Factur-X i ZUGFeRD. To jest druga warstwa implementacyjna, a nie zamiennik.

Do celów archiwizacji PDF/A-3 z osadzonym CII jest standardem. Większość systemów, które transmitują Peppol UBL przez sieć, generuje również PDF Factur-X CII dla archiwum nabywcy. Oba pełnią różne funkcje i współistnieją.

Uwaga na temat walidacji

Niezależnie od używanej składni, waliduj względem reguł Schematron poprawnego profilu. Faktura, która jest prawidłowym UBL, może nie przejść reguł Peppol BIS 3.0, jeśli brakuje jej obowiązkowych elementów specyficznych dla Peppol. Faktura, która jest prawidłowym CII, może nie przejść profilu Factur-X EN 16931, jeśli brakuje pól opcjonalnych wymaganych przez ten profil.

Głębszy problem jest taki, że większość systemów potrzebuje obu formatów. Dostarczenie przez Peppol wymaga UBL. Archiwum nabywcy wymaga PDF Factur-X z osadzonym CII. Utrzymywanie dwóch niezależnych ścieżek generowania XML, dwóch przejść walidacyjnych i dwóch zestawów plików reguł Schematron podwaja powierzchnię dla błędów poprawności.

SealDoc generuje oba z tego samego wejścia. Jedno wywołanie API z danymi faktury daje dokument UBL do transmisji przez Peppol i PDF/A-3 z osadzonym CII dla archiwum nabywcy. Walidacja Schematron uruchamia się dla obu danych wyjściowych przed zwróceniem któregokolwiek. Nie potrzebujesz utrzymywać żadnej ścieżki generowania XML ani śledzić wydań Peppol BIS.

Do sprawdzania istniejących plików publiczny walidator SealDoc akceptuje zarówno UBL, jak i CII i raportuje błędy według numeru BT i kodu reguły biznesowej. Przydatne do diagnozowania dokumentów otrzymanych od partnerów handlowych lub do kalibrowania eksportu faktury strony trzeciej względem wymagań EN16931.

← Back to all articles