Zápis katalógu

Catalog API beží na https://catalog.api.metty.eu a autentifikuje sa secret kľúčom v hlavičke Authorization.

metóda	cesta	správanie
PUT	/catalog/products	vytvorí produkt alebo ho úplne nahradí — neuvedené pole sa zmaže
PATCH	/catalog/products	zmení iba uvedené polia; neexistujúci produkt je chyba, nie vytvorenie
DELETE	/catalog/products	odstráni produkty z databázy aj z indexu

Telom PUT a PATCH je pole produktov bez obálky. Jedna dávka obsahuje najviac 100 produktov.

Príklad

curl -X PUT https://catalog.api.metty.eu/catalog/products \
  -H "Authorization: Bearer <SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "sku-1",
      "name": "Príklepová vŕtačka Bosch",
      "url": "https://eshop.sk/vrtacka",
      "price": 129.9,
      "list_price": 159.9,
      "currency": "EUR",
      "in_stock": true,
      "brand": "Bosch",
      "category": "Náradie > Vŕtačky",
      "description": "Príklepová vŕtačka s reguláciou otáčok.",
      "image": "https://eshop.sk/media/vrtacka.jpg",
      "params": { "farba": "modrá", "príkon": "800 W" }
    }
  ]'

id je váš vlastný identifikátor produktu a jediné povinné pole pre PATCH aj DELETE. Pri PUT sú povinné aj name a url.

Polia

pole	typ	limit	význam
id	string	1–255	identita produktu (vaše SKU)
name	string	255	názov produktu
url	string	2048	odkaz na detail produktu
price	number	—	cena ako JSON number, nie ako string
list_price	number / null	—	cena pred zľavou; hodnota nižšia alebo rovná price sa ignoruje
currency	string	8	mena katalógu (napríklad EUR) — vlastnosť katalógu, nie produktu
in_stock	boolean / null	—	dostupnosť
brand	string / null	255	značka
category	string / null	512	cesta kategórie, úrovne oddelené >
description	string / null	65 535	popis
image	string / null	255	URL obrázka
params	objekt / null	názov 128, hodnota 2048	vlastné atribúty — váš zdroj facetov

Dlhší text neodmietame, orežeme ho na uvedený limit. Pri poli image na to prosím dbajte: dlhá podpísaná URL sa do limitu nemusí zmestiť. Jedinou výnimkou je názov v params: dlhší než 128 znakov odmietneme ako invalid_params.

params je mapa názov → skalárna hodnota ({"farba": "modrá"}). Podľa nej následne filtrujete v Search API parametrom farba=modrá a widget z nej zostavuje filtre v šablónach Pro a Max. Boolean prevedieme na "true" / "false"; null ani vnorený objekt neprijímame.

Do params patrí všetko, podľa čoho sa má filtrovať

Facety vznikajú z params. Ak potrebujete filter podľa značky alebo iného vlastného poľa, pošlite ho aj ako parameter — samotné pole brand filtrovateľné nie je.

Nad rámec toho, čo pošlete, vie Metty doplniť facety odvodené z textov produktov a jednotlivé facety vypnúť pre konkrétnu kategóriu. Táto vrstva sa nastavuje u nás a vaše dáta nemení: export vráti presne tie params, ktoré ste zapísali, kým hľadanie môže ponúkať polí viac. To isté platí pre image: export vráti URL, ktorú ste nám poslali.

category je úplná cesta od koreňa; chýbajúce úrovne vytvoríme. Ako oddeľovač akceptujeme > aj |.

Originálne obrázky hostujete vy; my si každý raz stiahneme, necháme si 500 px WebP kópiu a servírujeme šírku, ktorú si vyhľadávanie vypýta. Sťahovanie beží na pozadí, takže PUT naň nečaká a image vo výsledkoch vyhľadávania je krátko po prvom zápise null.

Mazanie

curl -X DELETE https://catalog.api.metty.eu/catalog/products \
  -H "Authorization: Bearer <SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["sku-1", "sku-2"]}'

Limit 100 položiek na dávku platí aj tu.

Odpoveď

Dávka vždy vráti 200 a stav každého produktu samostatne. Jeden chybný produkt neovplyvní ostatné a produkt, ktorý neprešiel validáciou, sa do databázy nezapíše ani čiastočne.

{
  "results": [
    { "id": "sku-1", "status": "ok" },
    { "id": "sku-2", "status": "error", "error": "missing_name", "message": "The field \"name\" is required." }
  ]
}

Pole results kontrolujte vždy — stavový kód 200 neznamená, že prešli všetky produkty.

Celá dávka zlyhá (4xx bez results) iba pri nesprávnom kľúči, nevalidnom JSON, prekročení limitu 100 produktov alebo nesprávnom režime katalógu. Zoznam kódov nájdete v sekcii Chyby a limity.

Opakované odoslanie

Všetky tri operácie zapisujú podľa id, takže opakované odoslanie tej istej dávky je bezpečné: PUT znova prepíše rovnaké hodnoty, PATCH znova nastaví rovnaké polia. Idempotency kľúč nepotrebujete. Jediný rozdiel nastáva pri DELETE — opakovanie vráti not_found pri produktoch, ktoré odstránil už prvý pokus.

Hromadná zmena

Samostatný endpoint na hromadnú zmenu neexistuje. Zmenu viacerých produktov pošlite ako dávku PATCH; ak ich identifikátory nepoznáte, získate ich z exportu alebo zo Search API s rovnakým filtrom.

Kompletný synchronizačný skript nájdete v príkladoch.