Szukaj w sieci
Faktura Peppol BIS Billing 3.0 jest dokumentem XML. To właśnie XML jest fakturą: zawiera ustrukturyzowane dane, które oprogramowanie księgowe może zweryfikować, zaksięgować i przetworzyć automatycznie. Czasami faktura potrzebuje również materiałów pomocniczych, takich jak ewidencja godzin, dokument dostawy albo czytelny dla człowieka plik PDF. BIS 3.0 pozwala wysłać taki materiał razem z fakturą jako załącznik XML.
PDF może ułatwić człowiekowi odczytanie faktury, ale nie zastępuje ustrukturyzowanej faktury BIS. XML pozostaje dokumentem, którego systemy powinny używać do walidacji i automatycznego przetwarzania.
Gdzie umieścić załącznik w BIS 3?
Załączniki są przekazywane w cac:AdditionalDocumentReference/cac:Attachment. Ta grupa jest opcjonalna i może wystąpić wiele razy. Pełną strukturę opisuje oficjalna składnia UBL Invoice w Peppol BIS Billing 3.0.
W przypadku osadzonego pliku najważniejszy jest element cbc:EmbeddedDocumentBinaryObject. Ma on dwa obowiązkowe atrybuty:
mimeCode, który określa typ pliku;filename, który określa nazwę pliku dla odbiorcy.
Minimalny osadzony PDF może wyglądać tak:
| |
Wartością elementu nie jest sam plik PDF, lecz jego zawartość przedstawiona w Base64.
Jakie formaty są obsługiwane?
BIS Billing 3 nie pozwala na dowolny typ MIME. Odbiorca musi obsługiwać ograniczoną listę opartą na IANA. Oficjalna lista typów mediów załączonych dokumentów obejmuje:
| Kategoria | Typ MIME |
|---|---|
| Dokument | application/pdf |
| Obraz | image/png |
| Obraz | image/jpeg |
| Tekst | text/csv |
| Arkusz kalkulacyjny | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| Arkusz kalkulacyjny | application/vnd.oasis.opendocument.spreadsheet |
mimeCode musi być jedną z tych wartości, a rozszerzenie pliku powinno się z nim zgadzać. Nie należy oznaczać pliku ZIP jako PDF ani wysyłać pliku Excel z mimeCode="application/pdf".
BIS obsługuje również zewnętrzne odwołanie przez cac:ExternalReference/cbc:URI. Osadzony załącznik jest zwykle bardziej niezawodny w przypadku dokumentów pomocniczych: podróżuje razem z fakturą i nie zależy od późniejszej dostępności adresu URL, logowania ani terminu ważności linku.
10 MiB a 100 MiB
Te dwie wartości są często mylone:
- 10 MiB to najczęściej sprawdzany limit całej wiadomości XML. Nie jest to limit jednego załącznika. Kontrola zwykle obejmuje fakturę XML wraz ze wszystkimi osadzonymi załącznikami i treścią wiadomości odbieraną przez Access Point. Kilka małych załączników może więc wspólnie przekroczyć limit.
- 100 MiB to ogólna zdolność transportu. Wiadomość powinna zasadniczo działać do 100 MiB, ale konkretny limit zależy od polityki danego Access Pointu. Niektóre Access Pointy mogą odrzucić ją znacznie wcześniej.
Base64 zwiększa każdy osadzony obiekt binarny mniej więcej o jedną trzecią. Do tego dochodzą XML, opakowanie MIME i narzut bezpieczeństwa. Liczy się więc nie rozmiar plików na dysku, lecz rozmiar gotowej wiadomości. Implementacja powinna mierzyć kompletną zakodowaną wiadomość i zostawić zapas poniżej limitu egzekwowanego przez Access Point.
W przypadku większych materiałów użyj mniejszego, istotnego eksportu albo zewnętrznego odwołania uzgodnionego z odbiorcą. Faktura nie powinna stawać się ogólnym archiwum plików. Przed wysłaniem dużej wiadomości warto potwierdzić efektywny limit u odbiorcy.
Jak kodowany jest plik?
Bajty pliku są kodowane jako Base64 i umieszczane w cbc:EmbeddedDocumentBinaryObject. Base64 nie jest szyfrowaniem ani kontrolą bezpieczeństwa. Odbiorca dekoduje wartość z powrotem do bajtów, a Access Point i aplikacja docelowa nadal muszą stosować standardowe skanowanie pod kątem złośliwej zawartości.
Podczas tworzenia załącznika:
- odczytaj oryginalne bajty bez konwersji do kodowania tekstowego;
- zakoduj je w Base64;
- ustaw prawidłowe
mimeCodeifilename; - w teście zdekoduj wartość i porównaj ją z oryginałem bajt po bajcie;
- zwaliduj całą fakturę BIS oraz rozmiar gotowej wiadomości.
Dlaczego w ogóle wysyłać załącznik?
Ustrukturyzowany XML świetnie nadaje się do automatyzacji, ale nie zawiera każdego dowodu potrzebnego w procesie biznesowym. Załącznikiem może być ewidencja godzin, protokół dostawy lub odbioru, kalkulacja, zdjęcie, arkusz kalkulacyjny albo reprezentacja PDF dla człowieka.
Wysłanie dokumentu w tej samej wiadomości poprawia identyfikowalność. Odbiorca nie musi dopasowywać załącznika z e-maila ani pobierać linku, który później wygaśnie. Załącznik ma jednak wspierać fakturę, a nie jej zaprzeczać. Kwoty, dane podatkowe i identyfikacja stron muszą pochodzić ze strukturyzowanych danych BIS.
Dlaczego Access Point może dodać PDF?
Niektóre Access Pointy generują z faktury XML reprezentację PDF i dodają ją jako załącznik w formie podglądu faktury. Może to być przydatne przy ręcznej kontroli, drukowaniu lub archiwizacji, gdy obok maszynowo czytelnego XML potrzebny jest widok wizualny.
PDF jest pomocniczą reprezentacją, a nie drugą autorytatywną fakturą. Powinien być wygenerowany z poprawnego XML, mieć jasną nazwę i mimeCode="application/pdf". Nie może po cichu zmieniać kwot, VAT, referencji płatności ani stron transakcji. Do księgowania odbiorca powinien używać XML, a PDF traktować jako widok lub materiał pomocniczy.
Warto też jasno wskazać, czy PDF dostarczył nadawca, czy wygenerował go Access Point. Wygenerowany PDF zwiększa rozmiar wiadomości i może być dla odbiorcy niespodziewany.
Praktyczna checklista
Przed wysłaniem sprawdź, czy:
- faktura XML jest poprawna zgodnie z Peppol BIS Billing 3.0;
- każdy załącznik ma dozwolony typ MIME i sensowną nazwę;
- zawartość jest zakodowana w Base64 i można ją odtworzyć bez zmian;
- cała wiadomość mieści się w limicie sprawdzanym przez Access Point;
- wiadomo, czy Access Point generuje PDF i jak go obsługuje.
Dzięki temu XML pozostaje precyzyjny i możliwy do automatyzacji, a dokumenty pomocnicze podróżują razem z transakcją.
Źródła: Peppol BIS Billing 3.0, składnia UBL Invoice, lista typów mediów załączników oraz Peppol AS4 Profile.
