BizKitHub

API pro detail produktu

export type PublicProductDetailResponse = { id: ProductId; code: ProductId; name: string; slug: string; shortDescription: TrustedHTML; longDescription: TrustedHTML; mainImageUrl?: string; galleryItems: PublicProductGalleryItem[]; isVariantProduct: boolean; variantItems: PublicProductDetailVariantItem[]; active: boolean; b2b: boolean; showInFeed: boolean; soldOut: boolean; mainCategory?: { code: string; name: string }; categoryItems: { code: string; name: string }[]; brandId?: number; price: number; standardPricePercentage?: number; vat?: number; sizeWidthMm?: number; sizeHeightMm?: number; sizeDepthMm?: number; weightGrams?: number; warehouseAllQuantity?: number; warehouseLimit?: number; event?: PublicProductEventResponse; customFields: Record<string, string>; lastUpdate: Date; };

Naposledy aktualizováno 1. srpna 2026

Endpoint pro detail produktu vrací kompletní veřejnou datovou zátěž jediného produktu — vše, co prodejna potřebuje k vykreslení stránky produktu v jednom volání: název, krátký a dlouhý popis, galerii, varianty, fyzické rozměry, přiřazení kategorií, data událostí a vlastní pole. Je doplňkem k Product feed API, které vrací kompaktní položky seznamu vhodné pro stránky s procházením.

Tento endpoint je navržen tak, aby byl volán při každém zobrazení stránky produktu. Odpověď je poskytována z interně kešované snímku, který je aktualizován při každé změně katalogu, takže zůstává rychlý i při vysokém provozu a i když je základní datový model komplexní.

Endpoint


GET https://api.bizkithub.com/product/v1/detail?slug=xxx

Parametr dotazu slug je povinný a musí odpovídat kanonickému slug produktu (jedinečnému v rámci organizace). Autentizace probíhá pomocí standardního parametru apiKey (viz článek API key).

Pokud se slug nepřekládá na viditelný produkt, endpoint vrátí chybovou zprávu platformy PUBLIC_PRODUCT_DOES_NOT_EXIST. Produkt je považován za neviditelný, pokud je neaktivní, soft-deleted nebo slug jednoduše neexistuje.

Odpověď


```ts export type ProductId = ${string}; export type ProductVariantId = ${string};

export type PublicProductDetailResponse = { id: ProductId; code: ProductId; name: string; slug: string; shortDescription: TrustedHTML; longDescription: TrustedHTML; mainImageUrl?: string; galleryItems: PublicProductGalleryItem[]; isVariantProduct: boolean; variantItems: PublicProductDetailVariantItem[]; active: boolean; b2b: boolean; showInFeed: boolean; soldOut: boolean; mainCategory?: { code: string; name: string }; categoryItems: { code: string; name: string }[]; brandId?: number; price: number; standardPricePercentage?: number; vat?: number; sizeWidthMm?: number; sizeHeightMm?: number; sizeDepthMm?: number; weightGrams?: number; warehouseAllQuantity?: number; warehouseLimit?: number; event?: PublicProductEventResponse; customFields: Record<string, string>; lastUpdate: Date; };

export type PublicProductEventResponse = { id: string; startTime: Date; endTime: Date; isAllDay: boolean; isBlocking: boolean; title: string; description?: string; agenda?: string; url?: string; locationTitle?: string; };

export type PublicProductDetailVariantItem = { id: ProductVariantId; code: string; name: string; ean?: string; price: number; warehouseAllQuantity?: number; };

export type PublicProductGalleryItem = { type: 'image' | 'video'; id: number; url: string; title?: string; tag?: string; }; ```

Odpověď záměrně vrací bohatou, hluboce vnořenou datovou zátěž v jediném volání, namísto vyžadování vícenásobných kroků. Galerie, varianty, kategorie, data událostí a vlastní pole jsou všechna vyřešena na straně serveru do jednoho JSONu, takže prodejna potřebuje pouze jeden obousměrný přenos k vykreslení stránky.

Pole PublicProductDetailResponse


| Vlastnost | Typ | Význam |
|----------|------|---------|
| id | ProductId | Externí identifikátor produktu, typicky identický s code. |
| code | ProductId | Kód produktu definovaný obchodníkem. |
| name | string | Lidé čitelný název produktu. Obvykle nadpis stránky. |
| slug | string | URL slug produktu; tvoří součást URL detailní stránky. |
| shortDescription | TrustedHTML | Krátký popis jako bezpečné HTML. |
| longDescription | TrustedHTML | Dlouhý popis jako bezpečné HTML. |
| mainImageUrl | string | Absolutní URL hlavního obrázku (původní soubor). |
| galleryItems | PublicProductGalleryItem[] | Nahrané položky galerie — obrázky a videa. |
| isVariantProduct | boolean | Zda má produkt varianty; varianta musí být vybrána při nákupu. |
| variantItems | PublicProductDetailVariantItem[] | Dostupné varianty. Viz Product variants. |
| active | boolean | Zda je produkt aktivní. |
| b2b | boolean | Zda je produkt omezen na ověřené firemní zákazníky. |
| showInFeed | boolean | Zda je produkt exportován do feedů porovnávačů zboží. |
| soldOut | boolean | Zda je produkt označen jako vyprodaný. |
| mainCategory | { code, name } | Hlavní kategorie (používá se pro drobečkovou navigaci a kategorizaci v porovnávačích). |
| categoryItems | { code, name }[] | Všechny kategorie, do kterých tento produkt patří. |
| brandId | number | Primární identifikátor značky. |
| price | number | Základní cena ve výchozí měně obchodníka, včetně DPH. |
| standardPricePercentage | number | Značka referenční ceny používaná pro zobrazení přeškrtnutých ceníkových cen. |
| vat | number | Základní sazba DPH. |
| sizeWidthMm / sizeHeightMm / sizeDepthMm | number | Fyzické rozměry v milimetrech. |
| weightGrams | number | Hmotnost v gramech. |
| warehouseAllQuantity | number | Agregovaný skladový stav ve všech skladech. |
| warehouseLimit | number | Maximální skladovatelné nebo prodejné množství (užitečné pro události s prodejem vstupenek). |
| event | PublicProductEventResponse | Data události, pokud je produkt spojen s fyzickou událostí (koncert, tábor, kurz). |
| customFields | Record<string, string> | Metadata klíč–hodnota definovaná obchodníkem. |
| lastUpdate | Date | Časové razítko poslední aktualizace kešovaného snímku pro tento produkt. |

Pole PublicProductEventResponse


| Vlastnost | Typ | Význam |
|----------|------|---------|
| id | string | Veřejný identifikátor události. |
| startTime | Date | Začátek události. |
| endTime | Date | Konec události. |
| isAllDay | boolean | Zda událost pokrývá celý den. |
| isBlocking | boolean | Zda událost blokuje svůj kalendářní slot jako závaznou rezervaci. |
| title | string | Název události. |
| description | string | Volný text popisu. |
| agenda | string | Podrobný program nebo rozvrh. |
| url | string | Externí URL pro dodatečné informace. |
| locationTitle | string | Lidé čitelný název místa konání. |

Pole PublicProductGalleryItem


| Vlastnost | Typ | Význam |
|----------|------|---------|
| type | 'image' \| 'video' | Typ média. |
| id | number | Identifikátor média. |
| url | string | Absolutní URL původního souboru. |
| title | string | Volitelný popisek. |
| tag | string | Volitelný systémový tag používaný pro křížové odkazy na obrázky (např. main, back, packaging). |

Vícejazyčný obsah


Odpovědi jsou vráceny v lokalizaci požadované konfigurací API klíče nebo vyjednáváním jazyka v požadavku. Chybějící překlady se vrací na výchozí jazyk organizace podle pravidel zálohy organizace, takže volající nikdy neobdrží prázdný popis pro existující produkt.

Aktuálnost dat


Detailní odpověď je poskytována z kešovaného snímku, který je aktualizován při každé změně katalogu. Nestálá provozní pole (dostupnost, příznak vyprodáno, příznak smazání) jsou obohacena v době čtení z živé databáze. Není třeba ručně invalidovat; úprava obchodníka je viditelná při dalším volání.

Související články


Související články