API — prehľad

Metty poskytuje dve verejné API. Každé beží na vlastnom hostname a používa vlastný typ kľúča:

API	hostname	účel	autentifikácia
Search API	https://search.api.metty.eu	vyhľadávanie a našepkávanie pre vlastné UI	pk_ v query parametri key
Catalog API	https://catalog.api.metty.eu	synchronizácia katalógu bez feedu	sk_ v hlavičke Authorization

Ak používate widget, nevoláte ani jedno z nich — widget si komunikáciu rieši sám.

Kľúče

kľúč	tvar	endpointy	prenos
verejný	pk_ + 32 hexadecimálnych znakov	Search API	query parameter key
secret	sk_ + 64 hexadecimálnych znakov	Catalog API	hlavička Authorization: Bearer <SECRET_API_KEY>

Verejný kľúč je určený na čítanie a môže byť súčasťou zdrojového kódu stránky. Secret kľúč povoľuje zápis do katalógu, a preto nepatrí do frontendu — jeho miestom je serverová konfigurácia, ideálne premenná prostredia.

Hlavičku Authorization nelogujeme. Požiadavku cez nešifrované HTTP endpoint odmietne a nepresmeruje ju, pretože kľúč už v tom momente odišiel po sieti.

Režim katalógu

E-shop je vždy v jednom z dvoch režimov: feed (katalóg importujeme z XML) alebo content_api (katalóg posielate cez API). Režimy sa nekombinujú — starší feed snapshot by prepísal novšie zmeny odoslané cez API.

Zápis do e-shopu v režime feed vráti 409 catalog_mode_conflict; prepnutie režimu vykonáva Metty. Čítanie touto poistkou neprechádza: export katalógu aj Search API fungujú v oboch režimoch.

Prehľad endpointov

operácia	endpoint
vyhľadávanie	GET /search
našepkávanie	GET /suggest
zápis katalógu	PUT / PATCH / DELETE /catalog/products
bezpečný full snapshot	POST /catalog/syncs
export katalógu	GET /catalog/products

Čo API zámerne neobsahuje

Kampane a pinning výsledkov, analytiku, personalizáciu, geografický ranking, vnorené objekty a objekty typu category, brand či article.

Ak pošlete parameter, ktorý by ovplyvnil výsledok a nedokážeme ho obslúžiť, vrátime chybu s jeho názvom. Filter, ktorý by sa ticho neaplikoval, považujeme za horší výsledok než explicitnú chybu.