Odoslanie e-faktúry cez API PSB je najpoužívanejší endpoint. Odošlete XML dokument v ľubovoľnom podporovanom formáte (UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X/ZUGFeRD a ďalšie) a PSB sa postará o automatickú detekciu formátu, validáciu, routing a doručenie cez príslušnú sieť.

POST /api/v1/{partyId}/salesInvoice/send

{partyId} v URL je Peppol identifikátor odosielajúcej organizácie (dodávateľa). Požiadavka obsahuje XML dokument ako body (content-type application/xml). PSB automaticky rozpozná formát dokumentu (UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X/ZUGFeRD, FatturaPA a ďalšie) a validuje dokument voči príslušným pravidlám.

1. Upload: odošlite XML dokument na endpoint
2. Validácia: PSB validuje dokument voči XSD schéme a obchodným pravidlám
3. Routing: PSB vyhľadá cez SML/SMP, ako dosiahnuť príjemcu
4. Doručenie: dokument je doručený cez príslušný kanál (Peppol, e-mail alebo iná sieť)
5. Aktualizácia stavu: dostanete webhook notifikáciu so stavom doručenia

Dôležité: PSB určuje príjemcu na základe EndpointID vo Vašom XML dokumente. Ak tento element chýba alebo obsahuje nesprávny identifikátor, odoslanie zlyhá so stavom InvoiceSentError. Uistite sa, že Váš zdrojový systém správne vypĺňa EndpointID. Viac o identifikátoroch a routingu nájdete v článku o Peppol identifikátoroch.

PSB podporuje idempotency cez header požiadavky X-EConnect-DocumentId. Zahrnutím vlastného UUID pri každej upload požiadavke sa zabráni duplicitnému spracovaniu:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Ak odošlete rovnaký documentId znova, API vráti 409 Conflict a odosielateľ vie, že dokument už bol spracovaný.

Dôležité: Vždy používajte UUID/GUID ako documentId. Nikdy nepoužívajte číslo faktúry, pretože to spôsobuje problémy pri opätovnom odoslaní opravenej verzie tej istej faktúry.

Pred odoslaním faktúry môžete cez queryRecipientParty skontrolovať, či a ako je príjemca dostupný:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

V tele požiadavky odovzdávate zoznam identifikátorov, napríklad ["0106:12345678"], alebo objekt s partyIds a metaAttributes. Voliteľné parametre dotazu sú ?preferredDocumentTypeId a ?includeOptions.

Odpoveď obsahuje informácie o:

• Či je príjemca registrovaný na Peppol
• Aké typy dokumentov príjemca môže prijímať
• Cez aký Access Point je príjemca dostupný
• Aký kanál PSB použije na doručenie

Pre pokročilé vyhľadávanie vrátane URL Access Pointu a certifikátu AP je k dispozícii samostatná cesta:

GET /api/v1/peppol/deliveryOption?partyIds={id}&documentFamily=Invoice&isCredit=false

Pri neúspešnom doručení PSB automaticky uplatňuje mechanizmus opakovania:

• Maximálne 8 pokusov rozložených na približne 35 hodín
• Iba pri chybách servera 5xx (dočasné chyby na strane príjemcu)
• Pri každom pokuse sa publikuje udalosť InvoiceSentRetry
• Pri definitívnom zlyhaní dostanete udalosť InvoiceSentError cez Váš webhook

Časté chyby pri odosielaní:

Poznámka: SI-UBL 1.2 (Simpler Invoicing 1.2) nie je povolený na sieti Peppol od 1. januára 2024. Faktúry v tomto formáte výsledkujú v InvoiceSentError. Používajte NLCIUS (SI-UBL 2.0) alebo Peppol BIS Billing V3. Skontrolujte CustomizationID vo Vašom XML dokumente, ak narazíte na túto chybu.

Úspešný upload vráti 200 OK s identifikátorom dokumentu v PSB. Tento identifikátor použite na sledovanie stavu dokumentu cez API alebo cez webhoky.

Na rozdiel od purchaseInvoice endpoint salesInvoice nemá DELETE. Ide o zámerné rozhodnutie, pretože odoslaná alebo odmietnutá predajná faktúra je udalosť významná pre audit: dokument zostáva dohl'adateľný v auditnej stope aj po tom, ako odoslanie zlyhalo.

Zákazníci sa niekedy pýtajú, či možno odmietnutú predajnú faktúru zastaviť alebo zmazať, napríklad po tom, ako faktúru interné už dobropisovali. Odpoveď znie:

• Chyba validácie (4xx, napríklad Invalid payload): PSB umiestni dokument do konečného stavu InvoiceSentError. Žiadne opakovanie sa nevykonáva (opakujú sa iba chyby 5xx). Dokument nie je dodatočne doručený príjemcovi. Na PSB nie je potrebná žiadna akcia; dokument je v konečnom stave a uchováva sa 90 dní na účely auditu.
• Žiadny DELETE endpoint nie je potrebný: pretože dokument už nie je aktívny a neopakuje sa, nemusí byť explicitne mazaný na zastavenie odoslania.
• Poslať opravu pomocou nového dokumentu: ak bola pôvodná faktúra nesprávna a už bola (čiastočne) doručená, použite dobropis alebo opravnú faktúru podľa štandardného účtovníckeho postupu. Pôvodný documentId zostáva ako referencia v auditnej stope.

Tento rozdiel v životnom cykle medzi salesInvoice (bez DELETE) a purchaseInvoice (s DELETE) vyplýva z roly: odchodzia faktúra je obchodný úkon zaznamenaný odosielateľom, ktorý musí byť právne dohl'adateľný; prichodzia faktúra môže byť po úspešnom stiahnutí odstránená z vlastného systému príjemcu.

Štandardne PSB automaticky vyberá najlepší kanál. S parametrom dopytu ?channel={hookId} môžete vynútiť konkrétny kanál doručenia (napr. konkrétnu sieť alebo e-mailový fallback).

Prílohy (PDF, obrázky) sa môžu vložiť ako base64 do UBL dokumentu ako AdditionalDocumentReference. PSB spracúva vložené prílohy správne a doručuje ich spolu s faktúrou.

Poznámka: Endpoint odosielania akceptuje maximálne 24 MB na požiadavku (vrátane HTTP overheadu). Pri prílohách kódovaných v base64 payload narastie o približne 33%, takže 18 MB PDF výsledkuje v požiadavke o veľkosti približne 24 MB. Payloady presahujúce limit sú odmietnuté webovým serverom s HTTP 500 (nie 413), ešte pred aplikačnou validáciou. Zmenšite veľké prílohy alebo ich odošlite cez samostatný kanál.

Tip: Aktuálny štandard Peppol BIS Billing 3.0 podporuje maximálne jednu OrderReference na faktúru. Ak sa faktúra vzťahuje na viacero objednávok, musia sa odoslať viaceré faktúry.

Tip: Niektorí príjemcovia hlásia chyby pri faktúrach s XML namespace prefixom (napr. <urn:Invoice> namiesto <Invoice>). Obe formy sú technicky správny XML podľa W3C špecifikácie. Ak príjemca uvádza toto ako dôvod odmietnutia, nie je to platné odmietnutie v rámci siete Peppol. Príjemca musí používať XML parser, ktorý správne spracúva prefixované aj predvolené namespacy.

PSB je pripravený na požiadavky ViDA (VAT in the Digital Age). Pri odoslaní faktúry PSB automaticky generuje príslušné CTC/DRR hlásenie a odosiela ho daňovému úradu. Pre integrátorov to neznamená žiadnu zmenu vo workflow: používate rovnaký endpoint a rovnaký formát ako doteraz.

Stavové správy o CTC reportovaní sú súčasťou štandardného webhook mechanizmu. PSB poskytuje dôkazové súbory (evidence files) pre každé hlásenie. CTC reportovanie je zahrnuté v cene dokumentu.

Chcete najprv otestovať, či je Váš dokument platný? Použite Validate API.

• Prijatie faktúry cez API
• Idempotency: prevencia duplicitných uploadov
• Nastavenie a zabezpečenie webhookov
• Formáty dokumentov: UBL, CII a ďalšie
• NLCIUS: holandský štandard e-fakturovania
• Štruktúra UBL faktúry
• Vytvorenie a odoslanie faktúry cez platformu
• Stavy faktúr na platforme
• E-faktúrovanie s eConnect