> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Inzerát
> Prodejná nabídka produktu ve vašem katalogu, která určuje, co si zákazníci mohou koupit nebo pronajmout.
Katalog > Inzeráty
## Definice
> [!NOTE]
>
> **Analogie:** Inzerát je výkladní verze vašeho produktu. SKU a skladové položky popisují, co vlastníte, inzerát popisuje, co prodáváte: jeho název, fotografie, ceny, doby trvání a místa, kde se zobrazuje.
> [!TIP]
>
> **Zvláštnost v TWICE:** Inzerát není sklad. Dostupnost se odvozuje v reálném čase ze skladových položek, které jsou s ním propojeny prostřednictvím pravidel plnění. Dva inzeráty mohou vést ke stejným fyzickým jednotkám (například inzerát na denní pronájem a inzerát na dlouhodobé předplatné téhož kola).
## Inzerát vs. SKU vs. skladová položka
| Koncept | Co představuje | Kde se nachází |
| - | - | - |
| Inzerát (položka katalogu) | Nabídka směrem k zákazníkovi: název, média, ceny, varianty, prodejní kanály | Katalog |
| SKU | Interní definice produktu: kód, atributy, šablona plnění | Sklad |
| Skladová položka | Fyzická jednotka (nebo sdružené množství), kterou lze rezervovat | Sklad |
Inzerát se propojuje se skladem prostřednictvím **pravidel plnění**, ne přímými cizími klíči. Pravidlo říká: „pro splnění tohoto inzerátu rezervujte 1 jednotku odpovídající `attribute:bike_size = M`". Pravidlo se v okamžiku objednávky přeloží na odpovídající skladové položky, a proto může jeden inzerát čerpat z mnoha SKU a mnoho SKU může zásobovat mnoho inzerátů.
Viz také: [SKU](https://www.twicecommerce.com/docs/cs/concepts/inventory/skus.md), [Skladová položka](https://www.twicecommerce.com/docs/cs/concepts/inventory/stock-items.md).
## Kde to použiji?
* **Správa katalogu**: Vytvářejte, organizujte a publikujte produkty, které si zákazníci mohou objednat
* **Internetový obchod**: Vše publikované do online kanálu se vykresluje z inzerátu
* **Vytváření objednávek**: Návrh objednávky v administraci i pokladna na výkladní skříni začínají u inzerátu
* **Ceny**: Připojte jednu nebo více cenových tabulek pro řízení sazeb za pronájem, prodej a předplatné
* **Varianty**: Nabízejte velikost, barvu nebo jiné osy v rámci jednoho inzerátu
* **Dostupnost**: Počítejte dostupnost k prodeji (ATS) v reálném čase průnikem pravidel plnění se skladovými položkami
* **Kolekce**: Seskupujte inzeráty pro navigaci a merchandising na výkladní skříni
* **Prodejní kanály**: Řiďte, zda je inzerát viditelný v administraci a v internetovém obchodě
* **Doplňky**: Označte inzerát jako pouze doplňkový, nebo k jiným inzerátům připojte doplňky
* **SEO a marketing**: URL adresa, titulek stránky, meta popis, obrázek OpenGraph, `noindex`
## Klíčové vlastnosti
### Identita a obsah
| Vlastnost | Typ | Popis |
| - | - | - |
| `id` | UUID | Identifikátor generovaný serverem |
| `name` | String | Název zobrazovaný zákazníkům |
| `internalName` | String \| null | Volitelný interní štítek zobrazený pouze zaměstnancům |
| `description` | String \| null | Popis ve formátu prostého textu. Zastaralé, upřednostněte `descriptionJson` |
| `descriptionJson` | JSON | Formátovaný popis (rich text) používaný na výkladní skříni |
| `sections` | `CatalogItemSection[]` | Seřazené obsahové sekce (`heading`, `content`, `orderIndex`) |
| `taxonomyCategoryId` | String \| null | Odkaz na uzel taxonomie kategorií |
| `tags` | `Tag[]` | Štítky v rozsahu katalogu. Chytré kolekce podle nich vybírají shody |
| `attributes` | `ResourceAttribute[]` | Vlastní hodnoty atributů pro filtrování a vykreslení stránky produktu |
### Stav a viditelnost
| Vlastnost | Typ | Popis |
| - | - | - |
| `status` | Enum: `active` \| `draft` \| `template` | Stav publikování. Administrace zobrazuje dvě možnosti |
| `salesChannelAdmin` | Boolean | Viditelné při vytváření objednávek v administraci |
| `salesChannelOnline` | Boolean | Viditelné v internetovém obchodě |
> [!NOTE]
>
> Výběr stavu v administraci nabízí pouze **Veřejné** (`active`) a **Koncept** (`draft`). Hodnota `template` je vyhrazená pro systémové šablony a není stavem publikování určeným pro uživatele.
>
> Archivace je samostatná osa nezávislá na stavu publikování. Nastavením inzerátu na Koncept ho ponecháte v katalogu, ale mimo výkladní skříň, archivací ho vyřadíte z používání úplně. Viz [Archivace a mazání](https://www.twicecommerce.com/docs/cs/concepts/repeating-patterns/archiving-and-deletion.md).
### Ceny a daně
| Vlastnost | Typ | Popis |
| - | - | - |
| `pricingTables` | `PricingTable[]` | Jedna nebo více cenových tabulek propojených s inzerátem. Tabulky mohou být samostatné nebo sdílené |
| `taxes` | `CatalogItemTax[]` | Daňové sazby uplatněné na inzerát, s volitelnými přepsáními podle místa |
| `bookingDeposit` | Int ≥ 0 \| null | Vratná kauce (v nejmenších jednotkách měny) vyžadovaná při rezervaci tohoto inzerátu. `null` znamená bez kauce |
Cena se nikdy neukládá přímo na inzerát. Veškeré ceny žijí v připojených cenových tabulkách (řádky pro rezervace, prodej i předplatné). Viz [koncept Cenová tabulka](https://www.twicecommerce.com/docs/cs/concepts/catalog/price-tables.md).
### Limity a chování rezervace
| Vlastnost | Typ | Popis |
| - | - | - |
| `minBookingDuration` | `{ value, unit }` \| null | Nejkratší povolená doba pronájmu |
| `maxBookingDuration` | `{ value, unit }` \| null | Nejdelší povolená doba pronájmu |
| `bookingDurationIncrement` | `{ value, unit }` \| null | Omezuje rezervace se sazbou na celé násobky této doby |
| `orderDeadline` | OrderDeadline \| null | Nejzazší okamžik, kdy lze objednávku vytvořit vzhledem k začátku rezervace. Buď `{ type: 'absolute', value, unit }` (pevný odstup před začátkem; `unit` je `minutes`, `hours` nebo `days`), nebo `{ type: 'relative', daysBefore, time }` (konkrétní čas v dřívějším dni) |
`unit` je jedna z hodnot `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`.
### Sklad a plnění
| Vlastnost | Typ | Popis |
| - | - | - |
| `inventoryTrackingEnabled` | Boolean | Zda se dostupnost sleduje podle skladových položek |
| `rules` | `CatalogItemRule[]` | Základní pravidla plnění. Každé pravidlo definuje `quantity` a `conditions`, které přiřazují skladové položky podle atributu, kódu položky, kódu SKU, názvu položky nebo názvu SKU |
| `rules[].variantRules` | `CatalogItemVariantRule[]` | Přepsání základního pravidla podle varianty |
| `rules[].revenueSplitRate` | Number \| null | Volitelná míra rozdělení použitá v reportingu rozdělení výnosů |
| `serviceLocationLinks` | `CatalogItemServiceLocationLink[]` | Místa, ze kterých lze tento inzerát plnit |
### Varianty
| Vlastnost | Typ | Popis |
| - | - | - |
| `variants` | `CatalogItemVariant[]` | Jedna nebo více os variant. Každá má `name` (například `Velikost`) a seřazené `values` |
Inzerát bez variant se považuje za nabídku s jedním SKU. Viz [koncept Varianta](https://www.twicecommerce.com/docs/cs/concepts/catalog/variants.md).
### Média, dokumenty a SEO
| Vlastnost | Typ | Popis |
| - | - | - |
| `media` | `CatalogItemMediaLinks[]` | Seřazené soubory obrázků a videí |
| `documents` | `CatalogItemDocument[]` | Připojené soubory. Dva nezávislé příznaky pro každý soubor: `copyToOrder` ho zkopíruje na kartu Dokumenty objednávky, `attachToOrderConfirmation` ho přiloží k e-mailům o objednávce |
| `slugs` | String\[] | URL adresy na výkladní skříni. První položka je hlavní (kanonický) slug použitý v odkazech a SEO štítcích. Další položky jsou alternativní sluggy, které také vedou na inzerát. Automaticky se vygeneruje z názvu inzerátu při prvním uložení, pokud je pole prázdné |
| `pageTitle` | String \| null | SEO `` |
| `metaDescription` | String \| null | SEO meta popis |
| `ogTitle` / `ogDescription` / `ogImage` | String / FileResource | Metadata OpenGraph pro náhledy na sociálních sítích |
| `noindex` | Boolean | Zabrání indexování vyhledávači |
### Doplňky a související inzeráty
| Vlastnost | Typ | Popis |
| - | - | - |
| `addonOnly` | Boolean | Když je `true`, tento inzerát lze koupit pouze jako doplněk |
| `addonPricingMode` | `standalone` \| `percentage` | Jak se počítá jeho cena, když je použit jako doplněk |
| `addonPricePercentage` | Integer 1–200 \| null | Vyžadováno, když `addonPricingMode = 'percentage'` |
| `relatedListingIds` | String\[] | Až 100 inzerátů zobrazených jako doporučení |
### Požadavky pokladny
| Vlastnost | Typ | Popis |
| - | - | - |
| `checkoutRequirements` | `CheckoutRequirements` | Povinná zákaznická pole a text souhlasu pro tento inzerát. Ve výchozím stavu se přebírají z nastavení obchodu |
## Vztahy
> **Patří do katalogu**
>
> Inzerát je jeden řádek ve vašem katalogu. Je jednotkou merchandisingu a tím, co se objednává. Inzeráty se vypisují, filtrují a seskupují v **Katalog → Inzeráty**.
> **Vede k SKU a skladovým položkám prostřednictvím pravidel plnění**
>
> Inzerát neukazuje na jedno SKU. Každé pravidlo plnění na inzerátu přiřazuje jednu nebo více skladových položek podle atributu, kódu SKU nebo jiných filtrů. Dostupnost inzerátu je průnikem těchto shod s rezervacemi v kalendáři.
> **Objevuje se v kolekcích**
>
> Inzerát se může objevit v libovolném počtu kolekcí, ať už přidaný ručně (manuální kolekce), nebo přiřazený podle štítku (chytrá kolekce). Viz [koncept Kolekce](https://www.twicecommerce.com/docs/cs/concepts/catalog/collections.md).
> **Publikován do prodejních kanálů**
>
> Dva boolean příznaky řídí, kde je inzerát nabízen: Administrace a Internetový obchod. Vypnutím obou zůstane inzerát v katalogu, ale mimo provoz. Viz [koncept Internetový obchod](https://www.twicecommerce.com/docs/cs/concepts/sales-channels/online-store.md).
> **Propojen s místy**
>
> Každý `CatalogItemServiceLocationLink` určuje místo, ze kterého lze inzerát plnit. Používají ho filtry dostupnosti na výkladní skříni i směrování objednávek.
> **Oceněn prostřednictvím cenových tabulek**
>
> Veškeré ceny žijí v připojených cenových tabulkách. Inzerát obvykle má výchozí (vždy platnou) cenovou tabulku a volitelné časově omezené tabulky pro akce nebo sezónní ceny.
```mermaid theme={null}
%%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 30}}}%%
flowchart TB
subgraph CatalogBox[" "]
Collection["Kolekce"]
Listing["**Inzerát**"]
PriceTable["Cenová tabulka"]
Collection ~~~ Listing ~~~ PriceTable
end
Rules["Pravidla plnění"]
SKU[SKU]
StockItems[Skladové položky]
subgraph ChannelsBox[" "]
direction TB
Admin[Administrace]
OnlineStore[Internetový obchod]
Admin ~~~ OnlineStore
end
Listing -->|definuje| Rules
Rules -->|přiřazuje podle atributu / kódu SKU| SKU
SKU -->|vlastní jednotky| StockItems
Listing -.->|publikován do| ChannelsBox
Listing -->|oceněn| PriceTable
style CatalogBox fill:#0000000d,stroke:#888,stroke-width:2px
style Listing fill:#3b82f633,stroke:#3b82f6,stroke-width:3px,font-weight:bold
style Collection fill:#0000000a,stroke:#999,stroke-width:1px
style PriceTable fill:#0000000a,stroke:#999,stroke-width:1px
style Rules fill:#a78bfa33,stroke:#a78bfa,stroke-width:2px
style SKU fill:#10b98133,stroke:#10b981,stroke-width:2px
style StockItems fill:#10b98133,stroke:#10b981,stroke-width:2px
style ChannelsBox fill:#f59e0b1a,stroke:#f59e0b,stroke-width:2px
```
## Karty detailu inzerátu
Po otevření inzerátu v administraci nabízí stránka zdroje tyto karty:
| Karta | Co konfiguruje |
| - | - |
| Všeobecné | Název, interní název, popis, sekce, média, kategorii taxonomie, stav, štítky |
| Atributy | Vlastní hodnoty atributů (odkazy na skupiny atributů) |
| Varianty | Osy variant, hodnoty a jejich pořadí |
| Ceny | Jednu nebo více cenových tabulek (rezervační, prodejní, předplatné řádky; volitelné násobitele podle varianty) a kauci za rezervaci |
| Limity | `minBookingDuration`, `maxBookingDuration`, `bookingDurationIncrement`, `orderDeadline` |
| Plnění | Základní pravidla plnění, pravidla podle varianty a míry rozdělení výnosů |
| Čárové kódy | Čárové kódy, které se při skenování přiřadí k tomuto inzerátu |
| Publikování | Přepínače prodejních kanálů (Administrace / Internetový obchod) a místa |
| Nastavení pokladny | Požadavky pokladny specifické pro tento inzerát (povinná pole, souhlasy) |
| Nastavení doplňku | Jak se tento inzerát chová jako doplněk: viditelnost pouze jako doplněk a způsob jeho ocenění |
| Doporučení | Připojte doplňky k tomuto inzerátu a vyberte související inzeráty zobrazené na stránce produktu |
| Marketing | Pole SEO: URL adresa, titulek stránky, meta popis, OpenGraph |
| Dokumenty | Připojené soubory, každý lze označit **Kopírovat do objednávky** (kopie se objeví na kartě Dokumenty objednávky) nebo **Přiložit k potvrzení objednávky** (přiloží se k e-mailům o objednávce) |
| Protokol objednávek | Objednávky, které obsahují tento inzerát |
| Protokol aktivit | Auditní záznam změn tohoto inzerátu |
## Výpočet dostupnosti
Dostupnost (ATS, Available-To-Sell) se na inzerátu **nikdy neukládá**. Počítá se na vyžádání pomocí koncových bodů dostupnosti katalogu:
* `GET /catalog/:id/quantity` – celkový počet dostupných jednotek pro inzerát v daném rozsahu dat a vybraných místech
* `GET /catalog/:id/available-by-variant-value-groups` – rozpad podle kombinací hodnot variant
Výpočet projde pravidla plnění inzerátu, vyhodnotí `conditions` každého pravidla vůči skladovým položkám a odečte stávající rezervace v požadovaném okně. Inzerát s `inventoryTrackingEnabled = false` se považuje za nekonečně dostupný.
## Životní cyklus
**1. Vytvoření**
Vytvořte inzerát od začátku, ze šablony, duplikováním existujícího inzerátu nebo přímo z SKU (`POST /catalog/from-article/:articleId`).
> **Jaké informace jsou nutné jako minimum?**
>
> Striktně vyžadován je pouze `name`. Aby byl inzerát kupitelný, potřebujete navíc alespoň jedno pravidlo plnění (nebo `inventoryTrackingEnabled = false`), jednu cenovou tabulku a alespoň jeden povolený prodejní kanál.
> **Jaký je počáteční stav?**
>
> Nové inzeráty se vytvářejí se `status = 'draft'`. Jsou pro zákazníky neviditelné, dokud je nepřepnete na Veřejné.
> **Lze vytváření automatizovat?**
>
> Ano. Použijte `POST /catalog/` pro přímé vytvoření, `POST /catalog/many` pro hromadný import nebo `POST /catalog/from-article/:articleId` pro založení inzerátu z existujícího SKU.
**2. Publikování**
Přepněte `status` na `active` a povolte prodejní kanály, na kterých se má inzerát objevit.
> **Kde se veřejný inzerát objeví?**
>
> V internetovém obchodě, pokud je `salesChannelOnline = true`, a v návrhu objednávky v administraci, pokud je `salesChannelAdmin = true`.
> **Co v praxi brání publikování?**
>
> Nic v API. Inzerát bez pravidla plnění a s `inventoryTrackingEnabled = true` ale ukáže nulovou dostupnost. Inzerát bez cenové tabulky nelze u pokladny ocenit.
**3. Aktualizace**
Většinu polí lze upravit přes `PUT /catalog/:id`. Pravidla, varianty, cenové tabulky a čárové kódy mají vlastní vnořené koncové body.
> **Jaké změny jsou bezpečné u veřejného inzerátu?**
>
> Obsahová pole (název, popis, média, SEO) jsou bezpečná. Změny pravidel ovlivňují jen budoucí výpočty dostupnosti, existující objednávky si zachovávají data inzerátu, která zachytily.
> **Co se změnami cen?**
>
> Pokud má cena platit až od budoucího data, přidejte novou datovanou cenovou tabulku místo úpravy té výchozí. Existující objednávky se zpětně nepřeceňují.
**4. Vyřazení**
Nastavením `status = 'draft'` vyřadíte inzerát z provozu, ale zachováte jeho historii, `DELETE /catalog/:id` ho odstraní. Inzeráty, na které odkazují objednávky, se pro účely historického reportingu uchovávají i po smazání.
## Časté dotazy
> **Jaký je rozdíl mezi inzerátem a SKU?**
>
> **SKU** je definice skladu: kód, který identifikuje typ jednotky, kterou vlastníte. **Inzerát** je prodejná nabídka ve vašem katalogu. Jedno SKU může zásobovat mnoho inzerátů (například denní pronájem, týdenní pronájem a přímý prodej téhož kola). Jeden inzerát může vést k mnoha SKU prostřednictvím pravidel plnění.
> **Mohu prodávat stejnou fyzickou položku za různé ceny?**
>
> Ano. Vytvořte jeden inzerát na každou nabídku a připojte ke každému jinou cenovou tabulku, nebo připojte k jednomu inzerátu více cenových tabulek s nepřekrývajícími se okny `availabilityRange`.
> **Jak funguje dostupnost u sériově evidovaného skladu?**
>
> Každé pravidlo plnění se vyhodnotí na sadu kandidátských skladových položek podle shody atributu nebo kódu. ATS inzerátu pro dané časové okno se rovná počtu kandidátských skladových položek mínus jednotky již rezervované pro toto okno.
> **Co znamená stav `template`?**
>
> `template` je interní stav používaný funkcí systémových šablon. Není zobrazen ve výběru stavu v administraci a není stavem publikování určeným pro uživatele.
> **Může být inzerát zároveň pronájmem i prodejem?**
>
> Ano. Model cenové tabulky zahrnuje samostatné `bookingPricingRows`, `salesPricingRows` a `subscriptionPricingRows`. Přepínači `bookingsEnabled`, `salesEnabled` a `subscriptionsEnabled` na tabulce řídíte, které režimy nákupu jsou nabízeny.
> **Proč inzerát nemá pole `price`?**
>
> Veškerá cenová logika žije na cenových tabulkách, aby mohlo pro jeden inzerát koexistovat více sazebníků, časově omezené akce a násobitele podle varianty. Inzerát bez cenové tabulky je neoceněný.
## Reference pro vývojáře
Inzeráty jsou v API vystaveny jako položky `catalog`.
> **[API: Catalog](https://www.twicecommerce.com/docs/api-reference/catalog)**
>
> Otevřít koncový bod v referenci API.
## Související články
> **[Varianty](https://www.twicecommerce.com/docs/cs/concepts/catalog/variants.md)**
>
> Velikost, barva a další osy v rámci inzerátu
> **[Cenové tabulky](https://www.twicecommerce.com/docs/cs/concepts/catalog/price-tables.md)**
>
> Znovupoužitelné cenové struktury připojené k inzerátům
> **[Kolekce](https://www.twicecommerce.com/docs/cs/concepts/catalog/collections.md)**
>
> Manuální a chytré skupiny inzerátů
> **[SKU](https://www.twicecommerce.com/docs/cs/concepts/inventory/skus.md)**
>
> Definice skladu, ze které inzerát plní
> **[Skladová položka](https://www.twicecommerce.com/docs/cs/concepts/inventory/stock-items.md)**
>
> Fyzické jednotky rezervované při objednání inzerátu
> **[Internetový obchod](https://www.twicecommerce.com/docs/cs/concepts/sales-channels/online-store.md)**
>
> Kde se veřejné inzeráty zobrazují zákazníkům
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.