Preskočiť na obsah
E-shop aj firemný web. Bez percent z obratu. Začnite zadarmo.
SK
EnglishENSlovenčinaSKČeštinaCS
Prihlásiť sa Založiť e-shop zadarmo

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.

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. Beží u vás, nie na Porticane. Viď časť Klient SDK 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): administrácia upravuje len to, čo platforma pozná, nie bloky, ktoré by ste si vymysleli vo vlastnom kóde.

Postup od kľúča po nasadený frontend

  1. Obsluha obchodu vytvorí v administrácii v časti Obchod › Integrácie kľúč frontendu: 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.
  2. 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.
  3. Nainštalujte SDK z npm príkazom npm install @portican/storefront. Balík je na verejnom npm a nemá závislosti; každú verziu zverejňuje len CI Porticanu z hlavnej vetvy.
  4. Na serveri (SSR) vytvorte klienta s kľúčom, v prehliadači ho vytvorte bez kľúča. Príklad je nižšie v časti Klient SDK.
  5. Čí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).
  6. Frontend nasadíte na vlastný hosting. Portican ho nehostí ani nespúšťa; adresa webu musí sedieť s adresou, 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 zatiaľ nevie: právne texty obchodu cez Shop API a vykresľovanie blokov stránok a sekcií úvodnej strany. Tie si vo frontende skladá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 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 spustíte bez inštalácie cez npx @portican/cli vzhlad, alebo ho pridá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 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í.

Č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 nehostí, nestavia ani nenasadzuje. Pre vlastný frontend platforma dnes dáva kľúč, Shop API, SDK a odovzdanie košíka.
  • 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.