Konfiguracja e-mail hooków w PSB

Oprócz webhooków PSB oferuje możliwość wysyłania powiadomień e-mail. E-mail hook (nazywany również mailhook lub mailto hook) wysyła e-mail przy każdym zdarzeniu na wybranym topiku. Przydatne dla organizacji, które nie mają własnego endpointu webhookowego, lub jako uzupełnienie istniejących webhooków.

Tworzenie e-mail hooka

Rejestracja hooka przez API z akcją mailto::

{
  "action": "mailto:finanse@twoja-firma.pl",
  "topics": ["InvoiceReceived"]
}

Przy każdej otrzymanej fakturze PSB wyśle e-mail z powiadomieniem na podany adres. Adres e-mail w akcji może również zawierać placeholder: [senderEmailAddress] lub [receiverEmailAddress] do dynamicznego wysyłania na adres e-mail nadawcy lub odbiorcy.

Uwaga: Przy użyciu placeholderów zawsze należy stosować parametr fallbackEmail. Jeśli adres e-mail nie jest dostępny w dokumencie, PSB wyśle powiadomienie na adres zapasowy.

Parametry

E-mail hooki obsługują rozbudowaną konfigurację przez parametry query w URL akcji. URL buduje się jako mailto:adres@domena.pl?param1=wartość&param2=wartość.

Parametr

Wartości

Opis

includeAttachment

true / false

Dodaje dokument (XML) jako załącznik do e-maila

targetDocumentTypeId

Ciąg URN

Transformuje załącznik do tego formatu przed wysłaniem (np. z NLCIUS na Factur-X)

filename

Ciąg szablonowy

Nazwa pliku załącznika, z placeholderami jak {{id}}{{extension}}. Należy zakodować tę wartość w URL

excludePrimaryAttachment

true / false

Pomija załącznik XML (wysyła tylko załącznik PDF)

excludeAdditionalAttachments

true / false

Pomija dodatkowe załączniki (osadzone PDF/PNG z XML) (true) lub je dołącza (false)

version

0.9 lub 1.0

Wersja szablonu e-mail (patrz poniżej)

templateId

ID szablonu SendGrid

Używa własnego szablonu e-mail (musi być skonfigurowany przez eConnect)

fallbackEmail

Adres e-mail

Wymagany przy użyciu placeholderów w adresie

replyTo

Adres e-mail

Adres reply-to w e-mailu

bcc

Adresy oddzielone przecinkami

Odbiorcy BCC

from

Adres e-mail

Nadpisanie adresu nadawcy (możliwe tylko z własnym ApiKey)

Wersje szablonów

PSB obsługuje dwie wersje szablonu e-mail:

Wersja

Adres nadawcy

Uwagi

0.9

noreply@everbinding.nl

Stary szablon z przestarzałą domeną nadawcy

1.0

noreply@econnect.email

Nowy szablon eConnect z nowoczesnym layoutem

Wskazówka: Zawsze należy używać wersji 1.0 dla nowych konfiguracji. Wersja 0.9 wysyła ze starej domeny eVerbinding, która nie jest już aktywnie utrzymywana.

Pełny przykład

E-mail hook, który przy każdej otrzymanej fakturze wysyła e-mail z fakturą jako załącznik PDF, bez XML:

mailto:finanse@twoja-firma.pl?includeAttachment=true&excludePrimaryAttachment=true&version=1.0

Hook, który dynamicznie wysyła do nadawcy, z fallbackiem:

mailto:[senderEmailAddress]?includeAttachment=true&version=1.0&fallbackEmail=backup@twoja-firma.pl

Własny szablon SendGrid

Chcą Państwo mieć pełną kontrolę nad wyglądem e-maila? Należy zlecić eConnect skonfigurowanie własnego szablonu SendGrid i użyć parametru templateId. Można też podłączyć własne konto SendGrid, dodając obiekt init z kluczem API do konfiguracji hooka.

Przekazywanie faktur przychodzących do zewnętrznej skrzynki: tylko XML, bez PDF

Jeśli klient stwierdza, że przekazane faktury przychodzące zawierają tylko XML bez pliku PDF, przyczyną jest excludeAdditionalAttachments=true. Podczas tworzenia konektora e-mail/mailhooka ten parametr jest domyślnie ustawiony na true, co oznacza, że załączniki PDF nie są wysyłane.

Rozwiązanie: należy ustawić excludeAdditionalAttachments=false na mailhooku. Dodatkowe załączniki (PDF/PNG z XML) będą wówczas dołączane do e-maila.

Wykonanie: jeśli dotyczy to automatycznie utworzonego konektora e-mail (platforma Collabrr), zmianę może wprowadzić wyłącznie TechSupport. Nie należy ręcznie modyfikować konektora po korekcie — ręczna zmiana nadpisze korektę i ponownie wyłączy załącznik PDF. Jeśli klient zarządza własnym mailhookiem PSB, może samodzielnie ustawić parametr na false.

Wielu odbiorców

Można podać wiele adresów e-mail, tworząc osobne hooki, lub korzystając z parametru bcc dla dodatkowych odbiorców.

Undeliverable/NDR na adresie no-reply to nie błąd Peppol

E-mail hook wysyła powiadomienia z adresu no-reply (noreply@everbinding.nl dla wersji 0.9, noreply@econnect.email dla wersji 1.0). Jeśli odbierająca skrzynka pocztowa odpowiada automatycznie — na przykład przez wiadomość o nieobecności — odpowiedź ta często wraca jako Undeliverable lub NDR (non-delivery report), zazwyczaj z kodem błędu 550 5.1.10 Recipient not found.

Jeśli otrzymają Państwo taki Undeliverable/NDR z tematem odnoszącym się do powiadomienia PSB, np. InvoiceSent, nie oznacza to, że faktura nie została dostarczona przez Peppol. Topik InvoiceSent oznacza, że wychodząca faktura została pomyślnie dostarczona do strony odbierającej (zob. konfiguracja webhooków: często używane topiki). Odbicie następuje dlatego, że skrzynka klienta automatycznie odpowiedziała na adres no-reply — nie z powodu błędu dostarczenia przez Peppol.

Weryfikacja:

Proszę przeczytać załącznik NDR: czy oryginalny temat lub nadawca koperty odnosi się do adresu no-reply (noreply@everbinding.nl lub noreply@econnect.email)?
Jeśli dotyczy to powiadomienia takiego jak InvoiceSent, faktura została już pomyślnie dostarczona. Odbicie jest reakcją na sam e-mail z powiadomieniem, a nie błędem dostarczenia.
Należy poprosić klienta o wyłączenie automatycznej odpowiedzi lub wiadomości o nieobecności dla wiadomości z everbinding.nl i econnect.eu, lub o wykluczenie adresów no-reply z automatycznych odpowiedzi.

Rzeczywisty błąd dostarczenia platformy pojawia się jako status Delivery Failed w skrzynce nadawczej — nie jako NDR na adres no-reply.

Często zadawane pytania

Dlaczego przy placeholderach w adresie mailto wymagany jest fallbackEmail?

Placeholdery takie jak [senderEmailAddress] lub [receiverEmailAddress] są uzupełniane tylko wtedy, gdy adres znajduje się w dokumencie. Jeśli go brakuje, PSB wysyła powiadomienie na adres w fallbackEmail, aby Państwo nie tracili wiadomości.

Jaka jest różnica między wersją szablonu 0.9 a 1.0?

Wersja 0.9 korzysta ze starszej domeny nadawcy noreply@everbinding.nl; wersja 1.0 używa noreply@econnect.email z nowoczesnym układem. W nowych konfiguracjach zalecana jest 1.0.

Jak wysłać fakturę jako załącznik bez e-mailowania pierwotnego XML?

Należy ustawić includeAttachment na true i excludePrimaryAttachment na true, aby na przykład wysłać tylko załącznik PDF. Należy to połączyć z version=1.0 w query string dla wybranego szablonu.

Przekazuję faktury przychodzące do zewnętrznej skrzynki, ale otrzymuję tylko XML, nie PDF. Co jest przyczyną?

Przyczyną jest excludeAdditionalAttachments=true na mailhooku. Podczas tworzenia konektora e-mail parametr ten jest domyślnie ustawiony na true, co oznacza, że pliki PDF i inne załączniki z XML nie są dołączane. Należy ustawić excludeAdditionalAttachments=false, aby dołączyć dodatkowe załączniki. Proszę skontaktować się z TechSupport, jeśli nie zarządzają Państwo mailhookiem samodzielnie w PSB; nie należy ręcznie modyfikować automatycznie utworzonego konektora po korekcie TechSupport, gdyż ręczna zmiana nadpisze korektę.

Otrzymuję Undeliverable/NDR na powiadomienie InvoiceSent. Czy oznacza to nieudane dostarczenie przez Peppol?

Nie. Topik InvoiceSent oznacza, że faktura została już pomyślnie dostarczona do strony odbierającej. Undeliverable lub NDR na takie powiadomienie pojawia się dlatego, że skrzynka odbiorcy automatycznie odpowiedziała (np. wiadomością o nieobecności) na adres no-reply nadawcy powiadomienia (noreply@everbinding.nl lub noreply@econnect.email) — nie z powodu błędu dostarczenia przez Peppol. W razie wątpliwości należy sprawdzić, czy odpowiedź jest rzeczywiście reakcją na adres no-reply, i poprosić klienta o wyłączenie automatycznych odpowiedzi dla tych domen.

Pełna specyfikacja API dostępna jest na psb.econnect.eu ze wszystkimi możliwymi konfiguracjami i przykładami.

Otwórz referencję API