Ecommio
Všetky príručky

Headless storefront — rýchly štart

Minimálny sled volaní na postavenie vlastného frontendu nad API: chrome obchodu, katalóg, košík, pokladňa.

Pre: Vývojár

Tento článok je vstupná brána do headless API — sled volaní, ktorý potrebuje takmer každý vlastný frontend, od chrome obchodu po dokončenú objednávku. Úplný zoznam endpointov, hlavičiek a pravidiel je v Headless Storefront API — tento článok z neho vyberá len to, čo treba na prvý funkčný obchod.

1. Základná hlavička na každom requeste

Každé volanie potrebuje X-Client-Slug: <slug-obchodu> — bez neho server nevie, ktorý obchod odpovedá. Voliteľne pridajte Accept-Language pre jazyk a X-Currency pre zobrazovaciu menu (košík a pokladňa sa napriek tomu vždy vyrovnávajú v primárnej mene obchodu).

const BASE = 'https://moj-eshop.ecommio.sk/api/v1';
const CLIENT_SLUG = 'moj-eshop';

async function api(path: string, init: RequestInit = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Slug': CLIENT_SLUG,
      ...init.headers,
    },
  });
  return res.json();
}

2. Chrome obchodu (raz, cachovať)

const store = await api('/store');   // názov, logo, mena, DPH zobrazenie, hranica dopravy zdarma
const menus = await api('/menus');   // navigačný strom
const locales = await api('/locales'); // aktívne jazyky

store.plugins prezradí, ktoré pluginy má obchod zapnuté (analytika, cookie lišta) — vlastný frontend si ich vie vykresliť sám podľa rovnakej konfigurácie, akú dostávajú vstavané témy.

3. Výpis a detail produktu

const list = await api('/products?category=bezecke-topanky&sort=price-asc&per_page=24');
const facets = await api('/products/facets?category=bezecke-topanky'); // panel filtrov
const product = await api('/products/bezecka-topanka-air?include=translations,reviews');

Každý riadok produktu (výpis aj detail) už nesie rating, reviews_count a objekt manufacturer — netreba druhé volanie len kvôli hviezdičkám alebo značke.

4. Košík

Košík hosťa sa identifikuje cez X-Cart-Session — server ho vygeneruje pri prvom zápise; hodnotu si uložte (napr. do cookie) a posielajte pri každom ďalšom volaní.

let cartSession: string | undefined;

async function addToCart(variantId: number, quantity: number) {
  const res = await fetch(`${BASE}/cart/items`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Slug': CLIENT_SLUG,
      ...(cartSession && { 'X-Cart-Session': cartSession }),
    },
    body: JSON.stringify({ variant_id: variantId, quantity }),
  });
  cartSession ??= res.headers.get('X-Cart-Session') ?? undefined;
  return res.json();
}

5. Pokladňa

const methods = await api('/checkout/methods'); // doprava + platobné metódy
const order = await api('/checkout', {
  method: 'POST',
  headers: cartSession ? { 'X-Cart-Session': cartSession } : {},
  body: JSON.stringify({
    email: 'zakaznik@example.com',
    shipping_method_id: methods.shipping[0].id,
    payment_method_id: methods.payment[0].id,
    // adresa, prípadne create_account / gift_card_code
  }),
});

Platba kartou pokračuje cez POST /checkout/stripe/intent a potvrdenie na vlastnej doméne cez Stripe Elements — objednávka nikdy nedostane presmerovací checkout_url. Bankový prevod nevyžaduje nič ďalšie — vykreslite order.payment_instructions, ktoré odpoveď vráti priamo.

Pozor: Overte pred spustením do produkcie, či zvolená platobná metóda vôbec podporuje headless iniciáciu — GET /checkout/methods vracia len metódy, ktoré supportsHeadlessCheckout() povoľujú; ostatné POST /checkout odmietne s 422 PAYMENT_METHOD_NOT_AVAILABLE.

6. Prihlásený zákazník

const { token } = await api('/auth/login', { method: 'POST', body: JSON.stringify({ email, password }) });
// ďalej: Authorization: Bearer <token> na požiadavkách vyžadujúcich prihlásenie
const orders = await fetch(`${BASE}/orders`, {
  headers: { 'X-Client-Slug': CLIENT_SLUG, Authorization: `Bearer ${token}` },
}).then(r => r.json());

Čo tento rýchly štart vynecháva

Wishlist, vernostné body, affiliate program, digitálne stiahnutia, sledovanie objednávky bez účtu, konfigurovateľné produkty a plná tabuľka práv tokenu (identity:read/write, groups:write) — všetko je zdokumentované v Headless Storefront API, ktorá je aditívna referencia bez breaking zmien v rámci v1.

Časté problémy

  • `401`/`403` na verejných endpointoch. Chýba alebo je nesprávna hlavička X-Client-Slug — bez nej server nevie priradiť request k obchodu.
  • Košík sa po refreshi vyprázdni. X-Cart-Session sa neukladá medzi requestami na strane klienta — uložte hodnotu z prvej odpovede a posielajte ju ďalej.
  • Cena v košíku sa nezhoduje so zobrazenou cenou v inej mene. Zobrazovacia mena (X-Currency) je len prepočet na zobrazenie; košík a pokladňa sa vždy zúčtujú v primárnej mene obchodu.
  • Platba kartou vracia presmerovanie namiesto `clientSecret`. API v tejto platforme nikdy nevracia checkout_url pre kartu — integrácia musí použiť Stripe Elements na vlastnej doméne.
  • `422 PAYMENT_METHOD_NOT_AVAILABLE` pri platbe, ktorá funguje vo vstavanej téme. Daná brána nepodporuje headless iniciáciu (supportsHeadlessCheckout() === false) — ponúknite zákazníkovi inú metódu.

Súvisí

Bola táto stránka užitočná?