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	https URL detailu 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	2048	https URL obrázka
params	objekt / null	názov 128, hodnota 2048	vlastné atribúty — váš zdroj facetov

Dlhší text orežeme na uvedený limit. Výnimkou sú url a image: musia byť https URL (schému porovnávame bez ohľadu na veľkosť písmen) do 2048 znakov, inak položku odmietneme ako invalid_url / invalid_image — URL neorezávame. Rovnako 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 filter[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 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á (chyba bez results) iba pri nesprávnom kľúči, nevalidnom JSON, prekročení limitu 100 produktov, nesprávnom režime katalógu, neznámom (404 not_found) alebo už commitnutom (409 generation_committed) sync pri zápise s ?sync=, zaneprázdnenom indexe (503 index_busy) alebo prekročenom rate limite. 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.