Headless Storefront API

Interaktívna referencia všetkých endpointov je na /docs/api — v predvolenom nastavení je prístup obmedzený len na prihlásených administrátorov platformy (a super-adminov), na verejný prístup treba prostredie s explicitne zapnutým verejným režimom dokumentácie. Strojovo čitateľná špecifikácia (OpenAPI 3.1) je k dispozícii na /docs/api.json pod rovnakým prístupovým pravidlom.

Postavte kompletný storefront na ľubovoľnom frontende (Next.js, Nuxt, natívna aplikácia, iný CMS) nad REST API platformy — bez potreby platformovej témy. Každá zákaznícka operácia, ktorú používajú vstavané témy, je dostupná cez /api/v1: katalóg, košík, pokladňa, účet, objednávky, faktúry, vrátenia, obsah aj konfigurácia obchodu.

1. Základy requestu#

Schopnosti tokenu (nastavené per api_clients záznam): identity:read, identity:write (profil/heslo/avatar/email), groups:write (priradenie do dôveryhodnej B2B skupiny) a automaticky pridané tenant:<uuid> prepojenie, ktoré sa kontroluje pri každom zákazníckom requeste — token vydaný pre obchod A nemôže čítať dáta obchodu B ani zmenou X-Client-Slug.

2. Čo volať pre jednotlivé časti obchodu#

• Chrome obchodu (raz, cachovať): GET /v1/store (názov, logo, mena, jazyky, kontakt,

sociálne siete, zobrazenie DPH, hranica dopravy zdarma) + GET /v1/menus (navigácia) + GET /v1/locales.

• Domovská stránka: GET /v1/products?... (kurátorské zoznamy), GET /v1/collections, GET /v1/categories?tree=true, GET /v1/brands.
• Výpis produktov (PLP): GET /v1/products — filtre category, manufacturer, tags (csv slugy), attr_<slug> (csv hodnoty), search, min_price, max_price; sort = price-asc/price-desc/newest/popularity/rating/az/za (alebo starší name|price|created_at + direction); per_page. Bočný panel filtrov vykresľujte z GET /v1/products/facets (kategórie, značky, tagy, atribúty + počty, cenové rozpätie, možnosti triedenia; ?category= zúži atribútové/cenové fasety).
• Detail produktu (PDP): GET /v1/products/{id-or-slug}?include=translations,reviews,content_sections,size_guide, GET /v1/products/{id}/related, GET /v1/products/{id}/reviews. Vypredané → POST /v1/products/notify-back-in-stock. Produkty na mieru nesú option_groups — pozri §8.
• Karty / hviezdičky / značka: každý riadok produktu (výpis aj detail) nesie rating (priemer schválených recenzií, 0 keď žiadne nie sú) + reviews_count a objekt manufacturer (id/name/slug/logo_url) — bez druhého volania. Priemer si nepočítajte sami z reviews[] — je stránkovaný.
• Vyhľadávanie: GET /v1/search?q=, /v1/search/suggestions, /v1/search/autocomplete, /v1/search/popular.
• Košík: GET /v1/cart; zmeny cez /v1/cart/items, /v1/cart/discount, /v1/cart/gift-card; DELETE /v1/cart na vyprázdnenie.
• Pokladňa: GET /v1/checkout/methods → POST /v1/checkout (guest alebo prihlásený; gift_card_code, create_account). Platba kartou → POST /v1/checkout/stripe/intent, potvrdenie cez Stripe Elements na vlastnej doméne. Bankový prevod → vykreslite vrátené payment_instructions. Žiadne checkout_url — pozri §7.
• Účet: profil /v1/customer/profile, adresy /v1/customer/addresses, firma /v1/customer/company, objednávky /v1/orders (+ /reorder, /invoice, /returns), faktúry /v1/invoices, wishlist /v1/wishlist, vernosť /v1/loyalty, súbory na stiahnutie /v1/downloads, affiliate /v1/affiliate. Hostia (bez účtu) používajú /v1/orders/track/{guest_token} — pozri §9.
• Obsah: GET /v1/pages/{slug}, /v1/blog (+ /categories, /{slug}), /v1/faqs.
• Engagement: POST /v1/newsletter/subscribe (+ /confirm/{token}, /unsubscribe), POST /v1/contact.

3. Referencia endpointov#

Stĺpec Auth: — verejné · 🔑 Sanctum bearer · 🔑+ + gate na schopnosť tokenu.

Identita a účet#

Katalóg#

Košík a pokladňa#

GET /checkout/methods vráti ceny dopravy podľa aktuálneho košíka len vtedy, keď request nesie hlavičku X-Cart-Session (rovnaká, akú vraciate ku GET /cart) — inak vráti cenníkové ceny dopravy s príznakom cart_aware: false (napríklad chýbajúca doprava zadarmo od prahu košíka, lebo žiadny košík nie je k dispozícii). Odpoveď košíka (GET /cart) nesie aj loyalty_points_used, loyalty_discount a dropped_on_merge (položky vypadnuté pri zlúčení košíka hosťa s košíkom po prihlásení). Objednávka (GET /orders/{id}) nesie gift_card_amount a loyalty_discount — sumy uhradené darčekovou kartou a vernostnými bodmi.

Objednávky, faktúry, vrátenia#

Zákaznícke extra#

Obsah a konfigurácia obchodu (verejné čítanie)#

4. Parita web ↔ API#

Každá storefrontová/zákaznícka operácia z vstavaných tém a jej API ekvivalent.

Zámerne nedostupné cez API: layout a sekcie domovskej stránky/témy — headless klient si vykresľuje vlastný dizajn, takže spotrebúva dátové endpointy vyššie (produkty, menu, konfigurácia obchodu, obsah), nie stromovú štruktúru platformovej témy. Administrátorské operácie (CRUD produktov, nastavenia, fulfilment) zostávajú len v administrácii.

Pluginy: čo má obchodník zapnuté sa dozviete cez GET /store → plugins, s rovnakou verejnou konfiguráciou, akú dostávajú aj naše vlastné témy (analytické ID, texty cookie lišty, …), takže si ju viete vykresliť sami. Server-side pluginy (fakturácia, newsletter sync, platobné brány) od vás nič nepotrebujú — bežia na udalostiach objednávky bez ohľadu na vás a v zozname sa objavia s config: null. Jedinou výnimkou je brána bez API iniciácie; pozri §7.

5. Minimálny Next.js flow#

const api = (path: string, init: RequestInit = {}) =>
  fetch(`${BASE}/api/v1${path}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Slug': CLIENT_SLUG,
      ...(token && { Authorization: `Bearer ${token}` }),
      ...(cartSession && { 'X-Cart-Session': cartSession }),
      ...init.headers,
    },
  }).then(r => r.json());

// 1. chrome
const store = await api('/store');
const menus = await api('/menus');
// 2. prehliadanie → košík (zachyťte cart_session z prvej odpovede)
await api('/cart/items', { method: 'POST', body: JSON.stringify({ variant_id, quantity: 1 }) });
// 3. pokladňa
const methods = await api('/checkout/methods');
const order = await api('/checkout', { method: 'POST', body: JSON.stringify(payload) });
// 4. výber platby (karta): potvrdenie cez Stripe Elements na VAŠEJ doméne
const { clientSecret } = await api('/checkout/stripe/intent', {
  method: 'POST', body: JSON.stringify({ order_id: order.order_id }),
});
// Bankový prevod namiesto toho → vykreslite order.payment_instructions; nič iné netreba.

6. API je verzia v1, aditívna#

API v1 je len pridávacie — pole ani endpoint sa nikdy neodstráni ani nepremenuje na mieste: frontend hostíte vy, takže breaking change na tomto rozhraní by bol výpadok, ktorý za vás nevieme opraviť. Nové polia a nové voliteľné parametre pribúdajú bez zmeny verzie — tolerujte neznáme polia a nič vás nerozbije.

Breaking zmeny idú pod novú cestu (/api/v2/...), bežiacu súbežne s v1, kým klienti migrujú.

Odpovede prechádzajú explicitným výberom polí (nie surovým modelom), takže interné/citlivé stĺpce (nákupná cena, interné poznámky, cesty k súborom na disku, session identifikátory) sa do payloadu nikdy nedostanú. Kľúčové zjednotenia:

• Stránkované zoznamy (/products, /orders, /returns, /invoices, /downloads,

/products/{id}/reviews, /blog) používajú obálku { data, links, meta }.

• variants[].attribute_values je vždy zoznam objektov ({id, attribute_id, value, position, attribute:{id,name,slug,type}}),

nikdy mapa — importovaný feed bez namapovaných atribútov vráti položky s id: null a attribute_id: null, ale slug/value sú vždy vyplnené. Kľúčujte podľa attribute.slug, nikdy podľa attribute.id.

• checkout_url na POST /checkout neexistuje a nikdy nefungoval — platba kartou ide cez

/checkout/stripe/intent, presmerovacie brány cez svoje vlastné endpointy (pozri §7).

7. Platobné metódy dostupné cez API#

GET /checkout/methods vráti nakonfigurované platobné metódy obchodníka plus každý platobný plugin, ktorý je zapnutý, nakonfigurovaný a dá sa spustiť z /v1. is_plugin odlíši jedny od druhých; id pluginového riadku je kód brány a jeho fee je 0.

Vytvorenie objednávky a prijatie platby sú dva kroky pre každú bránu: POST /checkout uloží objednávku v stave pending, potom vymeníte jej order_id za miesto, kam poslať kupujúceho.

Všetky tri prijímajú {"order_id": "…"} a fungujú aj pre hostí bez účtu — vlastníctvo order_id spolu s kontextom klienta stačí na autorizáciu.

Návrat kupujúceho nič nedokazuje. Pri oboch presmerovacích bránach nezaručuje nič ani to, že sa kupujúci vrátil (krypto platba môže byť visiaca, nedoplatená alebo expirovaná). Stav platby riadi podpísaný webhook od poskytovateľa; čítajte ho späť cez GET /orders/{id} alebo `/orders/track/{token}`.

Brána, ktorú klient nevie spustiť cez API, sa z /checkout/methods skryje a POST /checkout ju odmietne s 422 PAYMENT_METHOD_NOT_AVAILABLE — objednávka tak nikdy neuviazne potichu v stave pending.

Kam sa kupujúci vráti#

Čokoľvek pošleme vášmu zákazníkovi — návrat z brány aj odkazy v transakčných mailoch — sa skladá z URL šablón na vašom API klientovi, s fallbackom na náš vlastný storefront, keď nie sú nastavené. Headless tenant má vlastný storefront vypnutý, takže bez nastavenia skončí zákazník na landing page Ecommio. Nastavte aspoň:

{guest_token} je spôsob, ako váš frontend ukáže objednávku hosťovi — headless hosť nemá u nás session. Podpísané odkazy na jednotlivé súbory fungujú aj bez tohto nastavenia; iba súhrnný zoznam "moje súbory" potrebuje download_url.

8. Konfigurovateľné produkty#

Produkty vyrábané na mieru (gravírovanie, emblém z galérie, nahrané logo) nesú svoje voľby priamo na detaile produktu:

// GET /v1/products/{id-or-slug}
{ "product": {
  "has_configurator": true,
  "option_groups": [{
    "id": "019f…", "name": "Emblém", "type": "image_select",
    "required": true, "position": 0, "config": null,
    "values": [
      { "id": "019f…", "label": "Tenis", "code": null,
        "price_delta": 0.30, "image_url": "https://…", "is_default": false, "position": 0 }
    ]
  }]
}}

option_groups je vždy prítomný — prázdne pole, keď produkt nie je konfigurovateľný alebo obchodník nemá (platený) konfigurátor. Vykresľujte podľa type:

Povolené prípony a limit veľkosti sú nastavenie obchodníka, nehardcodujte ich — čítajte plugins["product-configurator"] z GET /store (extensions, accept, formats_label, max_size_mb) a podľa toho ovládajte výber súboru a jeho nápovedu.

Potom pridanie do košíka:

// POST /v1/cart/items
{ "variant_id": "019f…", "quantity": 1,
  "options": [{ "group_id": "019f…", "value_id": "019f…" }] }

Server prevaliduje a precení každú voľbu: price_delta sa pripočíta do jednotkovej ceny položky, povinné skupiny sa vynucujú a voľby sa prenesú do objednávky (čitateľné v order.items[].metadata) aj na faktúru. Chýbajúca povinná skupina → 422 INVALID_PRODUCT_OPTIONS.

`price_delta` je len zobrazovacia hodnota — prepočítava sa do vašej X-Currency, kým košík vždy prepočítava z uloženej hodnoty v primárnej mene.

Odoslanie options pre obchod bez konfigurátora sa ignoruje (položka sa naceni ako jednoduchý produkt) namiesto zamietnutia, takže pred vykreslením vlastného builderu skontrolujte features.product_configurator na GET /store.

9. Samoobsluha pre hostí#

Všetko pod /orders, /invoices a /downloads je viazané na prihláseného zákazníka, ktorým hosť nie je. Hostia namiesto toho používajú guest_token objednávky — hodnotu dosadenú do vašich šablón checkout_success_url / account_order_url:

Čo je dobré vedieť:

• Vlastníctvo tokenu je autorizácia — zaobchádzajte s ním ako s heslom. Otvára presne

jednu objednávku a nič iné.

• Podmienené nastavením obchodníka (čítajte ako features.guest_order_tracking na

GET /store). Vypnuté → 404, a všetky doterajšie odkazy prestanú fungovať.

• Len objednávky hostí. Objednávka prihláseného zákazníka takto dostupná nie je a

vo vašich URL šablónach nikdy nenesie token — takí zákazníci sa prihlasujú.

• Digitálne doručenie funguje aj bez tohto: potvrdzujúci mail už nesie podpísané odkazy na

jednotlivé súbory. Tieto endpointy slúžia hosťovi, ktorý mail stratil alebo mu odkazy vypršali, na získanie nových bez zakladania účtu.