/ docs
ProduktZnalostiVývojári
Platforma Control
Odoslanie objednávky cez API

Odoslanie UBL objednávky cez PSB API: endpoint, profily, idempotency a sledovanie stavu.

Pomocou PSB API môžete odosielať nákupné objednávky (purchase orders) Vašim dodávateľom cez sieť Peppol. Proces funguje obdobne ako odosielanie faktúr: odošlete UBL Order XML dokument do API a PSB sa postará o validáciu, smerovanie a doručenie.

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

Požiadavka obsahuje UBL Order XML dokument ako telo s content-type application/xml. {partyId} je Peppol identifikátor odosielajúcej organizácie (kupujúceho).

Objednávkové profily

PSB podporuje dva Peppol profily pre objednávky:

ProfilProfileIDPoužitieOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Jednosmerná objednávka bez responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Kompletný objednávkový proces s response, zmenami a stornovaním

Pri Order Only kupujúci odošle objednávku a proces je ukončený. Pri Advanced Ordering môže dodávateľ reagovať Order Response a kupujúci môže objednávku neskôr zmeniť alebo stornovať.

Tip: Použite profil Advanced Ordering, ak chcete, aby dodávateľ objednávku potvrdil, alebo ak chcete objednávky neskôr upravovať.

Základný flow
  1. Upload: odošlite UBL Order XML dokument na endpoint
  2. Validácia: PSB zvaliduje dokument voči XSD schéme a business pravidlám
  3. Smerovanie: PSB cez SML/SMP vyhľadá, ako je príjemca dostupný
  4. Doručenie: dokument sa doručí cez Peppol dodávateľovi
  5. Aktualizácia stavu: obdržíte webhook OrderSent so stavom doručenia
Idempotency

Použite hlavičku X-EConnect-DocumentId na zabránenie duplicitnému spracovaniu:

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

Ak odošlete rovnaké documentId znovu, API vráti 409 Conflict. Vždy používajte UUID/GUID, nikdy číslo objednávky.

Spracovanie chýb

Pri neúspešnom doručení PSB automaticky uplatní retries:

  • Maximálne 8 pokusov rozložených na približne 35 hodín
  • Len pri 5xx server errors (dočasné chyby na strane príjemcu)
  • Pri každom pokuse sa publikuje event OrderSentRetry
  • Pri definitívnom zlyhaní obdržíte event OrderSentError
ChybaPríčinaRiešenieValidačná chyba (4xx)Dokument nespĺňa Peppol štandardSkontrolujte dokument pomocou Validate APIPríjemca nenájdenýIdentifikátor nie je registrovaný v PeppolSkontrolujte cez queryRecipientParty, či dodávateľ môže prijímať objednávky409 ConflictDokument s týmto documentId bol už spracovanýŽiadna akcia nie je potrebná
Webhook topics

Nastavte webhooky pre nasledujúce topics na sledovanie objednávkového procesu:

TopicKedyOrderSentObjednávka bola úspešne doručenáOrderSentRetryDoručenie sa opakujeOrderSentErrorObjednávku nebolo možné doručiťOrderResponseReceivedDodávateľ reagoval na objednávkuOrderChangeReceivedZmena objednávky bola prijatáOrderCancellationReceivedStornovanie objednávky bolo prijaté
Odpoveď

Úspešný upload vráti 201 Created s ID dokumentu v PSB. Toto ID použite na sledovanie objednávky cez API alebo webhooky.

Často kladené otázky
Kedy zvoliť Order Only a kedy Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) je jednosmerná objednávka bez ďalšieho toku správ. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) je potrebný, keď dodávateľ musí odpovedať pomocou Order Response alebo keď chcete objednávky neskôr zmeniť alebo zrušiť. Zvoľte Advanced, ak potrebujete tento úplný proces.

Ako zabránim duplicitnému spracovaniu pri odosielaní objednávky?

Odošlite hlavičku X-EConnect-DocumentId s jedinečným UUID alebo GUID. Ak znova použijete rovnaké documentId, API odpovie 409 Conflict. Nepoužívajte číslo objednávky ako kľúč idempotentnosti, pretože nie je na tento mechanizmus určený.

Čo sa stane pri dočasných chybách doručenia a aké webhooky dostanem?

Pri 5xx chybách na strane príjemcu sa PSB automaticky pokúsi o opätovné doručenie (maximálne 8 pokusov počas približne 35 hodín). Uvidíte OrderSentRetry pri každom pokuse a OrderSentError pri trvalom zlyhaní. Pri úspechu dostanete OrderSent.

Pozrite si kompletnú API špecifikáciu na psb.econnect.eu pre všetky parametre a vzorové payloady.

Vyskúšajte to v API

Súvisiace
PreviousPrijatie self-billingu
NextPrijatie objednávky