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ě.

Rychlý začátek

Klient bez programování. Vzhled obchodu si klient mění sám v administraci: barvy, písmo a šablonu e-shopu v části Obchod › Vzhled, stránky webu v části Obsah › Stránky webu. Změnu si prohlédne v náhledu, zveřejní ji na obrazovce Verze vzhledu a jedním kliknutím se vrátí na předchozí verzi. Totéž umí asistent v administraci.

Partner se startérem. Startér @portican/create se připravuje k vydání na veřejném npm; dokud není vydaný, npm create @portican@latest nefunguje. Startér založí frontend nad SDK s bloky platformy, košíkem předaným do pokladny, právními texty, lištou souhlasu a SEO.

Partner se šablonou. Vzhled měníte v souborech a nahráváte ho příkazem portican vzhlad push jako koncept; zveřejní ho obchodník. Hotový vzhled uložíte do knihovny šablon a u dalšího klienta ho vyberete už při registraci jeho obchodu.

Nahrání a hosting. Hotový vlastní frontend nahrajete jako statický web na hosting Porticanu příkazem portican frontend deploy (část Nahrání frontendu), nebo ho provozujete u sebe.

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. Na hosting Porticanu ji nahrajete jako hotový statický web příkazem portican frontend deploy: hosting jen vydává soubory a vykreslování na serveru (SSR) tam neběží. Frontend s SSR provozujete na vlastním hostingu. Viz části Klient SDK a Nahrání frontendu 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) nebo z vlastních bloků se schématem obsahu (část Bloky partnera): administrace upravuje jen to, co platforma zná, a vlastní blok zná podle schématu, které nahrajete.

Postup od klíče po nasazený frontend

Frontend na vlastním hostingu potřebuje klíč frontendu: obsluha obchodu ho vytvoří v administraci v části Obchod › Integrace, 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.
SDK @portican/storefront se připravuje k vydání na veřejném npm; dokud není vydané, npm install @portican/storefront nefunguje. Balíček nebude mít závislosti a každou verzi bude zveřejňovat jen CI Porticanu z hlavní větve.
Statický web (i na hostingu Porticanu) vytvoří klienta v prohlížeči bez klíče. Klíč patří jen na váš vlastní server, když frontend vykreslujete na serveru mimo Portican. 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).
Hotový statický frontend nahrajete na hosting Porticanu (část Nahrání frontendu); adresu Shop API, token trhu a jazyk mu zapíše platforma. Frontend na vlastním hostingu musí běžet na adrese, 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 umí kromě čtení: právní texty obchodu (pravneTexty, pravnyText), schéma bloků platformy (schemaBlokov), čtení bloků stránek, obsah vlastních bloků partnera (blokyPartnera, volá dotaz blokyPartnera a vrátí verzia, odtlacok, jazyk a bloky, část Čtení obsahu bloku a webhook), pomocníky pro SEO, souhlas a předání košíku. Co SDK nedělá: bloky nevykresluje, kreslíte je vy.

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

// Statický web (aj na hostingu Porticanu): v prehliadači, bez kľúča, zo zapísanej adresy webu.
// Adresu Shop API, token trhu a jazyk zapíše hosting Porticanu do /portican-env.json.
const premenne = await fetch('/portican-env.json').then(r => r.json());
const obchod = vytvorKlienta({
    adresaApi: premenne.PORTICAN_ADRESA_SHOP_API, // Shop API obchodu
    tokenTrhu: premenne.PORTICAN_TOKEN_TRHU,
    jazyk: premenne.PORTICAN_JAZYK,
});
// Vlastný server mimo Porticanu (SSR): vytvorServerovehoKlienta z @portican/storefront/server
// s kluc: process.env.PORTICAN_KLUC_FRONTENDU a pri dopyte { adresaNavstevnika }, aby stropy platili na návštevníka.

try {
    const produkt = await obchod.produkt('kytica-ruzi');
    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 @portican/cli se připravuje k vydání na veřejném npm; dokud není vydaný, npx @portican/cli vzhlad ani npm install --save-dev @portican/cli nefunguje.

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

Soubory ve složce vzhlad/

pull tyto soubory zapíše, push je nahraje jako koncept. Část, jejíž soubor ve složce chybí, koncept nenese.

Soubor	Co nese
`vzhlad.json`	Verze balíčku a verze vzhledu, ze které se stahovalo. Píše ho `pull`, ručně ho neměňte.
`tema.json`	Barvy a písma tématu.
`podoba-eshopu.json`	Podoba e-shopu a šablona.
`uvodna-strana.json`	Sekce úvodní stránky.
`bloky-partnera.json`	Schéma bloků vlastního frontendu partnera (viz část Bloky partnera níže).
`sekcie-stranok.json`	Pořadí, zapnutí a pás sekcí stránek (viz část Sekce pod kartou produktu).
`navigacia.json`	Nabídka v hlavičce a patička obchodu.
`vlastne-css.json`	Zapnutí a verze vlastního CSS.
`vlastne.css`	Vlastní CSS jako skutečný soubor `.css`.
`stranky/<jazyk>/<slug>.json`	Stránky webu, jeden soubor na stránku ve složce jazyka. Lomítko v adrese stránky je v názvu souboru `~`: stránka `o-nas/tim` je soubor `o-nas~tim.json`.

Sekce pod kartou produktu

Soubor sekcie-stranok.json mění pořadí sekcí, které obchod platformy kreslí pod kartou produktu, ne jejich obsah. Každá sekce má zapnuta (ano, nebo ne) a pozadie (platno, pas). Fotky a údaje produktu zůstávají nahoře, patří k nákupu, ne k sekci.
Sekce jsou z uzavřeného slovníku platformy: zalozky, dovera, recenzie, odporucania, podobne, otazky, otazkyProduktu, tabulkaVelkosti, bezpecnostVyrobku, nedavno, podkategorie, filtre, vypis, popis, uzavierka, odmeny, zasielky, zlavovykod, body, zdielanie. Neznámá sekce a druhý výskyt téže sekce se zahodí. Sekce, kterou soubor nezmiňuje, zůstane na svém místě a nová sekce, kterou platforma přidá později, přijde vypnutá.
Koncept bez tohoto souboru pořadí nemění: převezme to, které je naživo. Naživo jde, až když koncept zveřejní obchodník, ne příkazový řádek. Registr zná stránky produkt, kategoria, kosik; další přibudou, až je platforma přidá, a tato část je vypíše sama.

{
  "produkt": [
    {
      "druh": "recenzie",
      "zapnuta": true,
      "pozadie": "pas"
    },
    {
      "druh": "zalozky",
      "zapnuta": true,
      "pozadie": "platno"
    },
    {
      "druh": "nedavno",
      "zapnuta": false,
      "pozadie": "platno"
    }
  ]
}

`produkt`

Stránka produktu: sekce pod kartou v dnešním pořadí.

Sekce	Co kreslí	Výchozí stav
`zalozky`	Popis, parametry, soubory a odpověď o vrácení v záložkách; kreslí se jen u podoby produktu `zalozky`.	zapnutá
`dovera`	Odznaky důvěry; kreslí se jen tehdy, když má obchod zapnutý aspoň jeden odznak.	zapnutá
`recenzie`	Recenze produktu.	zapnutá
`odporucania`	Spárovaná nabídka pod kartou.	zapnutá
`podobne`	Podobné produkty z kategorie.	zapnutá
`otazky`	Časté otázky obchodu, stejné jako na stránce Kontakt; odpověď o vrácení je tohoto zboží.	zapnutá
`otazkyProduktu`	Otázky zákazníků k produktu a odpovědi obchodu; výchozí stav vypnuto.	vypnutá
`tabulkaVelkosti`	Tabulka velikostí produktu; výchozí stav vypnuto.	vypnutá
`bezpecnostVyrobku`	Výrobce a bezpečnostní údaje podle GPSR; výchozí stav vypnuto.	vypnutá
`nedavno`	Pás naposledy prohlížených produktů.	zapnutá

`kategoria`

Stránka kategorie: sekce nad výpisem a výpis v dnešním pořadí.

Sekce	Co kreslí	Výchozí stav
`podkategorie`	Podkategorie aktuální kategorie.	zapnutá
`filtre`	Filtry výpisu kategorie.	zapnutá
`vypis`	Výpis produktů kategorie.	zapnutá
`popis`	Popis kategorie.	zapnutá

`kosik`

Košík: sekce kolem souhrnu objednávky, pokladna se jimi nemění.

Sekce	Co kreslí	Výchozí stav
`odporucania`	Spárovaná nabídka pod kartou.	zapnutá
`uzavierka`	Věta o tom, dokdy je třeba objednat na nejbližší doručení.	zapnutá
`odmeny`	Odměny za hodnotu nákupu v košíku.	zapnutá
`zasielky`	Rozdělení objednávky do více zásilek v košíku.	zapnutá
`zlavovykod`	Pole pro slevový kód.	zapnutá
`body`	Věrnostní body v košíku.	zapnutá
`zdielanie`	Odkaz pro sdílení košíku.	zapnutá

Pozadí sekce

platno: sekce na plátně stránky, jako dosud.
pas: sekce v pásu v ploše tématu přes celou šířku, jako bloky webu.

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í.

Bloky partnera: schéma obsahu

Vlastní frontend kreslí vlastní bloky, ale texty, obrázky a odkazy v nich nepíšete napevno. Mění je obchodník v administraci na obrazovce Obchod › Bloky partnera, nebo asistent. Proto každý blok nese schéma obsahu: pole, jejich typy, hranice a výchozí hodnoty. Z něj platforma skládá formulář a podle něj ověřuje uložený obsah. Blok bez jediného pole platforma nepřijme (nález bez-schemy-obsahu), protože jeho texty by zůstaly v kódu.
Schéma píšete do souboru bloky-partnera.json ve vzhledu (viz část Vzhled v souborech) a nahrajete ji s konceptem příkazem portican vzhlad push. Naživo jde, až když obchodník verzi vzhledu zveřejní. Při každé změně polí zvyšte verzia: platforma odmítne změněné schéma se stejnou verzí, jakou má obchod naživo.
Typy polí: text, viacriadkovy, adresa, obrazok, cislo, volba, prepinac, zoznam, produkt, kolekcia, stranka. Text má výchozí maximum 200 znaků (strop 1 000), víceřádkový text 2 000 (10 000). Číslo má hranice najmenej a najviac, volba seznam hodnoty, seznam pole polozky (bez dalšího seznamu) a najviac položek: výchozí počet 20, nejvýše 100.
Hranice schématu: nejvýše 60 bloků, 40 polí v bloku i v položce seznamu, schéma nejvýše 256 KiB a obsah jednoho bloku v jednom jazyce nejvýše 64 KiB. Kód bloku je jako slug (uvod-pas), jméno pole jako identifikátor v JavaScriptu (nadpis); názvy pro obsluhu můžete dát i v dalších jazycích (nazvy).
Výchozí hodnota je to, co web ukáže, dokud obchodník pole nevyplní, a také po tlačítku Vrátit výchozí hodnotu partnera. Uložený obsah se při změně schématu nemaže: pole, které ze schématu zmizelo, frontend nedostane, a když se schéma vrátí, text je zpět.

{
  "verzia": 1,
  "bloky": [
    {
      "kod": "uvod-pas",
      "nazov": "Úvodný pás",
      "nazvy": {
        "cs": "Úvodní pás",
        "en": "Hero"
      },
      "polia": [
        {
          "pole": "nadpis",
          "typ": "text",
          "nazov": "Nadpis",
          "najviacZnakov": 80,
          "predvolba": "Kvety na každý deň"
        },
        {
          "pole": "fotka",
          "typ": "obrazok",
          "nazov": "Fotka"
        },
        {
          "pole": "tlacidlo",
          "typ": "adresa",
          "nazov": "Odkaz tlačidla",
          "predvolba": "/kategorie"
        },
        {
          "pole": "vyhody",
          "typ": "zoznam",
          "nazov": "Výhody",
          "najviac": 4,
          "polozky": [
            {
              "pole": "text",
              "typ": "text",
              "nazov": "Výhoda",
              "najviacZnakov": 60
            }
          ]
        }
      ]
    }
  ]
}

Čtení obsahu bloku a webhook

Obsah bloků čte frontend dotazem Shop API blokyPartnera (příklad níže); je mezi dotazy povolenými klíčem frontendu. Odpověď má verzia a odtlacok schématu, jazyk a bloky podle kódu bloku s hodnotami všech polí: chybějící nebo neplatnou hodnotu nahradí výchozí hodnota partnera. Bez nahraného a zveřejněného schématu jsou verzia a odtlacok null a bloky prázdné.
Jazyk je nepovinný: bez něj platí jazyk požadavku, jazyk mimo trh dostane výchozí jazyk trhu, takže frontend vždy něco nakreslí. Podle otisku frontend pozná, zda čte schéma, se kterým byl postaven.
SDK @portican/storefront dotaz blokyPartnera dnes volat neumí. Zavoláte ho holým GraphQL s hlavičkami klíče a trhu jako ostatní dotazy.
O změně obsahu se frontend dozví webhookem obsah.zmeneny: pole znacky v jeho těle obsahuje bloky-partnera, když obchodník změnil obsah bloků nebo se změnilo jejich schéma. Webhook se podepisuje hlavičkou portican-podpis s tolerancí 300 sekund a při neúspěchu se opakuje; hlavičky, ověření podpisu a opakování jsou stejné jako u ostatních událostí, viz Webhooky a API. Adresu webhooku zapíše obchodník na obrazovce Integrace.

POST {adresa Shop API obchodu}
vendure-token: {token trhu}
portican-kluc-frontendu: {kľúč frontendu}      # len na serveri

{ "query": "{ blokyPartnera(jazyk: \"sk\") }" }

# Odpoveď (pole blokyPartnera v data):
{
  "verzia": 1,
  "odtlacok": "9f2c…",
  "jazyk": "sk",
  "bloky": {
    "uvod-pas": {
      "nadpis": "Kvety na každý deň",
      "fotka": null,
      "tlacidlo": "/kategorie",
      "vyhody": [{ "text": "Doručenie v deň objednávky" }]
    }
  }
}

Nahrání frontendu

Hotový frontend (ne zdrojový kód) nahráváte z vlastního CI příkazem portican frontend deploy. Příkaz přečte složku (výchozí dist), pošle ji platformě jako jednu verzi a vypíše adresu jejího náhledu. Naživo se nic nezmění.
Hosting Porticanu vydává jen statický výstup: index.html, skripty, styly a obrázky. Na serveru neběží žádný kód partnera, takže tam není vykreslování na serveru (SSR), serverové funkce ani API cesty. Web se skládá v prohlížeči a Shop API volá bez klíče. Adresu Shop API trhu, token trhu, adresu pokladny a webu, jazyk a doménu obchodu zapíše platforma do souboru /portican-env.json vedle index.html; jedna verze tak běží na každém trhu, kam ji vydáte. Startér @portican/create takový web sestaví sám.
V kořeni složky musí být manifest portican.json: verzia (2), assety (složka webu v balíku, s index.html) a volitelně hostitelia. Mimo složku webu smí být jen manifest, package-lock.json a bloky-partnera.json (schéma vlastních bloků, část Bloky partnera). Balík s workerem (manifest verze 1 s polem hlavny) platforma odmítne větou, co změnit.
Potřebujete API klíč s rozsahem Nasazení frontendu (nasadenie-frontendu; Obchod › Integrace, viz Webhooky a API), uložený v tajemstvích CI jako PORTICAN_API_KLUC. Takový klíč umí verzi jen nahrát a přečíst seznam verzí (portican frontend verzie); nezveřejní ji ani nevrátí.
Platforma nahrání zastaví, když: chybí manifest nebo má jinou verzi, chybí index.html nebo je mimo složku webu soubor, který tam nepatří, chybí package-lock.json (CLI ho umí doplnit přes --zamok), balík má známou vysokou zranitelnost, verze přesahuje 25 MB nebo 2 000 souborů (jedno nahrání nejvýše 14 MiB), nebo má vlastní blok bez schématu obsahu. Skryté soubory (.env) a zdrojové mapy do balíku nedávejte. Nálezy kontroly CLI vypíše. Trh může mít najednou nejvýše 10 nezveřejněných verzí.
Web smí z prohlížeče volat Shop API obchodu a hostitele z pole hostitelia v manifestu (nejvýše 10, jen https, bez hvězdičky, nikdy adresa IP ani doména platformy); ostatní zablokuje zásada obsahu (CSP), kterou hosting přidá ke každé stránce. Zásada nepustí vložený <script> v HTML, skripty patří do souborů. Statické soubory nesmí ležet pod cestami, které na doméně obchodu obsluhuje platforma (/shop-api, /assets, /health, /na-stiahnutie, /sukromne-subory, /_next, /api, /.well-known, /robots.txt, /sitemap, /llms.txt, /feed, /ucp): takový balík se nenahraje.
Vyhledávače. Statický web pošle pro každou adresu stejný index.html a obsah se vykreslí až v prohlížeči. Google a Bing ho vykreslí a titulky, popisy, kanonické adresy a strukturovaná data (JSON-LD z pomocníků SDK) přečtou, jen později; nástroje, které skript nespouštějí (náhledy odkazů, část robotů), uvidí prázdnou stránku. Mapu stránek, feedy, robots.txt a llms.txt vydává na doméně obchodu platforma z dat obchodu. Stránky, které se mění zřídka, můžete předkreslit při buildu do hotového HTML; obsah, který mění obchodník, se pak ukáže až po dalším buildu.
Verze má stav koncept, náhled, zveřejněná nebo archiv; na trhu je zveřejněná nejvýše jedna. Zveřejnění dělá obchodník, ne klíč: v administraci ho provede asistent („zveřejni nový frontend“), který umí vrátit i předchozí verzi nebo šablonu platformy. Návrat na šablonu je jeden krok.
Dokud platforma hosting frontendů na svém serveru nezapne, nahrání skončí větou o nezapojeném hostingu a nic se nezapíše. Frontend na vlastním hostingu s klíčem frontendu funguje bez toho dál.

// portican.json v koreni priečinka balik/
{
  "verzia": 2,
  "assety": "verejne",
  "hostitelia": [
    "https://cms.partner.sk"
  ]
}

// balik/verejne/index.html, balik/verejne/static/…, balik/package-lock.json

# v CI partnera:
npm run build                    # statický web (napríklad vite build) a balík v balik/
export PORTICAN_API_KLUC="..."   # kľúč s rozsahom Nasadenie frontendu
portican frontend deploy --z balik --nazov "$GITHUB_SHA"
portican frontend verzie

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 nestaví ani nespouští: stavíte ho ve vlastním CI a nahrajete hotový statický web. Vykreslování na serveru (SSR) a serverový kód partnera hosting Porticanu nepodporuje; frontend, který je potřebuje, běží na vašem hostingu s klíčem frontendu.
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.