Odosielanie a prijímanie faktúr cez sieť Peppol

Peppol je európska sieť na výmenu štruktúrovaných e-faktúr medzi podnikmi a verejnými inštitúciami. Každá faktúra putuje z prístupového bodu odosielateľa do prístupového bodu príjemcu. Nordlet zostavuje faktúry a dobropisy vo formáte Peppol BIS Billing 3.0 a odosiela a prijíma ich prostredníctvom účtu prístupového bodu vašej spoločnosti.

Peppol stanovuje pravidlá pre výmenu dokumentov medzi prístupovými bodmi navzájom, ale neurčuje, ako váš softvér komunikuje s vaším vlastným prístupovým bodom, pretože každý poskytovateľ má vlastné API. Nordlet spolupracuje s týmito poskytovateľmi:

Poskytovateľ	Odosielanie	Stav doručenia	Prijímanie
Recommand	áno	cez webhook a na požiadanie	áno
Storecove	áno	iba cez webhook	áno
e-invoice.be	áno	cez webhook a na požiadanie	áno

Bez prístupového bodu vám Nordlet stále vytvorí súbor Peppol pre každú vystavenú faktúru a dobropis, ktorý si môžete stiahnuť a odovzdať iným spôsobom, nič však neodosiela ani neprijíma.

Čo budete potrebovať

• Účet u jedného z vyššie uvedených poskytovateľov s firmou zaregistrovanou v sieti Peppol. Každý poskytovateľ si za svoje služby účtuje poplatky, pozrite si jeho cenník.
• V systéme Nordlet vyplnené IČ DPH, IČ DPH / identifikačné číslo organizácie alebo Peppol ID firmy (Účet → Firmy → Peppol ID). Každý odberateľ, ktorému posielate dokumenty, musí mať niektorý z týchto údajov uvedený na karte partnera.

Prepojenie prístupového bodu

Prejdite na Účet → Súlad s predpismi → EÚ → Peppol access point, v poli Poskytovateľ vyberte svojho poskytovateľa, vyplňte polia pre daného poskytovateľa podľa pokynov nižšie a uložte zmeny. Pole Základná adresa API (API base URL) nechajte prázdne, pokiaľ vám poskytovateľ neposkytol inú adresu. Po uložení sa na stránke zobrazí Adresa webhooku (Webhook URL) vašej spoločnosti: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, kde {provider} je recommand, storecove alebo e-invoice-be a {companyId} je identifikačné číslo vašej spoločnosti. Každá firma v Nordlete má svoju vlastnú adresu webhooku.

Nordlet akceptuje volanie webhooku iba vtedy, ak preukáže znalosť tajného kľúča webhooku (webhook secret), takže volanie nepochádzajúce z účtu vášho prístupového bodu bude odmietnuté. Nordlet kontaktuje verejné internetové adresy výhradne pri volaní vášho prístupového bodu.

Recommand

1. V aplikácii Recommand otvorte svoju spoločnosť a skopírujte jej ID spoločnosti do poľa ID účtu v prístupovom bode (Account ID at the access point).
2. V Recommand vytvorte kľúč API (API key) a skopírujte ho spolu s jeho tajným kľúčom do polí Kľúč API (API key) a Tajný kľúč API (API secret).
3. Vymyslite si dlhý náhodný text, ktorý budete poznať iba vy a služba Recommand, a zadajte ho do poľa Tajný kľúč webhooku (Webhook secret). Uložte.
4. V Recommand vytvorte webhook pre svoju spoločnosť s adresou webhooku zobrazenou v Nordlete a rovnakým tajným kľúčom webhooku.

Recommand podpisuje každé volanie webhooku týmto tajným kľúčom.

Storecove

1. V aplikácii Storecove vytvorte pre svoju spoločnosť právnickú osobu (legal entity) s povoleným odosielaním aj prijímaním a skopírujte jej ID do poľa ID účtu v prístupovom bode (Account ID at the access point).
2. V Storecove v sekcii Kľúče API (API Keys) vytvorte kľúč API a skopírujte ho do poľa Kľúč API (API key). Pole Tajný kľúč API (API secret) nechajte prázdne.
3. Vymyslite si dlhý náhodný text a zadajte ho do poľa Tajný kľúč webhooku (Webhook secret). Uložte.
4. V Storecove nastavte push webhook s adresou webhooku zobrazenou v Nordlete, chránený HTTP základnou autentifikáciou (HTTP Basic authentication): ľubovoľné užívateľské meno a tajný kľúč webhooku ako heslo.

Storecove neponúka volanie na zistenie stavu odoslaného dokumentu, takže v tomto prípade stav doručenia prichádza výhradne prostredníctvom jeho webhooku a stránka faktúry neobsahuje tlačidlo Skontrolovať stav v sieti Peppol (Check Peppol status). Testovací účet (sandbox) v Storecove odosiela správy do testovacej siete Peppol; produkčné kľúče API získate od podpory Storecove.

e-invoice.be

1. V aplikácii e-invoice.be v sekcii Nastavenia API (API Settings) skopírujte kľúč API (API key) svojej spoločnosti do poľa Kľúč API (API key). Polia ID účtu v prístupovom bode (Account ID at the access point) a Tajný kľúč API (API secret) nechajte prázdne. Uložte.
2. Vytvorte webhook prostredníctvom API e-invoice.be (POST https://api.e-invoice.be/api/webhooks/) s adresou webhooku zobrazenou v Nordlete a udalosťami document.received, document.sent a document.sent.failed.
3. Skopírujte hodnotu secret, ktorú API vráti pre nový webhook, do poľa Tajný kľúč webhooku (Webhook secret) v Nordlete a zmeny znova uložte.

e-invoice.be podpisuje každé volanie webhooku týmto tajným kľúčom. Testovacia spoločnosť (sandbox) v e-invoice.be dokumenty, ktoré by inak odoslala cez Peppol, namiesto toho odosiela e-mailom.

Odoslanie faktúry

1. Vystavte faktúru alebo dobropis.
2. Skontrolujte, či má odberateľ na karte partnera vyplnené Peppol ID, IČ DPH alebo identifikačné číslo organizácie.
3. Na stránke faktúry v sekcii Doručenie (Delivery) kliknite na možnosť Odoslať cez Peppol (Send via Peppol) a akciu potvrďte. Sekcia Doručenie sa zobrazuje pri nevydaných faktúrach, ktoré ešte nie sú uhradené, a tlačidlo sa zobrazí iba vtedy, keď je prepojený prístupový bod.

Nordlet vygeneruje súbor Peppol a odovzdá ho vášmu prístupovému bodu. Na stránke faktúry sa následne zobrazí sekcia Doručenie cez Peppol (Peppol delivery):

Stav	Význam
pending	Odovzdané prístupovému bodu; prístupový bod odberateľa to zatiaľ potvrdil
delivered	Prístupový bod odberateľa potvrdil prijatie faktúry
rejected	Odberateľ faktúru odmietol; dôvod je zobrazený pod stavom
failed	Faktúru sa nepodarilo doručiť; ak prístupový bod poskytol dôvod, zobrazí sa pod stavom

Stav sa aktualizuje automaticky, keď prístupový bod nahlási zmenu prostredníctvom svojho webhooku. Tlačidlo Skontrolovať stav v sieti Peppol (Check Peppol status) okamžite požiada službu Recommand alebo e-invoice.be o aktuálny stav. V prípade e-invoice.be načíta aj odpoveď odberateľa na faktúru, pričom odmietnutie (kód odpovede RE) sa zobrazí ako stav rejected. Odmietnutú alebo nedoručenú faktúru je možné po odstránení príčiny odoslať znova. Ak prístupový bod faktúru rázne odmietne, napríklad preto, že odberateľ nie je zaregistrovaný v sieti Peppol, Nordlet zobrazí dôvod a faktúra zostane neodoslaná.

Tlačidlo Peppol XML v hornej časti stránky faktúry umožňuje stiahnuť rovnaký súbor Peppol bez jeho odoslania.

V súlade s požiadavkami siete Peppol sa pri dodaní tovaru v rámci EÚ uvádza dátum vystavenia ako dátum dodania a krajina odberateľa ako krajina určenia.

Prijímanie faktúr

Keď prístupový bod nahlási prijatý dokument prostredníctvom webhooku, Nordlet stiahne súbor Peppol z prístupového bodu. Faktúry a dobropisy prijaté vašou spoločnosťou sa objavia v sekcii Nákup → Spracovanie dokumentov (Purchases → Document capture) a budú označené ako prijaté cez Peppol od Peppol ID odosielateľa. Nordlet spracováva súbor Peppol samostatne, takže prijímanie dokumentov nespotrebúva kredity na rozpoznávanie dokumentov (OCR).

1. Otvorte prijatý dokument.
2. Skontrolujte dodávateľa, dátumy a jednotlivé položky. Vyberte dodávateľa zo svojho zoznamu partnerov alebo vytvorte nového.
3. Kliknite na Uložiť koncept (Save draft). Nordlet vytvorí koncept došlej faktúry (alebo koncept došlého dobropisu v prípade prijatého dobropisu) s priloženým pôvodným súborom Peppol. Zaevidujte ho rovnako ako akúkoľvek inú došlú faktúru.

Položky došlých faktúr v Nordlete nemôžu byť záporné. Zľavy a prirážky pre celý dokument, ako aj záporné položky sa pomerne rozpočítajú medzi položky s rovnakou sadzbou DPH. Čiastka, ktorú nie je možné priradiť k žiadnej položke s danou sadzbou DPH (napríklad vrátený tovar v sadzbe DPH, ktorú iná položka faktúry neobsahuje), sa zobrazí v druhej tabuľke: Položky dobropisu (Credit note lines) pre prijatú faktúru alebo Položky faktúry (Invoice lines) pre prijatý dobropis. Tieto položky sa uložia ako druhý dokument pre rovnakého dodávateľa: došlý dobropis viažuci sa k novej faktúre s číslom „<číslo dokumentu>-CR“ alebo došlá faktúra s číslom „<číslo dokumentu>-INV“. Oba dokumenty spolu súhrnne zodpovedajú celkovej sume prijatého dokumentu.

Overenie, či je odberateľ zaregistrovaný v sieti Peppol

Volanie POST /v1/peppol/participants/lookup s parametrom partnerId alebo participantId („<schéma>:<identifikátor>“) preverí v sieti Peppol, či je príjemca zaregistrovaný a aké typy dokumentov akceptuje. Táto funkcia funguje aj bez pripojeného prístupového bodu.

Rovnaké operácie cez API

Úloha	Volanie API
Prepojenie prístupového bodu	POST /v1/declarations/configs/update s parametrami system: "peppol" a objektom config obsahujúcim hodnoty provider (recommand, storecove alebo e-invoice-be), accountId, apiKey, apiSecret, webhookSecret a voliteľne apiBaseUrl
Prijatie webhooku od prístupového bodu	POST /v1/peppol/webhooks/{provider}/{companyId}, volané prístupovým bodom
Stiahnutie súboru Peppol	POST /v1/sales/invoices/peppol-xml
Odoslanie	POST /v1/sales/invoices/peppol-send (vráti chybu 422 bez prístupového bodu)
Načítanie stavu doručenia	POST /v1/sales/invoices/peppol-status (vráti chybu 422 pri použití Storecove); faktúry obsahujú polia peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Vyhľadanie prijatých dokumentov	POST /v1/capture/documents/list; prijaté dokumenty majú hodnoty provider: "peppol" a senderId
Premena na došlú faktúru	POST /v1/capture/documents/confirm s parametrom oppositeLines pre druhý dokument

Udalosti webhooku: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed a document_capture.peppol_received. Podrobnosti o chybách, idempotencii a webhookoch nájdete v časti Konvencie API.