Wysyłanie i odbieranie faktur przez Peppol

Peppol to europejska sieć służąca do wymiany ustrukturyzowanych e-faktur między przedsiębiorstwami a organami publicznymi. Każda faktura wędruje z punktu dostępowego nadawcy do punktu dostępowego odbiorcy. Nordlet generuje faktury i faktury korygujące zgodne ze standardem Peppol BIS Billing 3.0, a następnie wysyła je i odbiera za pośrednictwem konta punktu dostępowego Twojej firmy.

Sieć Peppol określa zasady wymiany dokumentów między punktami dostępowymi, ale nie definiuje, w jaki sposób oprogramowanie komunikuje się z własnym punktem dostępowym, ponieważ każdy dostawca posiada własne API. Nordlet współpracuje z następującymi dostawcami:

Dostawca	Wysyłka	Status doręczenia	Odbiór
Recommand	tak	przez webhook oraz na żądanie	tak
Storecove	tak	tylko przez webhook	tak
e-invoice.be	tak	przez webhook oraz na żądanie	tak

Bez skonfigurowanego punktu dostępowego Nordlet nadal przygotowuje plik Peppol dla każdej wystawionej faktury i faktury korygującej, abyś mógł go pobrać i przekazać w inny sposób, jednak nie wysyła ani nie odbiera żadnych dokumentów automatycznie.

Czego potrzebujesz

• Konta u jednego z wyżej wymienionych dostawców, za pośrednictwem którego Twoja firma jest zarejestrowana w sieci Peppol. Każdy dostawca pobiera opłaty za swoje usługi, szczegóły znajdziesz w jego cenniku.
• W systemie Nordlet, numeru NIP (VAT) firmy, numeru rejestracyjnego lub identyfikatora Peppol (Konto -> Firmy -> Identyfikator Peppol). Każdy klient, do którego wysyłasz dokumenty, również musi posiadać jedną z tych danych na swojej karcie partnera.

Łączenie punktu dostępowego

Otwórz zakładkę Konto -> Zgodność z przepisami -> UE -> Punkt dostępowy Peppol, wybierz swojego dostawcę w polu Dostawca, wypełnij pola dla tego dostawcy zgodnie z poniższym opisem i zapisz zmiany. Pozostaw pole Bazowy adres URL API puste, chyba że dostawca przekazał Ci inny adres. Po zapisaniu na stronie pojawi się Adres URL webhooka Twojej firmy: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, gdzie {provider} to recommand, storecove lub e-invoice-be, a {companyId} to identyfikator Twojej firmy. Każda firma w systemie Nordlet posiada własny unikalny adres URL webhooka.

Nordlet akceptuje wywołanie webhooka wyłącznie wtedy, gdy żądanie potwierdza znajomość sekretu webhooka, co oznacza, że wywołania pochodzące spoza konta Twojego punktu dostępowego są odrzucane. Nordlet nawiązuje połączenie z publicznymi adresami internetowymi tylko wtedy, gdy wywołuje Twój punkt dostępowy.

Recommand

1. W serwisie Recommand otwórz profil swojej firmy i skopiuj jej identyfikator firmy do pola Identyfikator konta w punkcie dostępowym.
2. W Recommand utwórz klucz API (API key) i skopiuj klucz oraz jego sekret do pól Klucz API i Sekret API.
3. Wymyśl długi, losowy tekst, który będzie znany tylko Tobie i systemowi Recommand, a następnie wpisz go w polu Sekret webhooka. Zapisz zmiany.
4. W Recommand utwórz webhook dla swojej firmy, podając adres URL webhooka wyświetlony przez Nordlet oraz ten sam sekret webhooka.

Recommand podpisywać będzie każde wywołanie webhooka tym sekretem.

Storecove

1. W serwisie Storecove utwórz podmiot prawny (legal entity) dla swojej firmy z uprawnieniami do wysyłania i odbierania dokumentów, a następnie skopiuj jego identyfikator do pola Identyfikator konta w punkcie dostępowym.
2. W Storecove w sekcji Klucze API (API Keys) utwórz klucz API i wklej go do pola Klucz API. Pole Sekret API pozostaw puste.
3. Wymyśl długi, losowy tekst i wpisz go w polu Sekret webhooka. Zapisz zmiany.
4. W Storecove skonfiguruj webhook typu push, używając adresu URL webhooka z systemu Nordlet, zabezpieczonego uwierzytelnianiem HTTP Basic: dowolna nazwa użytkownika oraz sekret webhooka jako hasło.

Storecove nie udostępnia metody zapytania o status wysłanego dokumentu, w związku z czym w przypadku tego dostawcy status doręczenia pochodzi wyłącznie z webhooka, a na stronie faktury nie ma przycisku Sprawdź status Peppol. Konto piaskownicowe (sandbox) w Storecove wysyła dokumenty w sieci testowej Peppol; produkcyjne klucze API można uzyskać od wsparcia technicznego Storecove.

e-invoice.be

1. W aplikacji e-invoice.be w sekcji Ustawienia API (API Settings) skopiuj klucz API swojej firmy do pola Klucz API. Pola Identyfikator konta w punkcie dostępowym oraz Sekret API pozostaw puste. Zapisz zmiany.
2. Utwórz webhook za pomocą API e-invoice.be (POST https://api.e-invoice.be/api/webhooks/), podając adres URL webhooka wyświetlony przez Nordlet oraz zdarzenia document.received, document.sent i document.sent.failed.
3. Skopiuj wartość secret, którą API zwraca dla nowego webhooka, wklej ją do pola Sekret webhooka w systemie Nordlet i ponownie zapisz zmiany.

Serwis e-invoice.be podpisuje każde wywołanie webhooka tym sekretem. Firma testowa (sandbox) w e-invoice.be wysyła dokumenty przeznaczone do wysyłki w wiadomościach e-mail zamiast przesyłać je przez sieć Peppol.

Wysyłanie faktury

1. Wystaw fakturę lub fakturę korygującą.
2. Upewnij się, że klient posiada uzupełniony identyfikator Peppol, numer NIP (VAT) lub numer rejestracyjny na swojej karcie partnera.
3. Na stronie faktury w sekcji Doręczenie kliknij Wyślij przez Peppol i potwierdź operację. Sekcja Doręczenie jest widoczna dla wystawionych, jeszcze nieopłaconych faktur, a przycisk pojawia się tylko wtedy, gdy punkt dostępowy jest połączony.

Nordlet generuje plik Peppol i przekazuje go do Twojego punktu dostępowego. Następnie na stronie faktury pojawia się sekcja Doręczenie Peppol:

Status	Znaczenie
pending	Przekazano do punktu dostępowego; punkt dostępowy klienta jeszcze nie potwierdził przyjęcia
delivered	Punkt dostępowy klienta potwierdził odebranie faktury
rejected	Klient odrzucił fakturę; powód odrzucenia widnieje pod statusem
failed	Nie udało się doręczyć faktury; powód jest widoczny pod statusem, o ile punkt dostępowy go przekazał

Status aktualizuje się automatycznie, gdy punkt dostępowy zgłosi zmianę za pośrednictwem webhooka. Przycisk Sprawdź status Peppol natychmiast wysyła zapytanie do Recommand lub e-invoice.be o aktualny status; w przypadku e-invoice.be odczytuje on również odpowiedź klienta na fakturę, a odmowa przyjęcia (kod odpowiedzi RE) jest wyświetlana jako status odrzuconej (rejected). Odrzuconą lub niedoręczoną fakturę można wysłać ponownie po usunięciu przyczyny błędu. Jeśli punkt dostępowy odrzuci fakturę od razu, na przykład z powodu braku rejestracji klienta w sieci Peppol, Nordlet wyświetli powód, a faktura pozostanie niewysłana.

Przycisk XML Peppol w górnej części strony faktury pozwala pobrać ten sam plik Peppol bez jego wysyłania.

W przypadku transakcji wewnątrzwspólnotowej data wystawienia jest traktowana jako data dostawy, a kraj klienta jako kraj dostawy, zgodnie z wymogami specyfikacji Peppol.

Odbieranie faktur

Gdy punkt dostępowy zgłosi odebranie dokumentu przez webhook, Nordlet pobiera plik Peppol z punktu dostępowego. Faktury i faktury korygujące otrzymane przez Twoją firmę pojawiają się w sekcji Zakupy -> Przechwytywanie dokumentów i są oznaczone jako odebrane przez sieć Peppol z identyfikatora Peppol nadawcy. Nordlet samodzielnie odczytuje plik Peppol, dzięki czemu odbiór dokumentów nie zużywa punktów rozpoznawania tekstów.

1. Otwórz odebrany dokument.
2. Sprawdź dostawcę, daty oraz pozycje; wybierz dostawcę spośród swoich partnerów lub utwórz nowego.
3. Kliknij Zapisz jako wersję roboczą. Nordlet utworzy projekt faktury zakupowej (lub projekt korekty zakupu w przypadku otrzymanej faktury korygującej) wraz z załączonym oryginalnym plikiem Peppol. Dalej obsłuż dokument tak samo, jak każdą inną fakturę zakupową.

Pozycje na fakturach zakupowych w systemie Nordlet nie mogą mieć ujemnych wartości. Rabaty i opłaty dotyczące całego dokumentu oraz ujemne pozycje są proporcjonalnie rozdzielane na pozycje objęte tą samą stawką podatku VAT. Kwota, której nie można przypisać do żadnej pozycji o danej stawce VAT, taka jak zwrot towaru ze stawką, dla której faktura nie ma innych pozycji, jest prezentowana w drugiej tabeli: Pozycje korekty w przypadku otrzymanej faktury lub Pozycje faktury w przypadku otrzymanej korekty. Te pozycje są zapisywane jako drugi dokument dla tego samego dostawcy: korekta zakupu powiązana z nową fakturą o numerze w formacie „-CR” lub faktura zakupowa o numerze w formacie „-INV”. Oba dokumenty łącznie sumują się do kwot widocznych na otrzymanym dokumencie.

Sprawdzanie, czy klient jest zarejestrowany w Peppol

Zapytanie POST /v1/peppol/participants/lookup zawierające parametr partnerId lub participantId (w formacie „:”) sprawdza w sieci Peppol, czy odbiornik jest zarejestrowany oraz jakie dokumenty akceptuje. Funkcja ta działa bez skonfigurowanego punktu dostępowego.

Wykonywanie tych samych operacji przez API

Zadanie	Wywołanie
Połączenie punktu dostępowego	POST /v1/declarations/configs/update z parametrami system: "peppol" oraz config zawierającym provider (recommand, storecove lub e-invoice-be), accountId, apiKey, apiSecret, webhookSecret i opcjonalnym apiBaseUrl
Odbiór webhooka z punktu dostępowego	POST /v1/peppol/webhooks/{provider}/{companyId}, wywoływane przez punkt dostępowy
Pobranie pliku Peppol	POST /v1/sales/invoices/peppol-xml
Wysyłka	POST /v1/sales/invoices/peppol-send (zwraca błąd 422 bez skonfigurowanego punktu dostępowego)
Odczyt statusu doręczenia	POST /v1/sales/invoices/peppol-status (zwraca błąd 422 w przypadku Storecove); faktury zawierają pola peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Wyszukiwanie odebranych dokumentów	POST /v1/capture/documents/list; odebrane dokumenty posiadają pola provider: "peppol" oraz senderId
Zamiana dokumentu w fakturę zakupową	POST /v1/capture/documents/confirm, z parametrem oppositeLines dla drugiego dokumentu

Zdarzenia webhooka: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed oraz document_capture.peppol_received. Informacje na temat błędów, idempotencji i webhooków znajdziesz w sekcji Konwencje API.