Časté otázky k UCP

Nie. Profil obchodu aj každý checkout nesú payment_handlers: {}. POST …/complete objednávku nevytvorí a nič nezmení: odpovie to isté ako čítanie checkoutu a platobné údaje v jeho tele sa ignorujú. Pripravený checkout má stav requires_escalation so správou payment_required a continue_url; kupujúci tento odkaz otvorí a zaplatí na webe obchodu, spôsobmi platby, ktoré obchod ponúka. Pozri Princípy a životný cyklus a Zhoda so špecifikáciou UCP.

Webhooky neexistujú. Čítajte checkout cez GET /ucp/v1/checkout-sessions/{id}, kým status nie je completed (s order.id, order.label — číslom objednávky obchodu, ak ho objednávka má — a order.permalink_url, stránkou potvrdenia objednávky v obchode, ktorá sa otvorí bez prihlásenia) alebo canceled.

Dokončí sa vždy iba checkout, nikdy košík: košík najprv premeňte na checkout a odovzdajte checkout. completed znamená, že objednávka vznikla, nie že je zaplatená; položky a súčty checkoutu zostávajú vašou poslednou ponukou a kupujúci mohol objednávku v obchode zmeniť. Na jednu reláciu majte naraz rozpracovanú najviac jednu požiadavku: čítanie checkoutu získava zámok relácie a môže odpovedať 503 s Retry-After: 1.

Rozumný rytmus je jedno čítanie každých 5–10 sekúnd, kým je kupujúci pravdepodobne v obchode (prvú štvrťhodinu), potom raz za minútu. Limit 600 čítaní checkoutu za minútu na IP platí pre všetky vaše relácie spolu. Jedno čítanie hneď po expires_at dá konečnú odpoveď: completed, ak objednávka prišla skôr, inak canceled. Pozri Idempotencia, súbežnosť a limity.

V obchode sa nestane nič: žiadna objednávka a žiadna rezervácia skladu. Checkout zostáva otvorený do svojho expires_at, 24 hodín po poslednom vytvorení alebo úprave (čítanie ho nepredlžuje); ďalšie čítanie potom vráti canceled. Košík platí 7 dní od poslednej zmeny a potom obchod na jeho volania odpovedá HTTP 200 s chybovou správou not_found. Pred odovzdaním lehotu predĺži každé vytvorenie či úprava, po odovzdaní už nič. Uložené údaje sa zmažú 30 dní po vypršaní.

Checkout sa dokončí iba vtedy, keď objednávka vznikne z košíka, ktorý odkaz naplnil, a obsahuje aspoň jednu z položiek checkoutu. Nedokončí sa, keď sa kupujúci do obchodu prihlásil až v jeho pokladni (košík hosťa sa vtedy zlúči so zákazníckym a objednávka vznikne z neho), alebo keď objednávka neobsahuje žiadnu z položiek checkoutu; zriedka aj vtedy, keď samotné dokončenie zlyhalo na strane Monokaida (nie je zaručené). Taký checkout pri vypršaní skončí ako canceled, hoci objednávka existuje. (Checkout, ktorého odkaz sa otvoril, keď bol ešte incomplete, namiesto toho zostane incomplete; dokončí sa aj vyprší rovnako.) Chýbajúce dokončenie preto neberte ako dôkaz, že objednávka neexistuje; nechajte kupujúceho pozrieť si potvrdenie priamo od obchodu.

Nie. Zrušenie zatvorí iba košík alebo checkout v UCP. Zrušenie dokončeného checkoutu ho vráti so správou checkout_completed a objednávka zostane nezmenená. Zmeny objednávky sú vecou kupujúceho a obchodu.

Samostatný sandbox neexistuje. Testujete proti obchodu na Monokaide, ktorý má UCP zapnuté na vlastnej doméne. Volania katalógu, košíka a checkoutu nevytvoria objednávku a nič nestrhnú; objednávka vznikne, až keď niekto otvorí continue_url a zadá objednávku v obchode — a je to skutočná objednávka toho obchodu. Test si dohodnite s obchodníkom: košíky agenta sa objavia aj v štatistike košíkov obchodu. Ako obchodník UCP zapne, opisuje Zapnutie UCP v obchode.

Profil svojej platformy: dokument JSON na verejnej adrese https://, ktorú spravujete, s odpoveďou 200 bez presmerovania do 5 sekúnd, najviac 256 KiB, s ucp.version 2026-04-08 a so schopnosťami, ktoré chcete používať. Každé volanie pod /ucp/v1 ho uvádza v hlavičke UCP-Agent. Minimálny profil ukazuje Rýchly štart pre vývojárov.

Nie. API neposiela hlavičky CORS pre iné pôvody, takže stránka na vašej doméne ho volať nemôže. Volajte ho zo svojho servera. Jediná stránka určená pre prehliadač je continue_url, ktorú otvára kupujúci.

Áno. Každý obchod poskytuje to isté API na svojej vlastnej doméne. Prečítajte si profil každého obchodu a použite endpoint, ktorý zverejní. Relácie patria jednému obchodu: id košíka alebo checkoutu použité na doméne iného obchodu dostane HTTP 200 s chybovou správou not_found. Limity požiadaviek sa rátajú na IP adresu pre všetky obchody na Monokaide spolu.

Profil je dostupný na každej doméne obchodu, na ktorej sa UCP poskytuje, ale každá adresa, ktorú zverejňuje — endpoint, continue_url, odkazy na objednávku a produkty —, používa overenú primárnu doménu obchodu. Volajte zverejnený endpoint.

Nie. Obchod sa určí podľa domény, ktorú voláte. Vašu platformu identifikuje adresa profilu v UCP-Agent, ktorá sa kryptograficky neoveruje. Id košíka alebo checkoutu je jediným kľúčom k danej relácii: držte ho na svojom serveri a mimo odkazov a logov. continue_url nesie samostatné tajomstvo určené kupujúcemu. Pozri Bezpečnosť a ochrana údajov.

Každá relácia UCP je anonymná; prepojenie identity (identity linking) sa nepodporuje. Keď kupujúci otvorí continue_url, položky idú do košíka, ktorý obchod ukazuje v tej karte prehliadača: do zákazníckeho košíka, ak je v obchode v tej karte prihlásený, inak do košíka hosťa. Odkaz otvorený v novej karte preto zvyčajne naplní košík hosťa. Kupujúci, ktorý sa potom prihlási v pokladni obchodu, položky spravidla nestratí (obchod košík hosťa zlúči so zákazníckym), ale checkout v UCP sa nedokončí (pozri vyššie).

Všetko okrem položiek a uplatneného zľavového kódu: kontaktné údaje, adresu doručenia, spôsob dopravy aj platbu. Údaje kupujúceho, ktoré ste poslali, zostávajú v relácii UCP.

Sumy sú celé čísla v najmenších jednotkách meny, ktorá je pri nich (EUR aj HUF majú dve desatinné miesta: 69900 EUR je 699,00 €). Obsahujú DPH všade, kde má obchod cenu s DPH, a prirážky obchodu; samostatný príznak na to odpoveď nemá. V košíku a checkoute sú súčty subtotal, záporná discount (iba kým platí zľavový kód), fulfillment (cena dopravy, až keď je vybraná možnosť dopravy) a total; všetky okrem total dávajú spolu total. Percentuálny zľavový kód sa počíta zo súčtu bez DPH, presne ako v pokladni obchodu, takže 10 % zľava nie je 10 % zo zobrazeného medzisúčtu. Príplatky za spôsob platby sa nenaceňujú.

Jazyk je context.language z tela požiadavky, inak prvý použiteľný jazyk z Accept-Language (v poradí hlavičky — váhy sa ignorujú), inak prvý jazyk obchodu; použije sa iba jazyk, ktorý obchod ponúka. Mena sa riadi jazykom: context.currency ju nezmení, iba hovorí, v akej mene je zadaný filters.price v katalógu (vo vyhľadávaní aj vyhľadaní podľa id). Ak chcete ceny v inej mene, zvoľte jazyk, v ktorom obchod v tej mene predáva. Košík alebo checkout si jazyk ponechá, kým telo požiadavky neuvedie iný context.language; zmena jazyka položky nanovo nacení a id ich riadkov sa zmenia.

Katalóg uvádza pre každý variant availability.status — in_stock, out_of_stock, preorder alebo discontinued — bez počtu kusov. Každé vytvorenie a každá úprava, ktorá posiela line_items (úprava košíka ich posiela vždy), sklad overí znova: množstvo nad stav skladu sa zníži s varovaním quantity_adjusted, vypredaný riadok sa odstráni s out_of_stock a variant na predobjednávku sklad neobmedzuje (každý riadok má strop 999 kusov). Nič sa nerezervuje, kým kupujúci neodošle objednávku v obchode; sklad sa overuje znova pri odovzdaní položiek aj v pokladni obchodu.

Iba ak váš profil deklaruje dev.ucp.shopping.discount. Na košík alebo checkout sa uplatní jeden kód: prvý, ktorý obchod prijme, a každý kód za ním dostane varovanie discount_code_combination_disallowed. Odmietnutý kód dostane discount_code_expired, discount_code_user_ineligible alebo discount_code_invalid — a v košíku bez položiek je každý kód discount_code_invalid, kým sa položky nepridajú. Uplatnený kód putuje s položkami do košíka kupujúceho, kde ho obchod overí znova.

Keď deklarujete dev.ucp.shopping.fulfillment, checkout ponúkne aktívne spôsoby dopravy obchodu pre krajinu doručenia (kým adresa nie je známa, všetky) ako možnosti jedného spôsobu doručenia, každú s cenou vypočítanou podľa toho istého pravidla ako v pokladni obchodu. Výber spôsobu, ktorý potrebuje výdajné miesto (spôsob Packeta), pridá správu pickup_point_required: miesto sa vyberá v obchode a checkout sa aj tak môže dostať do stavu requires_escalation. Zvolená možnosť sa do obchodu neprenáša; kupujúci dopravu vyberie znova tam.

Na IP adresu klienta a na operáciu za minútu: 600 pre čítanie (profil, katalóg, čítanie košíka alebo checkoutu), 300 pre zápisy, 60 pre každú z dvoch ciest odovzdania (načítanie stránky continue_url a požiadavka, ktorú stránka potom odošle). Platia spolu pre všetky obchody na Monokaide. Nad limitom príde 429 rate_limited s Retry-After: 60. Webový server pred API povolí 100 požiadaviek za sekundu na IP (nárazovo 200) a nad tým odpovie vlastnou HTML stránkou 429. Jeden klient (IPv4 adresa alebo IPv6 /64) môže za minútu prinútiť Monokaido stiahnuť najviac 5 profilov platformy, ktoré ešte nemá v cache (stiahnutý profil slúži všetkým obchodom); ďalšie dostanú 503 s Retry-After. Pozri Idempotencia, súbežnosť a limity.

Košík alebo checkout uchováva, čo ste poslali — meno, e-mail a telefón kupujúceho, adresu doručenia, context požiadavky, zľavové kódy — spolu s adresou profilu vašej platformy a svojou poslednou odpoveďou, a to do 30 dní po svojom expires_at. Odpovede uložené pre Idempotency-Key sa zmažú po 25 hodinách. Tabuľky UCP neukladajú IP adresu ani User-Agent. To, čo kupujúci zadá v pokladni obchodu, sú bežné údaje objednávky obchodu. Kto za ktoré údaje právne zodpovedá, určujú zmluvné podmienky obchodu a Monokaida. Pozri Bezpečnosť a ochrana údajov.

Presne 2026-04-08. ucp.version profilu vašej platformy musí byť tento dátum — každý iný sa odmietne s 422 version_unsupported — a každá schopnosť, ktorú používate, ho musí uvádzať: schopnosť deklarovaná iba v inej verzii sa nevyjedná a operácia, ktorá ju potrebuje, odpovie správou capabilities_incompatible. Obchod nezverejňuje supported_versions. Neznáme polia v požiadavkách sa ignorujú, nikdy sa neodmietajú. Čo obchod dnes podporuje, vždy povie jeho profil; tento manuál aj dokument OpenAPI opisujú nasadený kód a každá stránka uvádza, kedy bola naposledy aktualizovaná.

Otázky k produktom, cenám, doručeniu alebo konkrétnej objednávke patria obchodu. Otázky k implementácii UCP smerujte na Monokaido na support@monokaido.com. Uveďte doménu obchodu, čas (UTC), metódu a cestu, HTTP stav a code odpovede — API nevracia žiadne id požiadavky, preto si do logov zapisujte vlastné. Id košíka alebo checkoutu a continue_url sú prístupové údaje: nikdy ich neposielajte celé, ani nám — uveďte ich prvých osem znakov (pozri Nahlásenie bezpečnostného problému).