Integracja Peppol w aplikacji: wysyłka e-faktur przez KRONENWERK

Wysyłkę przez Peppol integrują Państwo w swojej aplikacji przez KRONENWERK, tworząc szkic faktury za pomocą POST /invoices/drafts, zlecając wystawienie i przesłanie faktury w produkcie oraz odbierając invoice.issued na swoim punkcie końcowym webhooka. KRONENWERK nie jest punktem dostępowym Peppol. Wysyła i odbiera przez Peppol za pośrednictwem akredytowanego dostawcy punktu dostępowego (Storecove), gdy firma zostanie podłączona w Ustawienia → Dostarczanie, a wysyłka produkcyjna zależy od tego konta i jego konfiguracji. Funkcja jest OBSŁUGIWANA Z OGRANICZENIAMI.

Czym jest Peppol z perspektywy integratora

Peppol to czteronarożna sieć dostarczania: Państwa firma (narożnik 1) przekazuje dokument swojemu punktowi dostępowemu (narożnik 2), który wyszukuje punkt dostępowy odbiorcy (narożnik 3) w katalogu SML/SMP i dostarcza dokument firmie odbierającej (narożnik 4). Dokumenty to ustrukturyzowany UBL zgodny z Peppol BIS Billing 3.0, implementacją EN 16931. Uczestnicy są adresowani identyfikatorami, takimi jak numer VAT w schemacie z list kodów OpenPeppol, które są w sieci obowiązkowe i regularnie aktualizowane (v9.7 na dzień 2 lipca 2026 r.). Mechanizm wyjaśniono na stronie Peppol, identyfikatory na stronie identyfikatory Peppol, a stronę praktyczną na stronie wysyłanie i odbieranie przez Peppol.

Dla programisty konsekwencja jest prosta: nigdy nie komunikują się Państwo z siecią bezpośrednio. Robi to czyjś punkt dostępowy, a pytanie brzmi — czyj. Zbudowanie własnego punktu dostępowego oznacza członkostwo w OpenPeppol, akredytację, bramę AS4 i publikację w SMP. Korzystanie z KRONENWERK oznacza, że punkt dostępowy należy do Storecove, połączenie należy do firmy, a Państwa kod komunikuje się wyłącznie z API KRONENWERK.

Przepływ: szkic, wystawienie, przesłanie, webhook

1. Państwa aplikacja tworzy klienta za pomocą POST /customers. Należy nadać klientowi kraj i numer VAT: identyfikator uczestnika Peppol belgijskiego odbiorcy jest wyprowadzany z jego numeru przedsiębiorstwa lub numeru VAT, a klient bez niego nie może być zaadresowany w sieci.
2. Państwa aplikacja rozpoczyna szkic za pomocą POST /invoices/drafts i nagłówka Idempotency-Key. Odpowiedzią jest szkic w stanie DRAFT z propozycją numeracji sprzedawcy i warunkami płatności klienta.
3. Osoba wystawia szkic w produkcie. KRONENWERK oblicza wynik weryfikacji podatkowej, sprawdza numer VAT w VIES, renderuje Peppol BIS Billing 3.0 UBL dla belgijskiego sprzedawcy, waliduje go i zużywa numer. W tym momencie invoice.issued jest kolejkowane do Państwa punktu końcowego.
4. Faktura jest przesyłana z produktu. Przesłanie to osobna, audytowana czynność na wystawionej fakturze, a nie efekt uboczny wystawienia: moduł krajowy wskazuje drogę (Peppol dla Belgii), podłączony dostawca punktu dostępowego przenosi dokument, a wynik jest zapisywany przy fakturze. Jeśli wynik jest nieznany — przekroczenie czasu po wysłaniu żądania — produkt odmawia ponownej wysyłki, dopóki wywołanie uzgadniające nie zapyta drugiej strony, czy posiada dokument. Ponawianie przy nieznanym wyniku to sposób, w jaki z jednej faktury robią się dwie.
5. Państwa aplikacja odbiera invoice.issued, weryfikuje KRONENWERK-Signature, deduplikuje po KRONENWERK-Event-Id i zapisuje invoiceId oraz number. Później następują invoice.paid lub invoice.cancelled.

Co musi skonfigurować programista

Warto zauważyć, czego nie ma na liście: żadnego SMP, żadnego certyfikatu AS4, żadnego członkostwa w OpenPeppol po Państwa stronie. Warto też zauważyć, czego API nie może zrobić: nie może podłączyć firmy do sieci, nie może przesyłać i nie może odczytać dziennika przesyłania. To ustawienia i czynności, które osoba wykonuje w produkcie.

Przykładowe żądania

curl -X POST https://kronenwerk.org/api/extern/v1/customers \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voorbeeld BV",
    "street": "Rue de l'"'"'Exemple 12",
    "postalCode": "1000",
    "city": "Bruxelles",
    "country": "BE",
    "vatId": "BE0123456789",
    "email": "invoices@example.be"
  }'

curl -X POST https://kronenwerk.org/api/extern/v1/invoices/drafts \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213-2026-09" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "3f2b…" }'

Odpowiedź dotycząca klienta zawiera numer kontrahenta pobrany z własnej sekwencji firmy (na przykład K-0042) oraz pola w zapisanej postaci: id, number, name, contact, email, phone, street, postalCode, city, country, vatId, currency, customer, supplier, archived, createdAt. Nazwa, ulica, kod pocztowy i miejscowość są wymagane, ponieważ EN 16931 przenosi adres w częściach, a klient bez ulicy to klient, do którego nie da się zaadresować żadnego dokumentu. API faktur jest w pełni opisane na stronie API faktur.

Odbiór przez Peppol

W Belgii obowiązek odbioru faktur ustrukturyzowanych przez Peppol dotyczy firm zarejestrowanych do VAT bez progu, więc połączenie, które tylko wysyła, byłoby połową obowiązku. Po podłączeniu firmy przychodzące dokumenty Peppol docierają do dostawcy punktu dostępowego, są przekazywane do KRONENWERK, wczytywane jako faktury zakupu i walidowane. Państwa integracja dowiaduje się o nich przez webhook purchase.recorded, który zawiera purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor i grossMinor. Sam dokument przychodzący nie jest udostępniany w API. Kontekst belgijski znajduje się w przeglądzie Belgii i na stronie krajowej Belgia.

Alternatywy, uczciwie porównane

Jeśli Państwa wymaganiem jest w pełni zautomatyzowana wysyłka bez osoby wystawiającej, API KRONENWERK dziś tego nie oferuje, a uczciwą rekomendacją jest bezpośrednia umowa z dostawcą. Przewodnik Peppol dla programistów opisuje, co należałoby wówczas zbudować; Peppol a sieci krajowe wyjaśnia, gdzie drogą jest Peppol, a gdzie system krajowy (KSeF, francuskie plateformes agréées).

Jak KRONENWERK to obsługuje

OBSŁUGIWANE Z OGRANICZENIAMI KRONENWERK generuje Peppol BIS Billing 3.0 UBL dla belgijskich sprzedawców przy wystawianiu oraz wysyła i odbiera przez Peppol za pośrednictwem akredytowanego dostawcy punktu dostępowego (Storecove), gdy firma zostanie podłączona w Ustawienia → Dostarczanie. KRONENWERK sam nie jest akredytowanym ani certyfikowanym punktem dostępowym Peppol. Wysyłka produkcyjna zależy od konta Storecove firmy i jego konfiguracji, a przesłanie jest czynnością, którą osoba wykonuje w produkcie po wystawieniu. Udziałem API są klient, szkic, odczyt zwrotny i webhooki, w planie Enterprise. Droga Peppol jest skonfigurowana dla belgijskich sprzedawców; dla niemieckich sprzedawców produkt tworzy XRechnung lub ZUGFeRD do wysyłki e-mailem lub pobrania i nie wskazuje drogi przesyłania, ponieważ niemieckie prawo żadnej nie wskazuje. Francuskie przesyłanie to inny mechanizm i jest JESZCZE NIEGOTOWE — zob. francuskie platformy. Szczegóły produktu: e-fakturowanie.