BizKitHub

API pro detail produktu

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í.

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ěď


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;
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 | 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