Konfigurácia e-mail hookov v PSB

Okrem webhookov ponúka PSB možnosť odosielať notifikácie e-mailom. E-mail hook (tiež mailhook alebo mailto hook) odošle e-mail pri každej udalosti na zvolenom topiku. Je to praktické pre organizácie, ktoré nemajú vlastný webhook endpoint, alebo ako doplnok k existujúcim webhookom.

Vytvorenie e-mail hooku

Zaregistrujte hook cez API s akciou mailto::

{
  "action": "mailto:financie@vasa-firma.sk",
  "topics": ["InvoiceReceived"]
}

Pri každej prijatej faktúre PSB teraz odošle notifikačný e-mail na zadanú adresu. E-mailová adresa v akcii môže obsahovať aj placeholder: [senderEmailAddress] alebo [receiverEmailAddress] na dynamické odosielanie na e-mailovú adresu odosielateľa alebo príjemcu.

Pozor: Pri placeholderoch vždy použite parameter fallbackEmail. Ak e-mailová adresa nie je v dokumente k dispozícii, PSB odošle notifikáciu na fallback adresu.

Parametre

E-mail hooky podporujú rozšírenú konfiguráciu cez parametre dotazu v action URL. URL zostavíte ako mailto:adresa@domena.sk?param1=hodnota&param2=hodnota.

Parameter

Hodnoty

Popis

includeAttachment

true / false

Pridá dokument (XML) ako prílohu k e-mailu

targetDocumentTypeId

URN reťazec

Transformuje prílohu do tohto formátu pred odoslaním (napríklad z NLCIUS na Factur-X)

filename

šablónový reťazec

Názov súboru prílohy s placeholdermi ako {{id}}{{extension}}. URL-enkódujte túto hodnotu

excludePrimaryAttachment

true / false

Vynechá XML prílohu (odošle len PDF prílohu)

excludeAdditionalAttachments

true / false

Vynechá ďalšie prílohy (vložené PDF/PNG z XML) (true) alebo ich priloží (false)

version

0.9 alebo 1.0

Verzia e-mailovej šablóny (pozri nižšie)

templateId

SendGrid template ID

Použitie vlastnej e-mailovej šablóny (musí byť nakonfigurované spoločnosťou eConnect)

fallbackEmail

e-mailová adresa

Povinné pri použití placeholderov v adrese

replyTo

e-mailová adresa

Reply-to adresa v e-maile

bcc

adresy oddelené čiarkou

BCC príjemcovia

from

e-mailová adresa

Prepísanie adresy odosielateľa (možné len s vlastným ApiKey)

Verzie šablón

PSB podporuje dve verzie e-mailovej šablóny:

Verzia

Adresa odosielateľa

Vysvetlenie

0.9

noreply@everbinding.nl

Stará šablóna so zastaranou doménou odosielateľa

1.0

noreply@econnect.email

Nová eConnect šablóna s moderným formátovaním

Tip: Pre nové konfigurácie používajte vždy verziu 1.0. Verzia 0.9 odosiela zo starej domény eVerbinding, ktorá sa už aktívne neudržiava.

Kompletný príklad

E-mail hook, ktorý pri každej prijatej faktúre odošle e-mail s faktúrou ako PDF prílohou, bez XML:

mailto:financie@vasa-firma.sk?includeAttachment=true&excludePrimaryAttachment=true&version=1.0

Hook, ktorý dynamicky odosiela odosielateľovi, s fallbackom:

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

Vlastná SendGrid šablóna

Chcete plnú kontrolu nad formátovaním e-mailu? Nechajte si od eConnectu nakonfigurovať vlastnú SendGrid šablónu a použite parameter templateId. Môžete tiež prepojiť vlastný SendGrid účet pridaním objektu init s Vaším API kľúčom do konfigurácie hooku.

Preposielanie prichádzajúcich faktúr do externej schránky: iba XML, bez PDF

Ak zákazník zistí, že preposielané prichádzajúce faktúry obsahujú iba XML a nie PDF, dôvodom je excludeAdditionalAttachments=true. Pri vytváraní e-mailového konektora/mailhooku je tento parameter predvolene nastavený na true, čo znamená, že prílohy PDF nie sú odosielané.

Riešenie: nastavte excludeAdditionalAttachments=false na mailhooku. Ďalšie prílohy (PDF/PNG z XML) budú potom v e-maile priložené.

Vykonanie: ak sa to týka automaticky vytvoreného e-mailového konektora (platforma Collabrr), túto zmenu môže vykonať iba TechSupport. Po oprave nekonfigurujte konektor ručne — ručná úprava prepíše opravu a opäť potlačí prílohu PDF. Ak zákazník spravuje vlastný PSB mailhook, môže parameter nastaviť na false sám.

Viacerí príjemcovia

Môžete zadať viacero e-mailových adries vytvorením samostatných hookov, alebo použitím parametra bcc pre ďalších príjemcov.

Undeliverable/NDR na no-reply adrese nie je chybou Peppolu

E-mail hook odosiela notifikácie z no-reply adresy (noreply@everbinding.nl pre verziu 0.9, noreply@econnect.email pre verziu 1.0). Ak prijímajúca poštová schránka odpovie automaticky — napríklad prostredníctvom správy o neprítomnosti — táto odpoveď sa často vráti ako Undeliverable alebo NDR (non-delivery report), typicky s kódom chyby 550 5.1.10 Recipient not found.

Ak dostanete takýto Undeliverable/NDR s predmetom odkazujúcim na PSB notifikáciu, ako je InvoiceSent, neznamená to, že faktúra nebola doručená cez Peppol. Topik InvoiceSent znamená, že odchádzajúca faktúra bola úspešne doručená prijímajúcej strane (pozri nastavenie webhookov: často používané topiky). Bounce vzniká preto, že poštová schránka zákazníka automaticky odpovedala na no-reply adresu — nie z dôvodu chyby doručenia cez Peppol.

Overenie:

Prečítajte prílohu NDR: odkazuje pôvodný predmet alebo odosielateľ obálky na no-reply adresu (noreply@everbinding.nl alebo noreply@econnect.email)?
Ak ide o notifikáciu ako InvoiceSent, faktúra už bola úspešne doručená. Bounce je reakciou na samotný notifikačný e-mail, nie chybou doručenia.
Požiadajte zákazníka, aby deaktivoval automatické odpovede alebo správu o neprítomnosti pre e-maily z everbinding.nl a econnect.eu, alebo aby no-reply adresy vylúčil z automatických odpovedí.

Skutočná chyba doručenia platformy sa prejaví stavom Delivery Failed v odchádzajúcej pošte — nie ako NDR na no-reply adresu.

Často kladené otázky

Prečo je fallbackEmail povinný pri placeholderoch v mailto adrese?

Placeholdery ako [senderEmailAddress] alebo [receiverEmailAddress] sa vyplnia len vtedy, ak je adresa v dokumente. Ak chýba, PSB odošle notifikáciu na adresu v fallbackEmail, aby ste neprišli o správu.

Čo je rozdiel medzi verziou šablóny 0.9 a 1.0?

Verzia 0.9 používa staršiu doménu odosielateľa noreply@everbinding.nl; verzia 1.0 používa noreply@econnect.email s moderným rozvrhnutím. Pre nové konfigurácie sa odporúča 1.0.

Ako poslať faktúru ako prílohu bez odoslania primárneho XML e-mailom?

Nastavte includeAttachment na true a excludePrimaryAttachment na true, aby ste napríklad poslali len PDF prílohu. Skombinujte to s version=1.0 v query reťazci pre požadovanú šablónu.

Preposielam prichádzajúce faktúry do externej schránky, ale dostávam iba XML, nie PDF. Čo je príčinou?

Príčinou je excludeAdditionalAttachments=true na mailhooku. Pri vytváraní e-mailového konektora je tento parameter predvolene nastavený na true, takže PDF a ďalšie prílohy z XML nie sú zahrnuté. Nastavte excludeAdditionalAttachments=false, aby ste zahrnuli ďalšie prílohy. Kontaktujte TechSupport, ak mailhook v PSB nespravujete sami; nekonfigurujte automaticky vytvorený konektor ručne po oprave TechSupport, keďže ručná úprava by opravu prepísala.

Dostávam Undeliverable/NDR na notifikáciu InvoiceSent. Znamená to zlyhanie doručenia cez Peppol?

Nie. Topik InvoiceSent znamená, že faktúra už bola úspešne doručená prijímajúcej strane. Undeliverable alebo NDR na takúto notifikáciu vzniká preto, že schránka príjemcu automaticky odpovedala (napríklad správou o neprítomnosti) na no-reply adresu odosielateľa notifikácie (noreply@everbinding.nl alebo noreply@econnect.email) — nie z dôvodu chyby Peppolu. V prípade pochybností overte, či odpoveď skutočne reaguje na no-reply adresu, a požiadajte zákazníka, aby pre tieto domény deaktivoval automatické odpovede.

Kompletnú API špecifikáciu nájdete na psb.econnect.eu so všetkými možnosťami konfigurácie a príkladmi.

Otvoriť API referenciu