API użytkownika udostępniane przez dostawcę i AS4 między Access Pointami to różne interfejsy. Należy przetestować odbiór, wysyłkę, duplikaty i błędy; sukces HTTP sam nie potwierdza doręczenia.
Jak oprogramowanie łączy się z Peppol przez API?
Typowa integracja łączy Państwa system do fakturowania lub ERP z interfejsem dostawcy doręczeń. Program przygotowuje dane, przekazuje dokument i przejmuje wyniki lub otrzymane faktury. Dostawca realizuje swoje zadanie w sieci doręczeń.
API dla klientów i przesył między Access Pointami to odrębne warstwy. Peppol AS4 opisuje komunikację między dostawcami. Konkretne adresy API, sposób uwierzytelniania i format odpowiedzi dla Państwa programu określa dokumentacja wybranego dostawcy.
Zanim rozpoczną się prace programistyczne, warto potwierdzić zakres: tylko wysyłka, tylko odbiór czy oba kierunki. Należy uwzględnić także kilka firm, dokumenty korygujące, załączniki i wymagane połączenie z księgowością.
Jak podzielić zadania między ERP a dostawcę?
| Zadanie | Co uzgodnić |
|---|---|
| Powstanie faktury | Gdzie jest źródło danych i kto zatwierdza dokument |
| Eksport UBL | Kto tworzy XML i jaki profil lub wydanie obsługuje |
| Adresowanie | Skąd pobierany jest Peppol ID i jak weryfikowany jest odbiorca |
| Walidacja | Które warstwy są wykonywane i jak zwracane są błędy |
| Doręczenie | Jaką identyfikację wiadomości i jaki wynik otrzymuje ERP |
| Odbiór | Jak pobierane są oryginalne XML, załączniki i czas odbioru |
| Przekazywanie danych | Jak śledzony jest wynik przekazania danych do FS SR |
Dostawca może przyjmować gotowy XML albo oferować jego utworzenie z innych danych. W obu przypadkach należy sprawdzić, czy znaczenie handlowe pól zostaje zachowane. Mapowanie wyjaśnia wzór XML z komentarzami.
Jak zaprojektować wysyłkę i powrót wyniku?
Dokument należy najpierw zapisać i sprawdzić technicznie. Przy przekazaniu trzeba zapisać własne odwołanie i identyfikację wiadomości nadaną przez dostawcę. Odpowiedź API powinna mieć wyjaśnione znaczenie: przyjęcie żądania może poprzedzać ostateczny wynik przesyłu.
Przy przetwarzaniu asynchronicznym wynik może przyjść przez webhook albo program może go sprawdzać przez ponowne zapytania zgodnie z dokumentacją. Nie należy traktować tych możliwości jako obowiązkowej funkcji każdego API. Warto uzgodnić, jak wynik wraca do właściwego dokumentu i co zobaczy pracownik w razie błędu.
Przykładowy przebieg integracji:
ERP przygotowuje i zapisuje fakturę
→ sprawdza XML i nadaje własne odwołanie
→ przekazuje dokument dostawcy
→ zapisuje identyfikację wiadomości
→ przejmuje wynik przesyłu
→ wyświetla status lub zadanie do poprawy
Schemat nie jest definicją konkretnego API. Nazwy statusów i dostępne potwierdzenia należy przejmować z dokumentacji usługi. Doręczenie techniczne trzeba odróżniać od handlowego zatwierdzenia przez nabywcę.
Co dzieje się przy awarii lub ponownym żądaniu?
Jeśli po wysłaniu wystąpi timeout, wynik może być nieznany: dostawca mógł przyjąć dokument. Ponowna wysyłka musi mieć uzgodnioną ochronę przed duplikatami. Należy sprawdzić, czy API obsługuje żądanie idempotentne lub odnalezienie wiadomości według Państwa odwołania.
Przy webhookach trzeba liczyć się z powtórzonym zdarzeniem i zgodnie z dokumentacją weryfikować jego pochodzenie. Przy odbiorze należy zapisać identyfikator wiadomości i tożsamość faktury; kontrola nie powinna opierać się wyłącznie na nazwie pliku. Techniczny duplikat przesyłu i dwa podobne handlowo dokumenty to różne sytuacje.
Warto przygotować również ręczne rozwiązanie przypadku, który pozostał bez jednoznacznego wyniku. Nie należy automatycznie oznaczać wyniku jako udanego tylko dlatego, że przestał przychodzić kod błędu.
Jak ustawić odbiór i dostępy kilku firm?
Pobrany XML należy zachować i porównać dane z importem do właściwej firmy. Późniejsze zatwierdzanie, przypisanie kont i płatność należą do Państwa procedury pracy. Oficjalna struktura UBL pomoże ustalić, gdzie należą dane handlowe.
Konta testowe i produkcyjne należy trzymać oddzielnie. Klucze trzeba przechowywać na serwerze i udostępniać je wyłącznie niezbędnym procesom. Przy kilku podmiotach należy sprawdzić zakres każdego uprawnienia, aby żądanie jednej firmy nie mogło przetworzyć dokumentów drugiej.
Należy określić również odzyskiwanie dostępu i wymianę danych przy zmianie usługi. Dziennik operacyjny powinien pomóc odnaleźć problem bez zbędnego kopiowania całej treści faktur do każdego logu.
Co musi przejść test przed uruchomieniem?
Należy przetestować zwykłą wysyłkę i odbiór, nieprawidłowy dokument, nieznanego odbiorcę, korektę i ponowny import. Warto dodać timeout po przekazaniu, powtórzone zdarzenie i chwilową niedostępność usługi. Dla każdego scenariusza trzeba określić oczekiwany wynik i procedurę obsługi.
Należy zapisać użyte wydanie zasad i wersję konektora. Przy aktualizacji warto porównać je z obowiązującymi specyfikacjami eDelivery. Kontrolę dokumentu wyjaśnia walidacja e-faktury.
W przypadku pracy na Słowacji należy dodać także uzgodnienia dotyczące przekazywania danych. Administracja Finansowa Republiki Słowackiej (Finančná správa SR) opisuje automatyczny przesył za pośrednictwem Cyfrowego listonosza (Digitálny poštár); integracja powinna umożliwić użytkownikowi odnalezienie jego wyniku. Ogólny przebieg opisuje doręczanie faktur.
Organizację pracy i testy z dostawcą oprogramowania uzupełnia poradnik dotyczący podłączenia programu księgowego. Konwersję istniejących dokumentów omawia procedura PDF na eFaktúrę.
Sprawdzone źródła
Opieramy się na oficjalnych materiałach. Oryginalne dokumenty znajdą Państwo pod poniższymi linkami. Gdy zmieniają się przepisy, aktualizujemy również ten przewodnik.
Treść zweryfikowana 1.10.2026. W konkretnej sprawie podatkowej rozstrzyga obowiązujące brzmienie ustawy i okoliczności dostawy.