Odeslání objednávky

Pomocí PSB API můžete odesílat nákupní objednávky (purchase orders) Vašim dodavatelům přes síť Peppol. Proces funguje obdobně jako odesílání faktur: odešlete UBL Order XML dokument do API a PSB se postará o validaci, směrování a doručení.

Endpoint

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

Požadavek obsahuje UBL Order XML dokument jako tělo s content-type application/xml. {partyId} je Peppol identifikátor odesílající organizace (kupujícího).

Objednávkové profily

PSB podporuje dva Peppol profily pro objednávky:

Profil

ProfileID

Použití

Order Only

urn:fdc:peppol.eu:poacc:bis:order_only:3

Jednosměrná objednávka bez response

Advanced Ordering

urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3

Kompletní objednávkový proces s response, změnami a stornováním

U Order Only kupující odešle objednávku a proces je ukončen. U Advanced Ordering může dodavatel reagovat Order Response a kupující může objednávku později změnit nebo stornovat.

Tip: Použijte profil Advanced Ordering, pokud chcete, aby dodavatel objednávku potvrdil, nebo pokud chcete objednávky později upravovat.

Základní flow

Upload: odešlete UBL Order XML dokument na endpoint
Validace: PSB zvaliduje dokument vůči XSD schématu a business pravidlům
Směrování: PSB přes SML/SMP vyhledá, jak je příjemce dostupný
Doručení: dokument se doručí přes Peppol dodavateli
Aktualizace stavu: obdržíte webhook OrderSent se stavem doručení

Idempotency

Použijte hlavičku X-EConnect-DocumentId k zabránění duplicitnímu zpracování:

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

Pokud odešlete stejné documentId znovu, API vrátí 409 Conflict. Vždy používejte UUID/GUID, nikdy číslo objednávky.

Zpracování chyb

Při neúspěšném doručení PSB automaticky uplatní retries:

Maximálně 8 pokusů rozložených na přibližně 35 hodin
Pouze při 5xx server errors (dočasné chyby na straně příjemce)
Při každém pokusu se publikuje event OrderSentRetry
Při definitivním selhání obdržíte event OrderSentError

Chyba

Příčina

Řešení

Validační chyba (4xx)

Dokument nesplňuje Peppol standard

Zkontrolujte dokument pomocí Validate API

Příjemce nenalezen

Identifikátor není registrován v Peppol

Zkontrolujte přes queryRecipientParty, zda dodavatel může přijímat objednávky

409 Conflict

Dokument s tímto documentId byl již zpracován

Žádná akce není potřeba

Webhook topics

Nastavte webhooky pro následující topics ke sledování objednávkového procesu:

Topic

Kdy

OrderSent

Objednávka byla úspěšně doručena

OrderSentRetry

Doručení se opakuje

OrderSentError

Objednávku nebylo možné doručit

OrderResponseReceived

Dodavatel reagoval na objednávku

OrderChangeReceived

Změna objednávky byla přijata

OrderCancellationReceived

Stornování objednávky bylo přijato

Odpověď

Úspěšný upload vrátí 201 Created s ID dokumentu v PSB. Toto ID použijte pro sledování objednávky přes API nebo webhooky.

Často kladené otázky

Kdy zvolit Order Only a kdy Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) je jednosměrná objednávka bez dalšího toku zpráv. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) je potřeba, když dodavatel musí odpovědět pomocí Order Response nebo když chcete objednávky později změnit či zrušit. Zvolte Advanced, pokud potřebujete tento úplný proces.

Jak zabráním duplicitnímu zpracování při odesílání objednávky?

Odešlete hlavičku X-EConnect-DocumentId s jedinečným UUID nebo GUID. Pokud znovu použijete stejné documentId, API odpoví 409 Conflict. Nepoužívejte číslo objednávky jako klíč idempotence, protože není pro tento mechanismus určen.

Co se stane při dočasných chybách doručení a jaké webhooky dostanu?

Při 5xx chybách na straně příjemce se PSB automaticky pokusí o opětovné doručení (maximálně 8 pokusů během přibližně 35 hodin). Uvidíte OrderSentRetry při každém pokusu a OrderSentError při trvalém selhání. Při úspěchu dostanete OrderSent.

Podívejte se na kompletní API specifikaci na psb.econnect.eu pro všechny parametry a vzorové payloady.

Vyzkoušejte to v API

Související