Zhoda so špecifikáciou UCP
Ktoré časti UCP 2026-04-08 Monokaido implementuje, ktoré nie a čo z toho vyplýva pre integráciu.
Na tejto stránke
- Čo obchod zverejňuje
- Schopnosti, rozšírenia a transporty
- Pravidlá protokolu
- Objavenie a profil obchodu
- Profil platformy a vyjednávanie
- Transport
- Overovanie, podpisy a identita
- Checkout a jeho dokončenie
- Košík
- Katalóg
- Rozšírenie fulfillment
- Rozšírenie discount
- Schopnosť objednávok a webhooky
- Idempotencia
- Chyby a správy
- Kde je špecifikácia nejednoznačná
- Nad rámec špecifikácie
- Ako sa oznamujú zmeny
Monokaido implementuje Universal Commerce Protocol vo verzii 2026-04-08 —
iba v tejto verzii — cez REST. Táto kapitola porovnáva implementáciu so
špecifikáciou tejto verzie pravidlo po pravidle a pri každom uvádza, čo
Monokaido robí a čo s tým má robiť váš klient.
Porovnanie vychádza zo stránok špecifikácie na
ucp.dev/2026-04-08 a z
oficiálnej REST schémy (rest.openapi.json) v podobe zverejnenej 26. októbra
2026. Čo kapitola hovorí o Monokaide, je správanie nasadeného kódu;
v súvislostiach ho vysvetľuje kapitola
Princípy a životný cyklus.
| Stav | Význam |
|---|---|
| Podporované | Implementované tak, ako to opisuje špecifikácia. |
| Čiastočne | Implementované v užšom rozsahu alebo s iným výkladom; riadok uvádza presne ako. |
| Nepodporované | Neimplementované. Nespoliehajte sa na to. |
| Neuplatňuje sa | Pravidlo sa na túto implementáciu nemôže vzťahovať. |
Čo obchod zverejňuje
Každá vlastná doména, ktorá poskytuje UCP, odpovedá na GET /.well-known/ucp
profilom uvedeným nižšie. Obchody sa líšia iba v dvoch veciach. Prvou je
hostiteľ, tu zapísaný ako <hostiteľ obchodu>: primárna doména obchodu, ak
táto doména poskytuje UCP, inak doména, na ktorú prišla požiadavka; rovnakého
hostiteľa používajú aj continue_url a order.permalink_url. Druhou je
katalógový režim: obchod v katalógovom režime uvádza iba dve schopnosti
katalógu.
| Schopnosť | version | spec | schema | extends | Uvádza sa |
|---|---|---|---|---|---|
dev.ucp.shopping.catalog.search | 2026-04-08 | https://ucp.dev/2026-04-08/specification/catalog/search | https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json | — | vždy |
dev.ucp.shopping.catalog.lookup | 2026-04-08 | https://ucp.dev/2026-04-08/specification/catalog/lookup | https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json | — | vždy |
dev.ucp.shopping.cart | 2026-04-08 | https://ucp.dev/2026-04-08/specification/cart | https://ucp.dev/2026-04-08/schemas/shopping/cart.json | — | mimo katalógového režimu |
dev.ucp.shopping.checkout | 2026-04-08 | https://ucp.dev/2026-04-08/specification/checkout | https://ucp.dev/2026-04-08/schemas/shopping/checkout.json | — | mimo katalógového režimu |
dev.ucp.shopping.fulfillment | 2026-04-08 | https://ucp.dev/2026-04-08/specification/fulfillment | https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json | "dev.ucp.shopping.checkout" | mimo katalógového režimu |
dev.ucp.shopping.discount | 2026-04-08 | https://ucp.dev/2026-04-08/specification/discount | https://ucp.dev/2026-04-08/schemas/shopping/discount.json | ["dev.ucp.shopping.checkout", "dev.ucp.shopping.cart"] | mimo katalógového režimu |
| Kľúč profilu | Hodnota |
|---|---|
ucp.version | "2026-04-08" |
ucp.services | jeden kľúč dev.ucp.shopping s jednou položkou: transport: "rest", endpoint: "https://<hostiteľ obchodu>/ucp/v1", version: "2026-04-08", spec: "https://ucp.dev/2026-04-08/specification/overview", schema: "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json" |
ucp.payment_handlers | {} |
ucp.supported_versions | chýba |
signing_keys, keys | chýbajú |
Všetky adresy spec a schema sú na https://ucp.dev/, teda na pôvode, ku
ktorému špecifikácia viaže menný priestor dev.ucp.*.
| Operácia | Koreňová schopnosť |
|---|---|
POST /ucp/v1/catalog/search | dev.ucp.shopping.catalog.search |
POST /ucp/v1/catalog/lookup, POST /ucp/v1/catalog/product | dev.ucp.shopping.catalog.lookup |
každá cesta /ucp/v1/carts | dev.ucp.shopping.cart |
každá cesta /ucp/v1/checkout-sessions | dev.ucp.shopping.checkout |
Schopnosti, rozšírenia a transporty
| Položka špecifikácie | Stav | Čo to znamená pre vás |
|---|---|---|
dev.ucp.shopping.catalog.search | Čiastočne | Textové vyhľadávanie v názve produktu (v jazyku odpovede) a vo vlastných kódoch produktov obchodu — zhoda podreťazca, ktorá ignoruje veľkosť písmen, ale nie diakritiku —, s voliteľným cenovým filtrom. Neprázdne filters.categories sa odmietne s 400, ostatné filtre sa ignorujú. Výsledky idú od najnovších, bez zoradenia podľa relevancie. Dopyt nehľadá v SKU ani GTIN variantu: lookup nájde variant podľa SKU, podľa GTIN ho nenájde nič. |
dev.ucp.shopping.catalog.lookup | Čiastočne | catalog/lookup prijme až 20 identifikátorov (id variantu, SKU variantu, id produktu alebo handle); catalog/product prečíta jeden produkt podľa id produktu, id variantu alebo handle, s výberom možností. preferences sa ignoruje: výber, ktorému nezodpovedá žiadny variant, sa uvoľňuje od konca selected. |
dev.ucp.shopping.cart | Čiastočne | Zmena ponechá polia, ktoré vynechá, a checkout vytvorený z košíka svoje zmeny do košíka nepremietne (pozri Košík). Obchod v katalógovom režime túto schopnosť neuvádza; volania košíka tam odpovedajú 200 s capabilities_incompatible. |
dev.ucp.shopping.checkout | Čiastočne | Checkout sa cez API nikdy nedokončí: pripravený checkout má stav requires_escalation a kupujúci nákup dokončí v obchode cez continue_url. |
dev.ucp.shopping.fulfillment | Čiastočne | Jeden spôsob doručenia s jednou skupinou možností. Typ pickup ani delené zásielky nie sú k dispozícii. |
dev.ucp.shopping.discount | Čiastočne | V relácii sa uplatní jeden kód; ďalšie dostanú discount_code_combination_disallowed. Bez vyjednaného rozšírenia sa žiadny kód nečíta ani neuplatní. |
dev.ucp.shopping.order | Nepodporované | Žiadne GET /orders/{id} ani webhooky objednávok. Stav completed a order zisťujte čítaním GET /ucp/v1/checkout-sessions/{id}. |
dev.ucp.common.identity_linking | Nepodporované | Každá relácia je anonymná. Kupujúci prihlásený v obchode v karte prehliadača, v ktorej otvorí continue_url, dostane položky do zákazníckeho košíka. |
dev.ucp.shopping.ap2_mandate | Nepodporované | Žiadna autonómna platba: kupujúci nákup vždy dokončí v obchode. |
dev.ucp.shopping.buyer_consent | Nepodporované | Právne odkazy obchodu prichádzajú v links[] checkoutu; súhlas kupujúci udelí v obchode. |
dev.ucp.common.loyalty | Nepodporované | — |
dev.ucp.shopping.permalink | Nepodporované | Použite continue_url. |
| Platobné metódy (payment handlers) | Nepodporované | payment_handlers je vždy {}. Kupujúci platí v pokladni obchodu, spôsobmi platby obchodu. |
Signály (dev.ucp.buyer_ip, dev.ucp.user_agent) a attribution | Nepodporované | Prijmú sa a ignorujú, ako každé pole, ktoré API nepoužíva. Žiadna správa signal si ich nikdy nevyžiada. |
Transport rest | Podporované | Jediný transport. |
Transporty mcp, a2a, embedded | Nepodporované | Profil uvádza jedinú službu REST. continue_url je celá stránka, ktorá sa odmietne zobraziť v rámci (frame), nie vložiteľná pokladňa. |
Pravidlá protokolu
Prvý stĺpec pomenúva pravidlo a v zátvorke stránku špecifikácie, z ktorej pochádza.
Objavenie a profil obchodu
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
Profil je na /.well-known/ucp, cez HTTPS a nepresmerováva (overview) | Podporované | Poskytuje ho každá vlastná doména, ktorá poskytuje UCP. Presmeruje sa (301) iba obyčajné http:// na https://. | Načítajte rovno adresu https://. |
Cache-Control je public s max-age aspoň 60, nikdy private, no-store ani no-cache (overview) | Podporované | public, max-age=300 | Profil držte v cache najviac päť minút. |
version, services a payment_handlers sú prítomné, registre aj keď sú prázdne (overview) | Podporované | payment_handlers je zámerne {}. | — |
signing_keys (nepovinné) (overview) | Nepodporované | Nezverejňujú sa: Monokaido neposiela webhooky a nič nepodpisuje. | Odpovede sa nedajú overiť podpisom. |
supported_versions pre staršie verzie, ktoré obchod podporuje (overview) | Neuplatňuje sa | Monokaido podporuje jedinú verziu, takže niet staršej, ktorú by uviedlo. | — |
Profil platformy a vyjednávanie
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
Platforma posiela pri každej požiadavke UCP-Agent: profile="…", slovník podľa RFC 8941 (overview, REST väzba) | Podporované | Číta sa pri každom volaní /ucp/v1 parserom pre podmnožinu, ktorú UCP používa: kľúče malými písmenami, profile ako reťazec v úvodzovkách, ostatné členy a parametre sa ignorujú, platí posledný profile. Chýbajúca hlavička, hlavička bez profile v úvodzovkách alebo hlavička, ktorá sa nedá rozobrať ako celok, vedie k 400 invalid_profile_url. | Posielajte presne profile="https://…". |
Adresa profilu ukazuje na /.well-known/ucp (REST väzba) | Čiastočne | Nevynucuje sa: prijme sa každá adresa https:// s najviac 1000 znakmi bez medzier a prihlasovacích údajov, s akýmkoľvek portom, cestou a query. | Napriek tomu ho hostujte na /.well-known/ucp. |
| Obchod profil platformy stiahne a overí, ak ho nemá v cache (overview) | Podporované | GET bez presmerovaní, iba 200, najviac 256 KiB, 5 s, iba verejné adresy. V cache sa drží podľa max-age profilu, s obmedzením na 60 s až 1 h (bez neho 5 min; no-store, no-cache a private sa ignorujú), počas obnovy sa ešte najviac hodinu používa stará kópia; zlyhania sa pamätajú 60 s. Za minútu sa stiahne najviac 5 profilov, ktoré ešte nie sú v cache, na klienta (adresu IPv4 alebo sieť IPv6 /64) a spolu 60 na jeden serverový proces API; nad tento počet 503 s Retry-After. Overujú sa iba ucp.version a ucp.capabilities. | Poskytujte ho rýchlo s Cache-Control: public, max-age=3600. Nič ďalšie vo vašom profile sa nekontroluje. |
| Prienik: rovnaký názov, najvyššia spoločná verzia, orezanie rozšírení bez aktívneho rodiča, opakovane (overview) | Podporované | Rodičia pochádzajú z deklarácie obchodu; rozšírenie s viacerými rodičmi zostane, kým je aktívny aspoň jeden. Vaše vlastné extends sa ignoruje. Obchod uvádza každú schopnosť iba vo verzii 2026-04-08, takže schopnosť, ktorú váš profil uvádza len v iných verziách, nie je aktívna. | Pre fulfillment uveďte checkout; pre discount košík alebo checkout. |
ucp v odpovedi uvádza verziu a schopnosti aktívne pre operáciu: checkout s discount a fulfillment, košík s discount (overview) | Podporované | capabilities obsahuje koreňovú schopnosť a každé jej vyjednané rozšírenie. | Skôr než sa spoľahnete na polia rozšírenia, overte ho tam. |
Kontrola pri požiadavke: version platformy musí byť verziou obchodu alebo kľúčom jeho supported_versions, inak version_unsupported (overview) | Podporované | Akákoľvek verzia okrem 2026-04-08 sa odmietne s 422 version_unsupported. | Uveďte 2026-04-08. |
| Obchod by mal obslúžiť požiadavky platforiem s jeho verziou alebo staršou (overview) | Nepodporované | Staršie zverejnené verzie, napríklad 2026-01-23, sa odmietnu ako každá iná. | — |
Chyby vyjednávania a ich stav HTTP: invalid_profile_url 400, profile_unreachable 424, profile_malformed 422, version_unsupported 422, capabilities_incompatible 200 (overview) | Podporované | Každá nesie continue_url na úvodnú stránku obchodu. capabilities_incompatible je obchodná odpoveď 200 s ucp.status: "error". | capabilities_incompatible berte ako konečný výsledok pre danú operáciu v danom obchode, kým sa jeho profil nezmení. |
Transport
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
| HTTPS s TLS najmenej 1.3 (REST väzba) | Čiastočne | Prijíma sa TLS 1.2 aj TLS 1.3. | Ak vaše pravidlá vyžadujú TLS 1.3, vynúťte ho v klientovi; obchod ho ponúka. |
JSON s Content-Type: application/json (overview) | Podporované | Každá odpoveď /ucp/v1 je JSON. Stránka continue_url je zámerne HTML: je určená prehliadaču kupujúceho. | Posielajte Content-Type: application/json v UTF-8. |
Hlavička Request-Id, v tabuľke hlavičiek REST aj v oficiálnej schéme označená ako povinná pri každej operácii (REST väzba) | Nepodporované | Nečíta sa ani nevracia. Žiadny identifikátor požiadavky sa nevracia. | Poslať ju neuškodí; zaznamenávajte si vlastný korelačný identifikátor. |
Hlavička Idempotency-Key, v tabuľke hlavičiek REST označená ako povinná, v oficiálnej schéme pri každom zápise (REST väzba) | Čiastočne | Nepovinná; pozri Idempotenciu. | Posielajte ju pri každom zápise. |
Overovanie, podpisy a identita
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
| Obchody by mali overovať platformy — API kľúčom, tokenom OAuth, vzájomným TLS alebo podpismi HTTP správ (overview, REST väzba) | Nepodporované | API je otvorené, čo je možnosť „Open API“, ktorú REST väzba uvádza. Obchod sa určí podľa hlavičky Host; jediným prístupovým údajom k relácii je jej id. Prístupové údaje, ktoré pošlete, sa ignorujú. | Id relácií držte v tajnosti. Nepredpokladajte, že iný volajúci, ktorý id pozná, sa k relácii nedostane. |
Podpisovanie požiadaviek (RFC 9421 Signature, Signature-Input, Content-Digest) a podpísané odpovede (overview, signatures) | Nepodporované | Poslané podpisy sa ignorujú; nič sa nepodpisuje. | — |
Chyby podpisov a dôvery signature_missing, signature_invalid, key_not_found, digest_mismatch, algorithm_unsupported, profile_not_trusted (overview, signatures) | Nepodporované | Nikdy sa neposielajú. | — |
Prepojenie identity (OAuth 2.0) a rozsahy dev.ucp.shopping.checkout:manage, dev.ucp.shopping.cart:manage (identity linking, checkout, cart) | Nepodporované | Relácie sú reláciami hosťa. Kupujúci sa prípadne prihlási v obchode. | — |
Checkout a jeho dokončenie
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
payment_handlers v ucp checkoutu (checkout) | Podporované | {} v každej odpovedi checkoutu, ktorá nie je chybou. | — |
| Zmena je úplná náhrada: platforma posiela celý checkout (checkout) | Čiastočne | line_items, ak sú poslané, nahradia všetky položky, a poslaný buyer alebo context nahradí uložený celý (null ho vymaže). Pole, ktoré požiadavka vynechá, si ponechá uloženú hodnotu a nevymaže sa: zľavové kódy vymaže discounts.codes: [] a adresa doručenia zostane, kým nepríde iná. | Pri každej zmene posielajte celý zdroj, ako to žiada špecifikácia. |
Dokončenie checkoutu vytvorí objednávku a vráti checkout s order (checkout) | Nepodporované | POST …/complete odpovie checkoutom v aktuálnom stave. Platobné údaje v tele sa ignorujú. | Od complete nikdy nečakajte objednávku. Odovzdajte kupujúcemu continue_url a potom čítajte GET. |
Stavy incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled (checkout) | Čiastočne | Používajú sa štyri. Akákoľvek chyba recoverable → incomplete; žiadna → requires_escalation s payment_required. completed až vtedy, keď kupujúci otvoril continue_url checkoutu (alebo košíka, z ktorého vznikol) a potom v obchode objednal z košíka, ktorý odovzdanie naplnilo, aspoň jednu z položiek checkoutu. ready_for_complete ani complete_in_progress sa nikdy neobjavia. | requires_escalation chápte ako „pripravené: odovzdajte“. |
requires_escalation nesie continue_url a aspoň jednu správu, ktorá potrebuje kupujúceho (checkout) | Podporované | Vždy payment_required so závažnosťou requires_buyer_input, navyše pickup_point_required, ak zvolený spôsob potrebuje výdajné miesto. | continue_url je odkaz pre prehliadač kupujúceho, nie pre váš server. |
continue_url v každej odpovedi, ktorá nie je konečná, v konečných chýba, vždy absolútne HTTPS (checkout) | Podporované | V každej odpovedi košíka a otvoreného checkoutu; v checkoute completed a canceled chýba. | — |
Potvrdenie objednávky order: {id, label?, permalink_url} (checkout) | Podporované | id je UUID objednávky, label jej číslo, permalink_url stránka potvrdenia obchodu, ktorá nevyžaduje prihlásenie. Zvyšok tela je posledná ponuka, nie objednávka. | Súčty ponuky nevydávajte za súčty objednávky. |
| Dokončený checkout sa už nemení (checkout) | Podporované | Zápisy sú podmienené revíziou (compare-and-set); dokončený checkout nič znova neotvorí. Zmena dokončeného alebo zrušeného checkoutu ho vráti nezmenený so správou checkout_completed alebo checkout_canceled. | — |
| Zrušenie dokončeného alebo zrušeného checkoutu sa odmietne (checkout) | Podporované | Odpoveď je 200 so zdrojom a správou checkout_completed alebo checkout_canceled (unrecoverable); ucp.status chýba. Objednávka sa cez UCP nikdy nezruší. | Čítajte správu, nielen stav HTTP. |
| Po dokončení checkoutu pošle obchod potvrdzujúci e-mail (checkout) | Čiastočne | Na adresu, ktorú kupujúci zadal v pokladni obchodu, príde vlastný e-mail obchodu s potvrdením objednávky, rovnaký ako pri každej objednávke z jeho pokladne. Obchodník, ktorý si transakčné e-maily vypol, nepošle žiadny. | — |
expires_at podľa RFC 3339; 6 hodín, ak ho obchod nenastaví (checkout) | Podporované | Nastaví sa vždy. Košík platí 7 dní, checkout 24 hodín od posledného vytvorenia alebo zmeny; čítanie platnosť nepredĺži. | Čítajte expires_at; nepočítajte so 6 hodinami. |
links[] s právnymi odkazmi (checkout) | Čiastočne | Zo súhlasov v pokladni obchodu, ktoré majú odkaz: type je privacy_policy, ak súhlas vyzerá ako zásady ochrany osobných údajov, inak terms_of_service, najviac 10, odkazy začínajúce / sa doplnia na absolútne s hostiteľom obchodu. refund_policy, shipping_policy ani faq sa nikdy nepoužijú. [], ak obchod žiadny súhlas s odkazom nemá. | Pred odovzdaním ich ukážte kupujúcemu. |
context: address_country, address_region, postal_code, intent, language, currency, eligibility, payment (checkout) | Čiastočne | context.language určí jazyk a tým aj menu cien. context.currency iba určuje menu filters.price v požiadavkách katalógu; menu cien nikdy nezmení. address_country, address_region a postal_code sa skontrolujú, uložia a vrátia v košíkoch a checkoutoch, no nezmenia ceny ani možnosti doručenia: to robí adresa doručenia. intent, eligibility a payment sa ignorujú, bez upozornenia eligibility_not_accepted, ktoré špecifikácia odporúča. | Menu volte cez jazyk; pre možnosti doručenia pošlite adresu doručenia. |
Košík
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
POST /carts, GET a PUT /carts/{id}, POST /carts/{id}/cancel (cart) | Podporované | — | — |
Vytvorenie odpovie 201 Created (oficiálna REST schéma) | Podporované | 201 pre nový košík alebo checkout. 200, keď prevod vráti otvorený checkout košíka, a pri obchodných chybách, na ktoré REST väzba odpovedá 200. | — |
| Zmena je úplná náhrada: platforma posiela celý košík (cart) | Čiastočne | line_items sú povinné pri každej zmene (bez nich 400) a nahradia všetky položky. Poslaný buyer alebo context nahradí uložený celý (null ho vymaže); buyer, context a discounts, ktoré požiadavka vynechá, si ponechajú uloženú hodnotu a discounts.codes: [] vymaže kódy. | Pri každej zmene posielajte celý zdroj. |
Čítanie košíka odpovie not_found pre košík, ktorý neexistuje, vypršal alebo bol zrušený (cart) | Podporované | Ako obchodná odpoveď HTTP 200 s ucp.status: "error", nikdy 404. | — |
Zrušenie košíka vráti košík v stave, v akom bol; ďalšie operácie by mali odpovedať not_found (cart) | Podporované | Na každé ďalšie volanie košíka obchod odpovie not_found. Odpoveď na zrušenie ešte nesie continue_url košíka, ktoré už nefunguje. | — |
Košík poskytuje continue_url a odhadované súčty a môže mať expires_at (cart) | Podporované | continue_url košíka otvorí stránku košíka obchodu, alebo jeho pokladňu, ak z košíka vznikol otvorený checkout: odovzdá sa potom tento checkout. Súčty košíka neobsahujú dopravu. | — |
Z košíka checkout cez cart_id: obsah košíka, prekrývajúce sa polia checkoutu sa ignorujú, existujúci nedokončený checkout sa vráti (cart) | Čiastočne | cart_id sa číta, iba ak je vyjednaná schopnosť košíka, ako to hovorí špecifikácia; inak je požiadavka obyčajným vytvorením a potrebuje line_items. Položky, kupujúci, kontext a jazyk pochádzajú z košíka; line_items, buyer a context z požiadavky sa ignorujú. Zľavové kódy z požiadavky, ak sú poslané, nahradia kódy košíka. Otvorený checkout košíka sa vráti (200) a z požiadavky sa naň nič nepoužije; vypršaný sa zruší a vznikne nový. Košík, ktorý si kupujúci už odniesol do obchodu, sa odmietne s handed_off. | Ak chcete ponechať kódy košíka, pošlite cart_id bez discounts; checkout meňte cez PUT. |
| Zľavové kódy košíka sa prenesú do checkoutu (discount) | Čiastočne | Iba ak požiadavka na prevod žiadne kódy neposiela. | Ako vyššie. |
| Zmeny počas checkoutu sa premietnu späť do košíka (odporúčané) (cart) | Nepodporované | Checkout dostane vlastnú kópiu položiek; košík zostane nezmenený. | Po prevode pracujte iba s checkoutom. |
Katalóg
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
POST /catalog/search, /catalog/lookup a /catalog/product; pri lookup obe cesty lookup aj product (REST väzba katalógu) | Podporované | — | — |
Vyhľadávanie nesie aspoň jeden vstup (query, filtre) a obchod to overí (catalog search) | Čiastočne | Nevynucuje sa: vyhľadávanie bez query a filtrov vypíše celý katalóg od najnovších. | Vždy pošlite query alebo filters.price. |
| Stránkovanie kurzorom, predvolene 10 na stránku (REST väzba katalógu) | Podporované | Najviac 20 na stránku; väčší limit sa bez chyby zníži. Kurzor nesie iba číslo stránky. Stránka môže byť kratšia alebo aj prázdna, hoci has_next_page je true. | S každým kurzorom posielajte ten istý dopyt, filtre, limit aj kontext; riaďte sa has_next_page, nie veľkosťou stránky. |
Lookup odpovie 200; neznáme identifikátory znamenajú menej produktov, voliteľne info not_found (REST väzba katalógu) | Podporované | Jedna informačná správa not_found na každý identifikátor bez zhody. | — |
Priveľa identifikátorov v dávke → 400 request_too_large (catalog lookup, REST väzba katalógu) | Podporované | Viac ako 20 identifikátorov. Pri ostatných limitoch (100 položiek, 10 zľavových kódov) obchod odpovie 400 invalid_request. | — |
Nenájdený produkt → 200, ucp.status: "error", not_found unrecoverable (REST väzba katalógu) | Podporované | S continue_url na úvodnú stránku obchodu. | — |
filters.categories (catalog search) | Nepodporované | Neprázdny zoznam sa odmietne s 400 invalid_request. | Hľadajte cez query a filters.price. |
Rozšírenie fulfillment
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
methods[] typu shipping alebo pickup s cieľmi doručenia, skupinami, možnosťami a selected_option_id (fulfillment) | Čiastočne | Jeden spôsob, type: "shipping", s jednou skupinou, ktorej možnosti sú spôsoby dopravy obchodu, aj keď váš profil uvádza supports_multi_group. Z požiadavky sa číta prvý spôsob doručenia: jeho vybraný (inak prvý) cieľ a selected_option_id prvej skupiny. Vlastné id cieľa sa vráti ako "destination". Možnosti nesú id, title, prípadne description a totals. Spôsob, ktorý potrebuje výdajné miesto, pridá pickup_point_required: miesto si kupujúci vyberie v obchode. | Posielajte jeden spôsob doručenia s jedným cieľom; výdajné miesta nechajte na obchod. |
Rozšírenie discount
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
discounts.codes nahradí uložené kódy, [] ich vymaže; discounts.applied; odmietnuté kódy ako upozornenia s path; sumy v totals[] aj line_items[].totals[] (discount) | Čiastočne | Uplatní sa jeden kód — prvý, ktorý obchod prijme. Každý ďalší dostane discount_code_combination_disallowed; odmietnutý kód dostane discount_code_expired, discount_code_user_ineligible alebo discount_code_invalid s path $.discounts.codes[<index>], kde index ukazuje do discounts.codes v podobe, akú vracia odpoveď (bez duplicít a prázdnych kódov). applied obsahuje najviac jednu položku s method: "across". Suma sa objaví iba v totals na najvyššej úrovni, nie v line_items[].totals. discount_code_already_applied ani discount_code_user_not_logged_in sa nikdy neposielajú. | Najdôležitejší kód pošlite ako prvý. |
Schopnosť objednávok a webhooky
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
GET /orders/{id} a podpísané webhooky objednávok na webhook_url platformy (order) | Nepodporované | Žiadna cesta pre objednávky ani žiadne webhooky. Objednávku hlási iba checkout; košík bez checkoutu, odovzdaný cez vlastné continue_url, ju nehlási nikdy. | Čítajte checkout; skončite pri completed alebo canceled. |
Idempotencia
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
Zápisy nesú Idempotency-Key (tabuľka hlavičiek REST: povinné; text REST väzby: mali by podporovať) | Čiastočne | Nepovinné. Bez kľúča zápis prebehne bez ochrany: zopakované vytvorenie založí druhú reláciu. Kľúč má 1 až 255 tlačiteľných znakov ASCII bez medzier. | Ku každému zápisu pošlite nový kľúč a pri každom jeho opakovaní ten istý. |
| Výsledky sa uchovávajú aspoň 24 hodín, odporúča sa 48 (REST väzba, signatures) | Podporované | Najmenej 25 hodín od prvého použitia kľúča: staršie kľúče maže úloha, ktorá beží každú hodinu. Odporúčaných 48 hodín sa nedodržiava. | Na kľúč sa nespoliehajte dlhšie ako 24 hodín od jeho prvého použitia. |
Duplicita s rovnakým obsahom dostane uložený výsledok, s iným obsahom 409 (REST väzba) | Podporované | 409 idempotency_conflict. Duplicita, kým prvá požiadavka ešte beží, dostane tiež 409, s Retry-After: 2. Aj obchodné odpovede (200 s ucp.status: "error") sa ukladajú a vracajú znova. Požiadavka, ktorej operácia zlyhá chybou protokolu (400, 503, 500), kľúč uvoľní. | Po 503 alebo chybe siete opakujte s tým istým kľúčom. |
| Obsah sa porovnáva podľa SHA-256 surových bajtov tela (signatures) | Čiastočne | Porovnáva sa kanonický JSON z operácie, id v ceste a tela so zoradenými kľúčmi: na medzerách a poradí kľúčov nezáleží, na poradí v poliach áno. | — |
| Kľúče sú jedinečné pre klienta a typ operácie (signatures) | Čiastočne | Platia v rámci obchodu a presnej adresy vášho profilu, nie v rámci operácie: ten istý kľúč pri inej operácii alebo inom id relácie vedie k 409 idempotency_conflict. | Adresu profilu nemeňte a kľúč nikdy nepoužite pre iný zápis. |
| Kľúč má aspoň 128 bitov entropie (signatures) | Neuplatňuje sa | Je to pravidlo pre kľúč, ktorý generujete vy. Monokaido kontroluje iba jeho formát. | Použite UUID v4. |
Pri zlyhaní úložiska obchod požiadavku odmietne s 503 (signatures) | Čiastočne | Kľúč, ktorý sa nedá zaregistrovať, ukončí požiadavku chybou 500 internal_error skôr, než sa čokoľvek vykoná. Výsledok, ktorý sa po vykonaní operácie nepodarí uložiť, sa zapíše do logu a odpoveď aj tak odíde; opakovanie s týmto kľúčom potom dostáva 409, kým neuplynie 120-sekundová rezervácia, a potom sa operácia vykoná znova. | 409 s Retry-After chápte ako „skúste neskôr“. |
Chyby a správy
| Pravidlo | Stav | Monokaido | Čo má robiť klient |
|---|---|---|---|
Chyby protokolu ako JSON {code, content} so stavom HTTP, Retry-After pri 429 a 503 (overview, REST väzba) | Podporované | invalid_request 400 (415 pre nepodporovanú znakovú sadu alebo kódovanie), invalid_profile_url 400, not_found 404, idempotency_conflict 409, request_too_large 400 alebo 413, profile_malformed a version_unsupported 422, profile_unreachable 424, rate_limited 429, internal_error 500, service_unavailable 503. Retry-After je 60 pri 429 a 1 až 60 pri 503. Chyby profilu, verzie a objavovania pridávajú continue_url na úvodnú stránku obchodu. Výnimka: na niektoré požiadavky odpovie sám webový server stránkou HTML — 413 nad 1 MiB, 429 nad 100 požiadaviek za sekundu z jednej IP, 502 a 504, keď je API nedostupné alebo pomalé. | Odpovede HTML spracujte iba podľa stavového kódu. |
401 a 403 (overview) | Neuplatňuje sa | 401 sa nikdy neposiela. 403 pochádza iba z ochrany platformy proti zápisom z cudzieho pôvodu, pri zápise, ktorý nesie session cookie Monokaida a prichádza z cudzieho webového pôvodu — agent na serveri to nikdy neurobí; jeho telo je invalid_request. | — |
Obchodné výsledky sú HTTP 200 s messages[]; ucp.status je nepovinné rozlíšenie (checkout, overview) | Podporované | Úspešné odpovede ucp.status vynechávajú; odpovede bez zdroja majú "error". not_found relácie aj produktu je obchodná odpoveď. | Chýbajúce ucp.status čítajte ako úspech. |
Tvar správ a závažnosti recoverable, requires_buyer_input, requires_buyer_review, unrecoverable (checkout) | Čiastočne | Používajú sa recoverable, requires_buyer_input a unrecoverable; requires_buyer_review nikdy. Upozornenia nemajú presentation; žiadna správa nemá content_type. Chýbajúce pole sa hlási kódom missing (príklad v špecifikácii používa field_required; kódy nie sú uzavretý zoznam). | Rozhodujte podľa type a severity; s neznámym kódom zaobchádzajte podľa jeho závažnosti. |
Kde je špecifikácia nejednoznačná
| Téma | Čo hovorí špecifikácia | Čo implementuje Monokaido | Čo má robiť klient |
|---|---|---|---|
Rodičia dev.ucp.shopping.discount | Vzorový profil obchodu v prehľade má "extends": "dev.ucp.shopping.checkout"; príklad rozšírenia s viacerými rodičmi v prehľade aj stránka discount uvádzajú za rodičov košík aj checkout. | Oboch rodičov. Discount je aktívny aj so samotným košíkom. | Discount uvádzajte vždy, keď používate košík alebo checkout. |
Tvar version_unsupported | Tabuľka chýb uvádza stav REST 422 a príklad pre REST je telo {code, content, continue_url}; príklad v časti o kontrole verzie pri požiadavke ukazuje odpoveď s obálkou ucp a správou. | Chybu protokolu 422, {code, content, continue_url}, bez obálky ucp. | Spracujte ju ako chybu protokolu. |
Idempotency-Key a Request-Id | Tabuľka hlavičiek REST aj oficiálna schéma ich označujú za povinné; text hovorí, že operácie meniace stav by mali idempotenciu podporovať. | Text: kľúč je nepovinný, Request-Id sa ignoruje. | Kľúč posielajte pri každom zápise. |
| Z košíka checkout a zľavové kódy | Stránka cart žiada použiť obsah košíka a ignorovať prekrývajúce sa polia checkoutu; stránka discount žiada preniesť kódy košíka. | Položky, kupujúci, kontext a jazyk z košíka; kódy z požiadavky, ak nejaké posiela, inak z košíka; doprava z požiadavky. | Ak chcete ponechať kódy košíka, vynechajte z požiadavky na prevod discounts. |
Kedy použiť requires_escalation | Stav checkoutu, ktorý potrebuje údaje, aké API neprijme, alebo vstup kupujúceho; stránka checkout tiež hovorí, že checkout dokončí kupujúci v dôveryhodnom rozhraní, ak nie je podporované rozšírenie AP2 mandates. | Každý pripravený checkout, pretože platba prebieha vždy v obchode. Je to posledný stav, ku ktorému API dospeje samo. | Odovzdajte pri requires_escalation; na ready_for_complete nečakajte. |
Prázdne links[] | Pole je povinné. | [], keď obchod nemá žiadny súhlas v pokladni s odkazom, alebo sa súhlasy nepodarilo načítať. | Prázdny zoznam prijmite. |
| Cache profilu platformy | Profil sa musí poskytovať s public a max-age aspoň 60; pravidlá sťahovania dovoľujú obchodu držať ho v cache aspoň 60 sekúnd bez ohľadu na jeho Cache-Control a obnovovať ho na pozadí. | Použije sa jeho max-age, obmedzené na 60 s až 1 h; no-store, no-cache a private sa ignorujú. | max-age nastavte na hodnotu, ktorá vám vyhovuje. |
Nad rámec špecifikácie
Monokaido pridáva obmedzenia, ktoré špecifikácia necháva otvorené. Sú súčasťou kontraktu:
- Jeden obchod na hostiteľa. Obchod sa určí podľa hlavičky
Host. Hostiteľ, ktorý UCP neposkytuje, odpovie404 not_foundbez ohľadu na príčinu; pozastavená firma odpovie503. Pozri Princípy a životný cyklus. - Limity požiadaviek na IP adresu klienta a operáciu za minútu: 600 čítaní,
300 zápisov, 60 požiadaviek odovzdania;
429 rate_limitedsRetry-After: 60. Odpovede nesúX-RateLimit-Limit,X-RateLimit-RemainingaX-RateLimit-Reset. Webový server pridáva 100 požiadaviek za sekundu z jednej IP (nárazovo 200), počítaných spolu s ostatnou prevádzkou obchodov z tej istej IP. Podrobnosti v kapitole Idempotencia, súbežnosť a limity. - Limity požiadavky. 100 položiek, množstvo 999 na položku (väčšie množstvo sa zníži na 999), 10 zľavových kódov, 20 identifikátorov pri operácii lookup, 20 výsledkov na stránku, telo 1 MiB.
- Na reláciu naraz jedna požiadavka. Zápisy a čítania checkoutu jednej
relácie čakajú v rade; požiadavka, ktorá sa do 10 sekúnd nedostane na rad
alebo nájde štyri čakajúce, dostane
503sRetry-After: 1. - Iba volania zo servera. CORS pre cudzie pôvody nie je, takže webová stránka z iného pôvodu API volať nemôže.
- Cache. Každá odpoveď okrem profilu obchodu je
no-store; odpovede nesú ajETag. - Odovzdanie.
continue_urlprenesie do košíka obchodu položky a uplatnený zľavový kód, nie údaje kupujúceho. Čo sa ukladá a ako dlho, opisuje kapitola Bezpečnosť a ochrana údajov.
Ako sa oznamujú zmeny
- Záväzným vyjadrením je profil obchodu. Hovorí, čo obchod v danej chvíli poskytuje: verziu protokolu, endpoint a schopnosti. Môže sa zmeniť, keď obchodník zmení obchod (katalógový režim, vypnutie UCP, jeho domény), a je určený na opakované čítanie: v cache sa smie držať päť minút.
- Verzia protokolu sa nemení. Špecifikácia v rámci verzie dovoľuje spätne
kompatibilné zmeny — nové nepovinné polia, nové chybové kódy, nové hodnoty
výčtov — a pre nekompatibilnú zmenu vyžaduje novú verziu. Monokaido nemení
význam
2026-04-08: podpora inej verzie by sa objavila vucp.versionasupported_versionsprofilu. - Kontrakt opisuje tento manuál. Každá stránka ukazuje dátum poslednej aktualizácie a dokument OpenAPI aj ďalšie strojovo čitateľné súbory sa zverejňujú spolu s týmito stránkami. Manuál neponúka odber noviniek, harmonogram ukončovania podpory ani záväzok úrovne služieb.
Aby ste si zmenu všimli včas, pri každom opätovnom načítaní profilu obchodu
porovnajte ucp.version a zoznam schopností, z času na čas porovnajte dokument
OpenAPI s kópiou, podľa ktorej ste klienta vytvorili, a v odpovediach ignorujte
polia, kódy a hodnoty výčtov, ktoré nepoznáte — môžu pribudnúť nové.