Czym jest plik ISDOC i jak go przetworzyć

ISDOC spotkacie w Czechach wszędzie tam, gdzie faktura trafia między dwie firmy korzystające z czeskiego oprogramowania księgowego. POHODA, Money S3, HELIOS, ABRA, Premier, FlexiBee, iDoklad — wszystkie go obsługują. Gdy dostaniecie załącznik .isdoc lub .isdocx, to strukturowana faktura, którą wasz system potrafi załadować bez ręcznego przepisywania. A gdy budujecie integrację fakturowania, prędzej czy później będziecie musieli ją czytać lub generować sami.

Ten artykuł wyjaśnia, czym jest ISDOC, skąd pochodzi, jak się ma do europejskiej normy i PEPPOL, i jak go przetworzyć w .NET tak, żeby nie padło na pierwszej fakturze, która trochę się różni.

Czym jest ISDOC

ISDOC to czeski krajowy standard strukturowanej faktury elektronicznej. Strukturowana oznacza, że to nie PDF ani skan — to XML, z którego oprogramowanie odczyta kwoty, pozycje, numer NIP, datę płatności i wszystko inne jako dane, nie jako tekst do przepisywania.

Istnieje w dwóch postaciach:

• .isdoc — jeden plik XML, jedna faktura.
• .isdocx — paczka ZIP, która zawiera ten sam XML plus załączniki. Zazwyczaj wizualne PDF faktury, żeby człowiek mógł ją przejrzeć, ale mogą to być też inne dokumenty.

Format jest zdefiniowany przez publicznie opublikowane schema XSD. To ważne: macie dokładny kontrakt, według którego sprawdzicie, czy faktura jest prawidłowa, zanim zacznniecie ją przetwarzać.

Skąd pochodzi ISDOC (i gdzie w tym Stormware)

Tu często słyszę skrót myślowy „ISDOC zrobił Stormware". To nie do końca prawda.

ISDOC powstał w grupie roboczej konsorcjum SPIS — które dziś nosi nazwę ICT Unie. Powstał jako czeska lokalizacja międzynarodowego standardu OASIS UBL 2.0 i po raz pierwszy został opublikowany w latach 2008–2009. Był to projekt wielu dostawców, nie produkt jednej firmy.

Stormware z programem POHODA był jednym z pierwszych i największych implementatorów i aktywnie promował ten format. Dlatego ISDOC się z nim kojarzy. Ale autorem standardu jest konsorcjum, nie jeden vendor. Dla praktyki oznacza to jedną przydatną rzecz: ISDOC nie jest formatem własnościowym zamkniętym w jednym oprogramowaniu. To otwarty standard, który obsługuje cała gama programów księgowych, i możecie się do niego podłączyć niezależnie od tego, kto wystawił fakturę.

Jak ISDOC ma się do PEPPOL i europejskiej normy

Tu jest właśnie to, co często się ze sobą myli. ISDOC, PEPPOL i EN 16931 to trzy różne rzeczy.

• ISDOC to czeska customizacja UBL 2.0. Konceptualnie XML jest bliskie UBL, ale nie jest identyczne z PEPPOL BIS 3.0 ani z UBL 2.1 używanymi dla normy europejskiej.
• EN 16931 to europejski model semantyczny faktury. PEPPOL BIS (zbudowany na UBL 2.1) to jego rozszerzona składnia do wymiany transgranicznej w UE.

Ciekawostka: ISDOC jest w wielu polach bogatszy niż model semantyczny EN 16931. Gdy konwertujecie ISDOC do UBL zgodnie z EN 16931, możecie część informacji utracić. Istnieje do tego open-source konwerter isdoc2ubl (na GitHubie), ale liczcie się z tym, że mapowanie jest stratne — nie każde pole ma odpowiednik w formacie docelowym.

W praktyce ISDOC i PEPPOL w Czechach koegzystują, jeden nie zastępuje drugiego:

• Krajowe B2B między dwiema firmami korzystającymi z czeskiego oprogramowania księgowego pozostaje na ISDOC.
• Zamówienia publiczne powyżej progów UE (B2G, platforma NEN) i fakturowanie transgraniczne działa przez PEPPOL BIS (UBL 2.1) ze względu na interoperacyjność w UE.

Pod ViDA UE będzie wymagać formatu transgranicznego opartego na EN 16931. Oznacza to, że ISDOC pozostaje formatem krajowym, nie standardem transgranicznym. Jeśli fakturujecie tylko w Czechach, ISDOC wam wystarczy. Gdy tylko rozwiązujecie zamówienia dla państwa lub handel transgraniczny, napotykacie PEPPOL i będziecie potrzebować mapowania między oboma.

Jak otworzyć ISDOC

Gdy plik .isdoc lub .isdocx po prostu przychodzi mailem, najprostsza droga to zaimportować go do oprogramowania księgowego, które znacie — POHODA, Money, HELIOS, iDoklad i inne załadują go bezpośrednio i faktura wypełni się sama. Istnieje też samodzielna przeglądarka ISDOCReader, która wyświetli plik jak klasyczną fakturę.

To jednak perspektywa użytkownika końcowego. Gdy budujecie integrację, otwarcie ISDOC oznacza sparsowanie go w kodzie. Warto tu zrobić to porządnie.

Jak przetworzyć ISDOC w .NET

ISDOC to zwykły XML względem opublikowanego XSD. Kuszącym skrótem jest ręczne parsowanie przez XDocument i wyciąganie wartości po nazwach elementów. Działa to do pierwszej faktury, która ma pole, o którym nie pomyśleliście. Niezawodna droga wiedzie przez schema.

1. Wygenerujcie klasy C# z oficjalnego XSD

Zamiast ręcznego czytania elementów, wygenerujcie klasy bezpośrednio z XSD ISDOC. Narzędzia: dotnet-xscgen, LinqToXsd albo legacy xsd.exe. Dostaniecie typowane klasy, które dokładnie odpowiadają schematowi. Zero literówek w nazwach elementów, zero zgadywania typów.

2. Czytajcie i zapisujcie przez serializację

Na wygenerowane klasy nałóżcie XmlSerializer (System.Xml.Serialization) do czytania i zapisu, albo XDocument (System.Xml.Linq) gdy potrzebujecie większej kontroli. Dzięki temu dostaniecie fakturę jako typowany obiekt, z którym w C# pracuje się normalnie, nie jak z drzewem stringów.

3. Walidujcie względem XSD

Przed przetworzeniem sprawdźcie, że plik jest prawidłowym ISDOC. Użyjcie XmlReaderSettings z XmlSchemaSet załadowanym z XSD ISDOC. Dzięki temu wyłapujecie uszkodzone lub niestandardowe faktury już na wejściu, nie trzy warstwy niżej, gdzie błąd objawia się jako tajemniczy null.

4. Przy .isdocx najpierw rozpakujcie

.isdocx to ZIP. Otwórzcie go przez System.IO.Compression.ZipArchive, wyciągnijcie wewnętrzny XML i dopiero to parsujcie. Załączniki (PDF i inne) pobierzcie z paczki osobno, jeśli potrzebujecie je archiwizować lub wyświetlić.

5. Do interoperacyjności mapujcie na EN 16931

Gdy potrzebujecie z ISDOC zrobić UBL lub CII zgodnie z EN 16931 — na potrzeby zamówienia publicznego lub wymiany transgranicznej — użyjcie XSLT z isdoc2ubl albo napiszcie własne mapowanie. I liczcie się z tym, o czym pisałem wyżej: mapowanie jest stratne. Sprawdźcie, że pola, na których wam zależy, mają odpowiednik w formacie docelowym.

Podsumowując: generowana serializacja plus walidacja względem schematu bije ręcznie pisany parser za każdym razem. Mniej kodu, mniej cichych błędów, a gdy schema zostanie rozszerzone, regenerujecie klasy zamiast polować po XDocument.

Gdzie pomożemy

E-faktury i faktury strukturowane budujemy na produkcji. Dla fakturowania podłączonego do polskiego KSeF dostarczyliśmy ponad 40 000 dokumentów ze 100% skutecznością i przy forensycznej odbudowie odtworzyliśmy 15 141 faktur, które poprzedni pipeline po cichu utracił. ISDOC, PEPPOL i EN 16931 to część tej samej domeny — strukturowana faktura, walidacja względem schematu, niezawodne przetwarzanie.

Jeśli rozwiązujecie czytanie lub generowanie ISDOC, mapowanie na PEPPOL dla zamówień publicznych, albo szykujecie się na ViDA, napiszcie do nas. Powiemy wam, gdzie to jest proste, a gdzie gubi się w szczegółach.

FAQ

Czym jest plik ISDOC?

ISDOC to czeski krajowy standard strukturowanej faktury elektronicznej. To plik XML zgodny z publicznie opublikowanym schematem XSD. Rozszerzenie .isdoc to jedna faktura, .isdocx to paczka ZIP z XML i załącznikami, zazwyczaj PDF.

Skąd pochodzi ISDOC i czy ma coś wspólnego ze Stormware?

ISDOC powstał w ramach konsorcjum SPIS (dziś ICT Unie) jako czeska lokalizacja standardu OASIS UBL 2.0, po raz pierwszy opublikowany w latach 2008–2009. Stormware z programem POHODA był wczesnym i dużym implementatorem, nie jedynym autorem formatu. Był to projekt wielu uczestników.

Jak sparsować ISDOC w .NET?

Wygeneruj klasy C# z oficjalnego XSD ISDOC za pomocą dotnet-xscgen lub LinqToXsd i czytaj przez XmlSerializer lub XDocument. Waliduj względem XSD przez XmlReaderSettings i XmlSchemaSet. Plik .isdocx najpierw rozpakuj przez ZipArchive, a następnie parsuj wewnętrzny XML.