Frontend partnera

Design a frontend pro klienta nemusíte skládat ze šablony platformy. Můžete měnit vzhled v souborech, nebo postavit vlastní aplikaci nad Shop API. Pokladna, platby a účet zákazníka zůstávají vždy na platformě.

Dvě cesty

Vzhled v souborech. Obchod běží na šabloně platformy a vy mu měníte téma, podobu e-shopu, úvodní stránku, vlastní CSS a stránky webu. Soubory držíte v gitu a nahráváte je příkazem portican vzhlad jako koncept; zveřejní ho obchodník. Viz část Vzhled v souborech níže.
Vlastní frontend. Napíšete vlastní aplikaci, která čte katalog a obsah obchodu přes Shop API pomocí SDK @portican/storefront. Běží u vás, ne na Porticanu. Viz část Klient SDK níže.
Obě cesty můžete kombinovat s tím, co popisují Háčky ve značkování, Bloky a jejich pole a Předloha webu. Obsah, který má měnit obchodník, čtěte z obchodu (nastavení, stránky webu, produkty): administrace upravuje jen to, co platforma zná, ne bloky, které byste si vymysleli ve vlastním kódu.

Postup od klíče po nasazený frontend

Obsluha obchodu vytvoří v administraci v části Obchod › Integrace klíč frontendu: pojmenuje ho a zapíše adresy webu, ze kterých bude volat prohlížeč. Adresa je https bez cesty a nesmí patřit platformě ani její subdoméně; nejvýše 5 adres na klíč a 5 klíčů na trh. Klíč se ukáže jen jednou.
Na téže obrazovce je token trhu a adresa Shop API obchodu s tlačítkem pro zkopírování; adresu skládá server z domény trhu, nehádejte ji z příkladů. Klíč platí jen s tokenem svého trhu, v hlavičce portican-kluc-frontendu spolu s hlavičkou vendure-token.
Nainstalujte SDK z npm příkazem npm install @portican/storefront. Balíček je na veřejném npm a nemá závislosti; každou verzi zveřejňuje jen CI Porticanu z hlavní větve.
Na serveru (SSR) vytvořte klienta s klíčem, v prohlížeči ho vytvořte bez klíče. Příklad je níže v části Klient SDK.
Čtěte katalog, nastavení a stránky webu. Košík držte u sebe a u pokladny ho předejte platformě jednorázovým kódem (část Košík a pokladna).
Frontend nasadíte na vlastní hosting. Portican ho nehostuje ani nespouští; adresa webu musí souhlasit s adresou, kterou jste zapsali u klíče.

Co klíč smí

Klíč frontendu smí jen veřejné dotazy ke čtení ze seznamu níže a jedinou mutaci odovzdajKosik. Každá jiná operace skončí chybou KLUC_FRONTENDU_OPERACIA.
Požadavek s klíčem ani požadavek ze zapsané adresy webu nenese relaci zákazníka. Kód partnera nezaloží košík Vendure, nevidí účet, objednávky, platby ani odkazy s tokenem.
Strop je 3 000 požadavků za minutu na klíč. Server partnera je pro platformu jedna adresa pro všechny návštěvníky, proto může adresu návštěvníka podepsat tajemstvím klíče v hlavičce x-portican-navstevnik (SDK to dělá, když zadáte adresaNavstevnika); stropy pak platí na návštěvníka. Bez podpisu platí vedle stropu klíče i strop na adresu serveru.
Při překročení stropu přijde chyba PRILIS_VELA_POZIADAVIEK s počtem sekund, které je třeba počkat. Špatný, zrušený nebo cizí klíč vrátí KLUC_FRONTENDU_NEPLATI. Obsluha klíč zruší v administraci a web přestane načítat produkty.
Klíč patří jen na server. Prohlížeč volá Shop API bez klíče, a to jen ze zapsané adresy webu (CORS). Klíč v kódu, který dostane prohlížeč, by mohl použít kdokoli.

Dotazy, které klíč povolí

Veřejný katalog a obsah obchodu. Nic o zákazníkovi, objednávce ani odkazech s tokenem. Seznam je seznamem povolených, ne zakázaných: nový dotaz pluginu není otevřený sám.

Z kódu platformy. Tento seznam se skládá přímo ze zdrojového kódu platformy a každé nasazení ověří, že s ním souhlasí.

activeChannel
availableCountries
collections
collection
facets
facet
products
product
search
storefrontSettings
schemaBlokov
strankyWebu
strankaWebu
suboroveStrankyObchodu
suborovaStrankaObchodu
pravneTextyObchodu
pravnyTextObchodu
vypisBlogu
clankyBlogu
clanokBlogu
adresyClankov
jazykyClanku
mapaClankov
akcioveProdukty
produktyPodlaId
najpredavanejsieProdukty
novinkyProdukty
odporucaniaKProduktu
vacsieVarianty
recenzieProduktu
socialnyDokazProduktu
nastavenieVypredanych
skryteProdukty
cenovePasma
presmerovaneKategorie
presmerovaneKarty
presmerovaniaObchodu
zobrazenieTrhu
sviatocneTerminy
blokyPartnera

Klient SDK

SDK je typovaný klient Shop API bez závislostí. Běží v Node 18 a novějším, v Cloudflare Workers, v Deno i v prohlížeči. Čte nastavení obchodu, kategorie, produkty, vyhledávání a stránky webu.

Chyby mají kód (kod), stav HTTP (stav) a při překročení stropu i cakajSekund. Hlavičky a kódy chyb v SDK souhlasí s jádrem platformy; hlídá to test balíčku.

Co SDK zatím neumí: právní texty obchodu přes Shop API a vykreslování bloků stránek a sekcí úvodní stránky. Ty si ve frontendu skládáte sami.

import { vytvorKlienta, ChybaObchodu } from '@portican/storefront';

const obchod = vytvorKlienta({
    adresaApi: process.env.PORTICAN_ADRESA_SHOP_API!, // Shop API obchodu
    tokenTrhu: process.env.PORTICAN_TOKEN_TRHU!,
    kluc: process.env.PORTICAN_KLUC_FRONTENDU, // len na serveri, nikdy v prehliadači
    jazyk: 'sk',
});

try {
    // Na serveri s adresou návštevníka, aby stropy platili na neho, nie na celý server.
    const produkt = await obchod.produkt('kytica-ruzi', { adresaNavstevnika: request.ip });
    const vysledky = await obchod.hladaj({ vyraz: 'ruže', take: 24 });
    const nastavenia = await obchod.nastavenia();
    const stranka = await obchod.stranka('o-nas');
} catch (e) {
    // Pri strope príde kód chyby so sekundami, ktoré treba počkať.
    if (e instanceof ChybaObchodu && e.strop) await pockaj(e.cakajSekund ?? 1);
    else throw e;
}

Košík a pokladna

Košík je seznam variant a množství ve vašem frontendu, nejvýše 50 řádků a 999 kusů jedné varianty. Větší košík platforma nepřevezme a nezaokrouhlí ho potichu: partner uvidí chybu.
U pokladny zavoláte odovzdajKosik. Dostanete jednorázový kód, který platí 10 minut a jednou. Předání může být nejvýše 120 za minutu na klíč nebo adresu webu.
Zákazník kód donese formulářem POST na /prevziat-kosik obchodu (nebo /<jazyk>/prevziat-kosik), nikdy v adrese. Pokladna košík převezme jen z webu, který ho předal, proto musí formulář odejít ze zapsané adresy webu.
Ceny, sklad, dopravu a slevy počítá platforma, ne váš kód. Varianta mimo obchod se odmítne hned při předání, vyprodaný kus při převzetí z košíku vypadne. Objednávku zakládá až pokladna v relaci zákazníka.

import { nacitajKosik, pridajDoKosika, ulozKosik, formularPokladne } from '@portican/storefront';

// Košík je zoznam variantov a množstiev u vás (localStorage, cookie, KV).
const kosik = pridajDoKosika(nacitajKosik(localStorage), variantId, 1);
ulozKosik(localStorage, kosik);

// Pri pokladni ho odovzdáte platforme; ceny, sklad a dopravu prepočíta ona.
const { kod } = await obchod.odovzdajDoPokladne(kosik);
const f = formularPokladne(kod, 'https://www.obchod-klienta.sk', 'sk');
// <form method="POST" action={f.action}><input type="hidden" name="kod" value={f.polia.kod} /></form>

Vzhled v souborech: příkazový řádek

Příkaz portican vzhlad stáhne vzhled obchodu (téma, podobu e-shopu, úvodní stránku, vlastní CSS a stránky webu) jako soubory, které si držíte v gitu, a nahraje je zpět jako koncept. Koncept si obchodník prohlédne v náhledu a zveřejní ho sám v administraci na obrazovce Verze vzhledu. Příkazový řádek nic nezveřejňuje.
Potřebuje API klíč s rozsahem Koncepty vzhledu (část Obchod › Integrace, viz Webhooky a API). Klíč patří do proměnné prostředí PORTICAN_API_KLUC, nikdy do příkazu: zůstal by v historii shellu. U obchodu s více trhy nastavte token trhu v PORTICAN_TRH.
verzie vypíše verze vzhledu, pull stáhne zveřejněnou (nebo zvolenou) verzi, push nahraje složku jako nový koncept a vypíše, kolik částí mění oproti živému vzhledu, nahlad vypíše odkaz na náhled, který platí hodinu. Balíček nesmí mít víc než 2 MB.
JSON soubory mají seřazené klíče a odsazení, takže diff v gitu ukáže jen skutečnou změnu. Příkazový řádek spustíte bez instalace přes npx @portican/cli vzhlad, nebo ho přidáte do projektu (npm install --save-dev @portican/cli).

export PORTICAN_API_KLUC="..."   # kľúč s rozsahom Vzhľad, nikdy v príkaze

portican vzhlad verzie
portican vzhlad pull --do vzhlad
portican vzhlad push --z vzhlad --nazov "Jesenná kampaň"
portican vzhlad nahlad

Schéma bloků

Shop API vydává dotaz schemaBlokov: strojově čitelný popis druhů bloků stránek a sekcí úvodní stránky s poli, typy, hranicemi délky a počtu, volbami a verzí. Podle ní zjistíte, jaká pole blok nese, aniž byste četli kód platformy.
Schéma je veřejné a jen ke čtení, stejné pro každý trh a bez údajů obchodu. Verze se zvyšuje s každou změnou polí, typů či hranic a potvrzuje ji otisk, takže poznáte, zda znáte právě tu verzi.
Dotaz schemaBlokov je v seznamu dotazů klíče frontendu výše, takže ho SDK může volat i s klíčem. Schéma je veřejná a stejná pro každý trh, proto klíč nic nového neodhalí.

Co platforma nedělá

Pokladna, přihlášení, účet zákazníka, platby a vrácení peněz jsou vždy na platformě. Frontend partnera k nim nemá přístup a platební údaje přes něj neprocházejí.
Portican frontend partnera nehostuje, nestaví ani nenasazuje. Pro vlastní frontend platforma dnes dává klíč, Shop API, SDK a předání košíku.
Texty a obrázky, které má měnit obchodník, ve frontendu nepište napevno: čtěte je z nastavení, stránek webu a produktů, které obchodník upravuje v administraci.