Frontend partnera

Dizajn a frontend pre klienta nemusíte skladať zo šablóny platformy. Môžete meniť vzhľad v súboroch alebo postaviť vlastnú aplikáciu nad Shop API. Pokladňa, platby a účet zákazníka ostávajú vždy na platforme.

Rýchly začiatok

Klient bez programovania. Vzhľad obchodu si klient mení sám v administrácii: farby, písmo a šablónu e-shopu v časti Obchod › Vzhľad, stránky webu v časti Obsah › Stránky webu. Zmenu si pozrie v náhľade, zverejní ju na obrazovke Verzie vzhľadu a jedným klikom sa vráti na predošlú verziu. To isté vie urobiť asistent v administrácii.

Partner so štartérom. Štartér @portican/create sa pripravuje na vydanie na verejnom npm; kým nie je vydaný, npm create @portican@latest nefunguje. Štartér založí frontend nad SDK s blokmi platformy, košíkom odovzdaným do pokladne, právnymi textami, lištou súhlasu a SEO.

Partner so šablónou. Vzhľad meníte v súboroch a nahrávate ho príkazom portican vzhlad push ako koncept; zverejní ho obchodník. Hotový vzhľad uložíte do knižnice šablón a pri ďalšom klientovi ho vyberiete už pri registrácii jeho obchodu.

Nahratie a hosting. Hotový vlastný frontend ako statický web nahráte na hosting Porticanu príkazom portican frontend deploy (časť Nahratie frontendu), alebo ho prevádzkujete u seba.

Dve cesty

Vzhľad v súboroch. Obchod beží na šablóne platformy a vy mu meníte tému, podobu e-shopu, úvodnú stranu, vlastné CSS a stránky webu. Súbory držíte v gite a nahrávate ich príkazom portican vzhlad ako koncept; zverejní ho obchodník. Viď časť Vzhľad v súboroch nižšie.
Vlastný frontend. Napíšete vlastnú aplikáciu, ktorá číta katalóg a obsah obchodu cez Shop API pomocou SDK @portican/storefront. Na hosting Porticanu ju nahráte ako hotový statický web príkazom portican frontend deploy: hosting vydáva len súbory a vykresľovanie na serveri (SSR) tam nebeží. Frontend so SSR prevádzkujete na vlastnom hostingu. Viď časti Klient SDK a Nahratie frontendu nižšie.
Obe cesty môžete kombinovať s tým, čo opisuje Háčiky v značkovaní, Bloky a ich polia a Predvoľba webu. Obsah, ktorý má meniť obchodník, čítajte z obchodu (nastavenia, stránky webu, produkty) alebo z vlastných blokov so schémou obsahu (časť Bloky partnera): administrácia upravuje len to, čo platforma pozná, a vlastný blok pozná podľa schémy, ktorú nahráte.

Postup od kľúča po nasadený frontend

Frontend na vlastnom hostingu potrebuje kľúč frontendu: obsluha obchodu ho vytvorí v administrácii v časti Obchod › Integrácie, pomenuje ho a zapíše adresy webu, z ktorých bude volať prehliadač. Adresa je https bez cesty a nesmie patriť platforme ani jej subdoméne; najviac 5 adries na kľúč a 5 kľúčov na trh. Kľúč sa ukáže len raz.
Na tej istej obrazovke je token trhu a adresa Shop API obchodu s tlačidlom na skopírovanie; adresu skladá server z domény trhu, nehádajte ju z príkladov. Kľúč platí len s tokenom svojho trhu, v hlavičke portican-kluc-frontendu spolu s hlavičkou vendure-token.
SDK @portican/storefront sa pripravuje na vydanie na verejnom npm; kým nie je vydané, npm install @portican/storefront nefunguje. Balík nebude mať závislosti a každú verziu bude zverejňovať len CI Porticanu z hlavnej vetvy.
Statický web (aj na hostingu Porticanu) vytvorí klienta v prehliadači bez kľúča. Kľúč patrí len na váš vlastný server, keď frontend vykresľujete na serveri mimo Porticanu. Príklad je nižšie v časti Klient SDK.
Čítajte katalóg, nastavenia a stránky webu. Košík držte u seba a pri pokladni ho odovzdajte platforme jednorazovým kódom (časť Košík a pokladňa).
Hotový statický frontend nahráte na hosting Porticanu (časť Nahratie frontendu); adresu Shop API, token trhu a jazyk mu zapíše platforma. Frontend na vlastnom hostingu musí bežať na adrese, ktorú ste zapísali pri kľúči.

Čo kľúč smie

Kľúč frontendu smie len verejné dopyty na čítanie zo zoznamu nižšie a jedinú mutáciu odovzdajKosik. Každá iná operácia skončí chybou KLUC_FRONTENDU_OPERACIA.
Požiadavka s kľúčom ani požiadavka zo zapísanej adresy webu nenesie reláciu zákazníka. Kód partnera nezaloží košík Vendure, nevidí účet, objednávky, platby ani odkazy s tokenom.
Strop je 3 000 požiadaviek za minútu na kľúč. Server partnera je pre platformu jedna adresa pre všetkých návštevníkov, preto môže adresu návštevníka podpísať tajomstvom kľúča v hlavičke x-portican-navstevnik (SDK to robí, keď zadáte adresaNavstevnika); stropy potom platia na návštevníka. Bez podpisu platí popri strope kľúča aj strop na adresu servera.
Pri strope príde chyba PRILIS_VELA_POZIADAVIEK so sekundami, ktoré treba počkať. Zlý, zrušený alebo cudzí kľúč vráti KLUC_FRONTENDU_NEPLATI. Obsluha kľúč zruší v administrácii a web prestane načítavať produkty.
Kľúč patrí len na server. Prehliadač volá Shop API bez kľúča, a to len zo zapísanej adresy webu (CORS). Kľúč v kóde, ktorý dostane prehliadač, by mohol použiť ktokoľvek.

Dopyty, ktoré kľúč povolí

Verejný katalóg a obsah obchodu. Nič o zákazníkovi, objednávke ani odkazoch s tokenom. Zoznam je zoznam povolených, nie zakázaných: nový dopyt pluginu nie je otvorený sám.

Z kódu platformy. Tento zoznam sa skladá priamo zo zdrojového kódu platformy a každé nasadenie overí, že s ním sedí.

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í. Beží v Node 18 a novšom, v Cloudflare Workers, v Deno aj v prehliadači. Číta nastavenia obchodu, kategórie, produkty, hľadanie a stránky webu.

Chyby majú kód (kod), stav HTTP (stav) a pri strope aj cakajSekund. Hlavičky a kódy chýb v SDK sa zhodujú s jadrom platformy; stráži to test balíka.

Čo SDK vie okrem čítania: právne texty obchodu (pravneTexty, pravnyText), schému blokov platformy (schemaBlokov), čítanie blokov stránok, obsah vlastných blokov partnera (blokyPartnera, volá dopyt blokyPartnera a vráti verzia, odtlacok, jazyk a bloky, časť Čítanie obsahu bloku a webhook), pomocníkov na SEO, súhlas a odovzdanie košíka. Čo SDK nerobí: bloky nevykresľuje, kreslíte ich 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 pokladňa

Košík je zoznam variantov a množstiev vo vašom frontende, najviac 50 riadkov a 999 kusov jedného variantu. Väčší košík platforma neodovzdá a nezaokrúhli ho potichu: partner uvidí chybu.
Pri pokladni zavoláte odovzdajKosik. Dostanete jednorazový kód, ktorý platí 10 minút a raz. Odovzdaní môže byť najviac 120 za minútu na kľúč alebo adresu webu.
Zákazník kód donesie formulárom POST na /prevziat-kosik obchodu (alebo /<jazyk>/prevziat-kosik), nikdy v adrese. Pokladňa košík prevezme len z webu, ktorý ho odovzdal, preto formulár musí odísť zo zapísanej adresy webu.
Ceny, sklad, dopravu a zľavy počíta platforma, nie váš kód. Variant mimo obchodu sa odmietne hneď pri odovzdaní, vypredaný kus pri prevzatí z košíka vypadne. Objednávku zakladá až pokladňa v relácii 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>

Vzhľad v súboroch: príkazový riadok

Príkaz portican vzhlad stiahne vzhľad obchodu (tému, podobu e-shopu, úvodnú stranu, vlastné CSS a stránky webu) ako súbory, ktoré si držíte v gite, a nahrá ich späť ako koncept. Koncept si obchodník pozrie v náhľade a zverejní ho sám v administrácii na obrazovke Verzie vzhľadu. Príkazový riadok nič nezverejňuje.
Potrebuje API kľúč s rozsahom Koncepty vzhľadu (časť Obchod › Integrácie, viď Webhooky a API). Kľúč patrí do premennej prostredia PORTICAN_API_KLUC, nikdy do príkazu: ostal by v histórii shellu. Pri obchode s viacerými trhmi nastavte token trhu v PORTICAN_TRH.
verzie vypíše verzie vzhľadu, pull stiahne zverejnenú (alebo zvolenú) verziu, push nahrá priečinok ako nový koncept a vypíše, koľko častí mení oproti živému vzhľadu, nahlad vypíše odkaz na náhľad, ktorý platí hodinu. Balík nesmie mať viac než 2 MB.
JSON súbory majú zoradené kľúče a odsadenie, takže diff v gite ukáže len skutočnú zmenu. Príkazový riadok @portican/cli sa pripravuje na vydanie na verejnom npm; kým nie je 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

Súbory v priečinku vzhlad/

pull zapíše tieto súbory, push ich nahrá ako koncept. Časť, ktorej súbor v priečinku chýba, koncept nenesie.

Súbor	Čo nesie
`vzhlad.json`	Verzia balíka a verzia vzhľadu, z ktorej sa sťahovalo. Píše ho `pull`, ručne ho nemeňte.
`tema.json`	Farby a písma témy.
`podoba-eshopu.json`	Podoba e-shopu a šablóna.
`uvodna-strana.json`	Sekcie úvodnej strany.
`bloky-partnera.json`	Schéma blokov vlastného frontendu partnera (viď časť Bloky partnera nižšie).
`sekcie-stranok.json`	Poradie, zapnutie a pás sekcií stránok (viď časť Sekcie pod kartou produktu).
`navigacia.json`	Ponuka v hlavičke a pätička obchodu.
`vlastne-css.json`	Zapnutie a verzia vlastného CSS.
`vlastne.css`	Vlastné CSS ako skutočný súbor `.css`.
`stranky/<jazyk>/<slug>.json`	Stránky webu, jeden súbor na stránku v priečinku jazyka. Lomka v adrese stránky je v mene súboru `~`: stránka `o-nas/tim` je súbor `o-nas~tim.json`.

Sekcie pod kartou produktu

Súbor sekcie-stranok.json mení poradie sekcií, ktoré obchod platformy kreslí pod kartou produktu, nie ich obsah. Každá sekcia má zapnuta (áno alebo nie) a pozadie (platno, pas). Fotky a údaje produktu ostávajú hore, patria k nákupu, nie k sekcii.
Sekcie sú z uzavretého slovníka platformy: zalozky, dovera, recenzie, odporucania, podobne, otazky, otazkyProduktu, tabulkaVelkosti, bezpecnostVyrobku, nedavno, podkategorie, filtre, vypis, popis, uzavierka, odmeny, zasielky, zlavovykod, body, zdielanie. Neznáma sekcia a druhý výskyt tej istej sekcie sa zahodia. Sekcia, ktorú súbor nespomína, ostane na svojom mieste a nová sekcia, ktorú platforma pridá neskôr, príde vypnutá.
Koncept bez tohto súboru poradie nemení: preberie to, ktoré je naživo. Naživo ide, až keď koncept zverejní obchodník, nie príkazový riadok. Register pozná stránky produkt, kategoria, kosik; ďalšie pribudnú, keď ich platforma pridá, a táto časť ich 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: sekcie pod kartou v dnešnom poradí.

Sekcia	Čo kreslí	Predvolene
`zalozky`	Popis, parametre, súbory a odpoveď o vrátení v záložkách; kreslí sa len pri podobe produktu `zalozky`.	zapnutá
`dovera`	Odznaky dôvery; kreslia sa len vtedy, keď má obchod zapnutý aspoň jeden odznak.	zapnutá
`recenzie`	Recenzie produktu.	zapnutá
`odporucania`	Spárovaná ponuka pod kartou.	zapnutá
`podobne`	Podobné produkty z kategórie.	zapnutá
`otazky`	Časté otázky obchodu, tie isté ako na stránke Kontakt; odpoveď o vrátení je tohto tovaru.	zapnutá
`otazkyProduktu`	Otázky zákazníkov k produktu a odpovede obchodu; predvolene vypnutá.	vypnutá
`tabulkaVelkosti`	Tabuľka veľkostí produktu; predvolene vypnutá.	vypnutá
`bezpecnostVyrobku`	Výrobca a bezpečnostné údaje podľa GPSR; predvolene vypnutá.	vypnutá
`nedavno`	Pás naposledy prezeraných produktov.	zapnutá

`kategoria`

Stránka kategórie: sekcie nad výpisom a výpis v dnešnom poradí.

Sekcia	Čo kreslí	Predvolene
`podkategorie`	Podkategórie aktuálnej kategórie.	zapnutá
`filtre`	Filtre výpisu kategórie.	zapnutá
`vypis`	Výpis produktov kategórie.	zapnutá
`popis`	Popis kategórie.	zapnutá

`kosik`

Košík: sekcie okolo súhrnu objednávky, pokladňa sa nimi nemení.

Sekcia	Čo kreslí	Predvolene
`odporucania`	Spárovaná ponuka pod kartou.	zapnutá
`uzavierka`	Veta o tom, dokedy treba objednať na najbližšie doručenie.	zapnutá
`odmeny`	Odmeny za hodnotu nákupu v košíku.	zapnutá
`zasielky`	Rozdelenie objednávky na viac zásielok v košíku.	zapnutá
`zlavovykod`	Pole na zľavový kód.	zapnutá
`body`	Vernostné body v košíku.	zapnutá
`zdielanie`	Odkaz na zdieľanie košíka.	zapnutá

Pozadie sekcie

platno: sekcia na plátne stránky, ako doteraz.
pas: sekcia v páse v ploche témy cez celú šírku, ako bloky webu.

Schéma blokov

Shop API vydáva dopyt schemaBlokov: strojovo čitateľný popis druhov blokov stránok a sekcií úvodnej strany s poľami, typmi, hranicami dĺžky a počtu, voľbami a verziou. Podľa nej viete skontrolovať, aké polia blok nesie, bez čítania kódu platformy.
Schéma je verejná a len na čítanie, rovnaká pre každý trh a bez údajov obchodu. Verzia sa zvyšuje s každou zmenou polí, typov či hraníc a potvrdzuje ju odtlačok, takže viete zistiť, či poznáte práve tú verziu.
Dopyt schemaBlokov je v zozname dopytov kľúča frontendu vyššie, takže ho SDK môže volať aj s kľúčom. Schéma je verejná a rovnaká pre každý trh, preto kľúč nič nové neodhalí.

Bloky partnera: schéma obsahu

Vlastný frontend kreslí vlastné bloky, no texty, obrázky a odkazy v nich nepíšete natvrdo. Mení ich obchodník v administrácii na obrazovke Obchod › Bloky partnera, alebo asistent. Preto každý blok nesie schému obsahu: polia, ich typy, hranice a predvoľby. Z nej platforma skladá formulár a podľa nej overuje uložený obsah. Blok bez jediného poľa platforma neprijme (nález bez-schemy-obsahu), lebo jeho texty by ostali v kóde.
Schému píšete do súboru bloky-partnera.json vo vzhľade (viď časť Vzhľad v súboroch) a nahráte ju s konceptom príkazom portican vzhlad push. Naživo ide, až keď obchodník verziu vzhľadu zverejní. Pri každej zmene polí zvýšte verzia: platforma odmietne zmenenú schému s tou istou verziou, akú má obchod naživo.
Typy polí: text, viacriadkovy, adresa, obrazok, cislo, volba, prepinac, zoznam, produkt, kolekcia, stranka. Text má predvolene najviac 200 znakov (strop 1 000), viacriadkový text 2 000 (10 000). Číslo má hranice najmenej a najviac, voľba zoznam hodnoty, zoznam polia polozky (bez ďalšieho zoznamu) a najviac položiek: predvolene 20, najviac 100.
Hranice schémy: najviac 60 blokov, 40 polí v bloku aj v položke zoznamu, schéma najviac 256 KiB a obsah jedného bloku v jednom jazyku najviac 64 KiB. Kód bloku je ako slug (uvod-pas), meno poľa ako identifikátor v JavaScripte (nadpis); názvy pre obsluhu môžete dať aj v ďalších jazykoch (nazvy).
Predvoľba je to, čo web ukáže, kým obchodník pole nevyplní, aj po tlačidle Vrátiť predvoľbu partnera. Uložený obsah sa pri zmene schémy nemaže: pole, ktoré zo schémy zmizlo, frontend nedostane, a keď sa schéma vráti, text je späť.

{
  "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
            }
          ]
        }
      ]
    }
  ]
}

Čítanie obsahu bloku a webhook

Obsah blokov číta frontend dopytom Shop API blokyPartnera (príklad nižšie); je medzi dopytmi povolenými kľúčom frontendu. Odpoveď má verzia a odtlacok schémy, jazyk a bloky podľa kódu bloku s hodnotami všetkých polí: chýbajúcu alebo neplatnú hodnotu nahradí predvoľba partnera. Bez nahratej a zverejnenej schémy sú verzia a odtlacok null a bloky prázdne.
Jazyk je nepovinný: bez neho platí jazyk požiadavky, jazyk mimo trhu dostane predvolený jazyk trhu, takže frontend vždy niečo nakreslí. Podľa odtlačku frontend pozná, či číta schému, s ktorou bol postavený.
SDK @portican/storefront dopyt blokyPartnera dnes volať nevie. Zavoláte ho holým GraphQL s hlavičkami kľúča a trhu ako ostatné dopyty.
O zmene obsahu sa frontend dozvie webhookom obsah.zmeneny: pole znacky v jeho tele obsahuje bloky-partnera, keď obchodník zmenil obsah blokov alebo sa zmenila ich schéma. Webhook sa podpisuje hlavičkou portican-podpis s toleranciou 300 sekúnd a pri neúspechu sa opakuje; hlavičky, overenie podpisu a opakovanie sú rovnaké ako pri ostatných udalostiach, viď Webhooky a API. Adresu webhooku zapíše obchodník na obrazovke Integrácie.

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" }]
    }
  }
}

Nahratie frontendu

Hotový frontend (nie zdrojový kód) nahrávate z vlastného CI príkazom portican frontend deploy. Príkaz prečíta priečinok (predvolene dist), pošle ho platforme ako jednu verziu a vypíše adresu jej náhľadu. Naživo sa nič nezmení.
Hosting Porticanu vydáva len statický výstup: index.html, skripty, štýly a obrázky. Na serveri nebeží žiadny kód partnera, preto tam nie je vykresľovanie na serveri (SSR), serverové funkcie ani API trasy. Web sa skladá v prehliadači a Shop API volá bez kľúča. Adresu Shop API trhu, token trhu, adresu pokladne a webu, jazyk a doménu obchodu zapíše platforma do súboru /portican-env.json vedľa index.html; jedna verzia tak beží na každom trhu, kam ju vydáte. Štartér @portican/create taký web zostaví sám.
V koreni priečinka musí byť manifest portican.json: verzia (2), assety (priečinok webu v balíku, s index.html) a nepovinne hostitelia. Mimo priečinka webu smie byť len manifest, package-lock.json a bloky-partnera.json (schéma vlastných blokov, časť Bloky partnera). Balík s workerom (manifest verzie 1 s poľom hlavny) platforma odmietne vetou, čo zmeniť.
Potrebujete API kľúč s rozsahom Nasadenie frontendu (nasadenie-frontendu; Obchod › Integrácie, viď Webhooky a API), uložený v tajomstvách CI ako PORTICAN_API_KLUC. Taký kľúč vie verziu len nahrať a prečítať zoznam verzií (portican frontend verzie); nezverejní ju ani nevráti.
Platforma nahratie zastaví, keď: chýba manifest alebo má inú verziu, chýba index.html alebo je mimo priečinka webu súbor, ktorý tam nepatrí, chýba package-lock.json (CLI ho vie doplniť cez --zamok), balík má známu vysokú zraniteľnosť, verzia presahuje 25 MB alebo 2 000 súborov (jedno nahratie najviac 14 MiB), alebo má vlastný blok bez schémy obsahu. Skryté súbory (.env) a zdrojové mapy do balíka nedávajte. Nálezy kontroly CLI vypíše. Trh môže mať naraz najviac 10 nezverejnených verzií.
Web smie z prehliadača volať Shop API obchodu a hostiteľov z poľa hostitelia v manifeste (najviac 10, len https, bez hviezdičky, nikdy adresa IP ani doména platformy); ostatné zablokuje politika obsahu (CSP), ktorú hosting pridá ku každej stránke. Politika nepustí vložený <script> v HTML, skripty patria do súborov. Statické súbory nesmú ležať pod cestami, ktoré na doméne obchodu obsluhuje platforma (/shop-api, /assets, /health, /na-stiahnutie, /sukromne-subory, /_next, /api, /.well-known, /robots.txt, /sitemap, /llms.txt, /feed, /ucp): taký balík sa nenahrá.
Vyhľadávače. Statický web pošle pre každú adresu ten istý index.html a obsah sa vykreslí až v prehliadači. Google a Bing ho vykreslia a titulky, popisy, kanonické adresy a štruktúrované dáta (JSON-LD z pomocníkov SDK) prečítajú, len neskôr; nástroje, ktoré skript nespúšťajú (náhľady odkazov, časť robotov), uvidia prázdnu stránku. Mapu stránok, feedy, robots.txt a llms.txt vydáva na doméne obchodu platforma z dát obchodu. Stránky, ktoré sa menia zriedka, môžete predkresliť pri builde do hotového HTML; obsah, ktorý mení obchodník, sa potom ukáže až po ďalšom builde.
Verzia má stav koncept, náhľad, zverejnená alebo archív; na trh je zverejnená najviac jedna. Zverejnenie robí obchodník, nie kľúč: v administrácii ho urobí asistent („zverejni nový frontend“), ktorý vie aj vrátiť predošlú verziu alebo šablónu platformy. Návrat na šablónu je jeden krok.
Kým platforma hosting frontendov na svojom serveri nezapne, nahratie skončí vetou o nezapojenom hostingu a nič sa nezapíše. Frontend na vlastnom hostingu s kľúčom frontendu funguje bez toho ďalej.

// 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

Čo platforma nerobí

Pokladňa, prihlásenie, účet zákazníka, platby a vrátenie peňazí sú vždy na platforme. Frontend partnera k nim nemá prístup a platobné údaje cez neho neprechádzajú.
Portican frontend partnera nestavia ani nespúšťa: stavíte ho vo vlastnom CI a nahráte hotový statický web. Vykresľovanie na serveri (SSR) a serverový kód partnera hosting Porticanu nepodporuje; frontend, ktorý ich potrebuje, beží na vašom hostingu s kľúčom frontendu.
Texty a obrázky, ktoré má meniť obchodník, vo frontende nepíšte natvrdo: čítajte ich z nastavení, stránok webu a produktov, ktoré obchodník upravuje v administrácii.