Odeslání e-faktury přes API PSB je nejpoužívanější endpoint. Odešlete XML dokument v libovolném podporovaném formátu (UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X/ZUGFeRD a další) a PSB se postará o automatickou detekci formátu, validaci, routing a doručení přes příslušnou síť.

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

{partyId} v URL je Peppol identifikátor odesílající organizace (dodavatele). Požadavek obsahuje XML dokument jako 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 další) a validuje dokument vůči příslušným pravidlům.

1. Upload: odešlete XML dokument na endpoint
2. Validace: PSB validuje dokument vůči XSD schématu a obchodním pravidlům
3. Routing: PSB vyhledá přes SML/SMP, jak dosáhnout příjemce
4. Doručení: dokument je doručen přes příslušný kanál (Peppol, e-mail nebo jiná síť)
5. Aktualizace stavu: obdržíte webhook notifikaci se stavem doručení

Důležité: PSB určuje příjemce na základě EndpointID ve Vašem XML dokumentu. Pokud tento element chybí nebo obsahuje nesprávný identifikátor, odeslání selže se stavem InvoiceSentError. Ujistěte se, že Váš zdrojový systém správně vyplňuje EndpointID. Více o identifikátorech a routingu najdete v článku o Peppol identifikátorech.

PSB podporuje idempotency přes header požadavku X-EConnect-DocumentId. Zahrnutím vlastního UUID u každého upload požadavku se zabrání duplicitnímu zpracování:

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

Pokud odešlete stejný documentId znovu, API vrátí 409 Conflict a odesílatel ví, že dokument již byl zpracován.

Důležité: Vždy používejte UUID/GUID jako documentId. Nikdy nepoužívejte číslo faktury, protože to způsobuje problémy při opětovném odeslání opravené verze téže faktury.

Před odesláním faktury můžete přes queryRecipientParty zkontrolovat, zda a jak je příjemce dostupný:

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

V těle požadavku předáváte seznam identifikátorů, například ["0106:12345678"], nebo objekt s partyIds a metaAttributes. Volitelné dotazové parametry jsou ?preferredDocumentTypeId a ?includeOptions.

Odpověď obsahuje informace o:

• Zda je příjemce registrován na Peppol
• Jaké typy dokumentů příjemce může přijímat
• Přes jaký Access Point je příjemce dostupný
• Jaký kanál PSB použije pro doručení

Pro pokročilé vyhledávání včetně URL Access Pointu a certifikátu AP je k dispozici samostatná cesta:

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

Při neúspěšném doručení PSB automaticky uplatňuje mechanismus opakování:

• Maximálně 8 pokusů rozložených na přibližně 35 hodin
• Pouze u chyb serveru 5xx (dočasné chyby na straně příjemce)
• U každého pokusu se publikuje událost InvoiceSentRetry
• Při definitivním selhání obdržíte událost InvoiceSentError přes Váš webhook

Časté chyby při odesílání:

Poznámka: SI-UBL 1.2 (Simpler Invoicing 1.2) není povolen na síti Peppol od 1. ledna 2024. Faktury v tomto formátu vedou k InvoiceSentError. Používejte NLCIUS (SI-UBL 2.0) nebo Peppol BIS Billing V3. Zkontrolujte CustomizationID ve Vašem XML dokumentu, pokud narazíte na tuto chybu.

Úspěšný upload vrátí 200 OK s identifikátorem dokumentu v PSB. Tento identifikátor použijte ke sledování stavu dokumentu přes API nebo přes webhooky.

Na rozdíl od purchaseInvoice endpoint salesInvoice nemá DELETE. Jde o záměrnou volbu, protože odeslaná nebo odmítnutá prodejní faktura je událost významná pro audit: dokument zůstává dohledatelný v auditní stopě i poté, co odeslání selhalo.

Zákazníci se někdy ptá, zda lze odmítnutou prodejní fakturu zastavit nebo smazat, například poté, co fakturu interně již dobropisovali. Odpověď zní:

• Chyba validace (4xx, například Invalid payload): PSB umístí dokument do konečného stavu InvoiceSentError. Žádné opakování se neprovádí (opakují se pouze chyby 5xx). Dokument není dodatečně doručen příjemci. Na PSB není potřeba žádná akce; dokument je v konečném stavu a uchovává se 90 dní pro účely auditu.
• Žádný DELETE endpoint není potřeba: protože dokument již není aktivní a neopakuje se, nemusí být explicitně mazaný pro zastavení odeslání.
• Poslat opravu pomocí nového dokumentu: pokud byla původní faktura nesprávná a již byla (částečně) doručena, použijte dobropis nebo opravnou fakturu podle standardního účetního postupu. Původní documentId zůstává jako reference v auditní stopě.

Tento rozdíl v životním cyklu mezi salesInvoice (bez DELETE) a purchaseInvoice (s DELETE) vyplývá z role: odchozí faktura je obchodní úkon zaznamenaný odesílatelem, který musí být právně dohledatelný; příchozí faktura může být po úspěšném stažení odstraněna z vlastního systému příjemce.

Standardně PSB automaticky vybírá nejlepší kanál. S parametrem dotazu ?channel={hookId} můžete vynutit konkrétní kanál doručení (např. konkrétní síť nebo e-mailový fallback).

Přílohy (PDF, obrázky) se mohou vložit jako base64 do UBL dokumentu jako AdditionalDocumentReference. PSB zpracovává vložené přílohy správně a doručuje je společně s fakturou.

Poznámka: Endpoint odesílání přijímá maximálně 24 MB na požadavek (včetně HTTP overheadu). U příloh kódovaných v base64 payload naroste o přibližně 33%, takže 18 MB PDF vede k požadavku o velikosti přibližně 24 MB. Payloady přesahující limit jsou odmítnuty webovým serverem s HTTP 500 (nikoli 413), ještě před aplikační validací. Zmenšete velké přílohy nebo je odešlete přes samostatný kanál.

Tip: Aktuální standard Peppol BIS Billing 3.0 podporuje maximálně jednu OrderReference na fakturu. Pokud se faktura vztahuje na více objednávek, musí se odeslat více faktur.

Tip: Někteří příjemci hlásí chyby u faktur s XML namespace prefixem (např. <urn:Invoice> místo <Invoice>). Obě formy jsou technicky správný XML podle W3C specifikace. Pokud příjemce uvádí toto jako důvod odmítnutí, nejedná se o platné odmítnutí v rámci sítě Peppol. Příjemce musí používat XML parser, který správně zpracovává prefixované i výchozí namespacey.

PSB je připraven na požadavky ViDA (VAT in the Digital Age). Při odeslání faktury PSB automaticky generuje příslušné CTC/DRR hlášení a odesílá ho finančnímu úřadu. Pro integrátory to neznamená žádnou změnu ve workflow: používáte stejný endpoint a stejný formát jako dosud.

Stavové zprávy o CTC reportování jsou součástí standardního webhook mechanismu. PSB poskytuje důkazové soubory (evidence files) pro každé hlášení. CTC reportování je zahrnuto v ceně dokumentu.

Chcete nejprve otestovat, zda je Váš dokument platný? Použijte Validate API.

• Přijetí faktury přes API
• Idempotency: prevence duplicitních uploadů
• Nastavení a zabezpečení webhooků
• Formáty dokumentů: UBL, CII a další
• NLCIUS: nizozemský standard e-fakturace
• Struktura UBL faktury
• Vytvoření a odeslání faktury přes platformu
• Stavy faktur na platformě
• E-fakturace s eConnect