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

# Dostupnost inzerátu

> Jak TWICE rozhoduje, které inzeráty jsou dostupné v prodejním kanálu, a jak dotazovat dostupnost podle místa, vyřízení a data rezervace.

## Definice

**Dostupnost** odpovídá na jednu otázku, *které inzeráty může zákazník v tomto prodejním kanálu získat?*, a umožňuje ji prohloubit kontextem:

* *…s daným typem vyřízení*
* *…na konkrétním místě*
* *…k rezervaci mezi dvěma daty*

Tatáž služba dostupnosti pohání vlastní prodejní kanály TWICE (Internetový obchod, POS, Administrace) a je přes API dostupná i externím integracím.

## Jak to funguje

Dostupnost **není binární**. Zda je inzerát dostupný, závisí na několika faktorech, které se vrstvou přidávaného kontextu:

* **Inzerát** – inzerát je aktivní, viditelný v kanálu a má alespoň jeden platný typ nákupu.
* **Sklad** – alespoň jedno místo drží zásobu (u položek, které sledují inventář).
* **Vyřízení** – způsob vyřízení dokáže zákazníka obsloužit. U **vyzvednutí v obchodě** je inzerát na daném místě *způsobilý* pouze tehdy, když se tam prodává **a** [pravidla vyřízení](https://www.twicecommerce.com/docs/cs/concepts/admin/locations) daného místa nabízejí vyzvednutí v obchodě pro typ nákupu inzerátu (pronájem nebo prodej).
* **Data** – u rezervací je požadované období bez konfliktů v kalendáři.

Zákazník obvykle vybírá místo a data až pozdě v cestě nákupem, takže dostupnost odpovídá s tím kontextem, který má, a s přibývajícím kontextem se zpřesňuje:

| Kontext | Co můžete zákazníkovi sdělit |
| - | - |
| Pouze kanál | „Dostupné na 3 místech" – nebo „Vyberte data pro zobrazení dostupnosti" u rezervovatelných položek |
| Kanál + místo | „Skladem na Downtownu – vyzvednutí i doručení k dispozici" |
| Kanál + místo + data | „Rezervovatelné 1.–7. 7. za 45 €/den" |

### Způsobilost vs. dostupnost

Dva z těchto faktorů odpovídají na odlišné otázky a výkladní skříň je vyhodnocuje v tomto pořadí:

* **Způsobilost** je fakt *konfigurace* – *lze tento inzerát na tomto místě vůbec vyřídit?* Místo je pro inzerát způsobilé, když se inzerát **na něm prodává** a místo nabízí způsob vyřízení pro jeho typ nákupu. Nezávisí na stavu zásob ani na datech, takže ji lze vyhodnotit předem – pro zobrazení „dostupné k vyzvednutí na těchto místech" a pro filtrování výběru místa.
* **Dostupnost** na to vrství **zásoby a data** – *mají způsobilá místa opravdu požadované položky volné pro zvolené období?* Místo může být způsobilé, a přesto vyprodané pro dané období nebo množství.

Výkladní skříň nejprve zúží výběr na způsobilá místa, poté řeší skutečné zásoby a data pro místo, které zákazník zvolí. Položka zobrazená jako „dostupná k vyzvednutí" se tedy po zadání konkrétních dat a množství může vrátit jako vyprodaná – způsobilost říká, *kde by ji bylo možné vyřídit*, dostupnost potvrzuje, *zda to jde právě teď*.

Ve výkladních skříních s více místy řídí [výběr obchodu](https://www.twicecommerce.com/docs/cs/sales-channels/online-store/theme-editor/settings/store-selection.md) to, jaké zásoby daného místa zákazník vidí. Stránka košíku toto rozšiřuje o kontrolu dostupnosti po jednotlivých obchodech – každý obchod je označen jako „Košík je dostupný" nebo „Košík není dostupný" podle toho, zda dokáže vyřídit všechny položky v košíku pro zvolená data.

### Signál dostupnosti vs. přesná zásoba

V pohledu procházení je dostupnost **signál**, tedy *dostupné někde*, ne počet. Sděluje zákazníkovi, zda lze položku koupit a na kolika místech, aniž by odhalovala přesná množství:

| Signál | Co zákazník vidí |
| - | - |
| Dostupné | „Dostupné na 3 místech" |
| Nedostupné | „Momentálně není k dispozici" |

Přesná množství podle místa se vracejí až po výběru konkrétního místa, a jen pokud se je obchodník rozhodne zobrazovat – někteří obchodníci chtějí signál nedostatku typu „zbývají jen 2", zatímco jiní přesnou zásobu považují za soukromou.

U **rezervovatelných** položek je dostupnost svou povahou vázaná na data. Dokud zákazník nezvolí data, žádný smysluplný signál neexistuje.

> [!NOTE]
>
> Dostupnost odráží [stav skladové položky](https://www.twicecommerce.com/docs/cs/concepts/inventory/stock-item-state.md) a jakékoli [naplánované události](https://www.twicecommerce.com/docs/cs/concepts/inventory/events.md) (rezervace a další blokace), které položku na určité období blokují. Položka, která je vázaná na objednávku, rezervovaná, nebo není **U vás**, se do dostupnosti pro daný rozsah nepočítá.
>
> [Odstup](https://www.twicecommerce.com/docs/cs/inventory/stock-items/fulfillment.md) také prodlužuje okno nedostupnosti oběma směry – odstup před rezervací blokuje položku před jejím začátkem (a ve výkladní skříni funguje jako minimální předstih), zatímco odstup po rezervaci ji blokuje po jejím skončení. Obě okna s odstupem se počítají jako vázaná a brání rezervaci položky v jejich průběhu.

## Rozhodnutí o rezervaci

Zda může zákazník inzerát získat, je součin (**A zároveň**) napříč několika vrstvami – každá musí projít a první vrstva, která selže, je důvodem, proč inzerát není nabídnut. Výkladní skříň je vyhodnocuje od nejlevnější (čistá konfigurace) po nejkonkrétnější (živé zásoby a data):

```mermaid theme={null}
flowchart TD
  S{"Inzerát prodejný?<br/>aktivní · v kanálu · s cenou"} -->|ne| X[Nenabízeno]
  S -->|ano| E{"Místo způsobilé?<br/>prodává se tam · nabízí toto vyřízení pro daný typ nákupu"}
  E -->|ne| X
  E -->|ano| K{"Zásoba dostupná?<br/>jen sledované položky"}
  K -->|ne| X
  K -->|ano| D{"Data a množství sedí?<br/>jen rezervace"}
  D -->|ne| X
  D -->|ano| BI{"Začátek na mřížce rezervačního intervalu?<br/>rezervace, jen výkladní skříň"}
  BI -->|ne| X
  BI -->|ano| OD{"Termín objednávky splněn?<br/>rezervace a předplatná"}
  OD -->|ne| X
  OD -->|ano| Y[Nabídnuto zákazníkovi]
```

**1. Inzerát je prodejný**

* Status **Aktivní** – koncept a šablonové [inzeráty](https://www.twicecommerce.com/docs/cs/concepts/catalog/listings.md) se nikdy nenabízí.
* Zapnuto v zákazníkově **prodejním kanálu** (`salesChannelOnline` pro Internetový obchod).
* Má alespoň jeden typ nákupu s řádkem v připojené [cenové tabulce](https://www.twicecommerce.com/docs/cs/concepts/catalog/price-tables.md): zapnutý **rezervační řádek** v platném okně pro pronájmy, nebo **prodejní řádek** pro nákupy.

**2. Místo dokáže inzerát vyřídit – *způsobilost***

* Inzerát se **prodává na** [místě](https://www.twicecommerce.com/docs/cs/concepts/admin/locations) (propojeno) a místo je aktivní se zapnutým kanálem.
* [Pravidla vyřízení](https://www.twicecommerce.com/docs/cs/concepts/admin/locations) daného místa nabízejí požadovaný **způsob vyřízení** (např. vyzvednutí v obchodě) **pro daný typ nákupu**. Prodejna, která nabízí vyzvednutí pro prodej, ale ne pro pronájem, dělá pronájem tam *nezpůsobilým*, i kdyby byl skladem.

Tato vrstva je čistá konfigurace: zásoby ani data se ještě neprověřují, takže ji lze vyřešit předem a použít k filtrování výběru místa.

**3. Zásoba existuje – *dostupnost***

U položek sledovaných v inventáři musí způsobilé místo držet alespoň jednu použitelnou [skladovou položku](https://www.twicecommerce.com/docs/cs/concepts/inventory/stock-item-state.md) – **U vás**, a nevázanou na objednávku, nerezervovanou ani jinak neblokovanou. Inzeráty s neomezenou dostupností tuto vrstvu přeskakují.

**4. Data odpovídají cenovému řádku a otevírací době místa (rezervace)**

Jakmile zákazník zvolí období:

* **Rezervační řádek** musí pokrýt danou dobu trvání a respektovat svá omezení `weekdays` a `timeOfDayRange`, datové okno tabulky a minimální/maximální dobu rezervace inzerátu – jinak **cena neexistuje**, a tedy ani rezervovatelná možnost.
* **[Hodiny vyřízení](https://www.twicecommerce.com/docs/cs/concepts/admin/locations)** místa musí umožňovat zvolený čas vyzvednutí a vrácení. Hodiny vyzvednutí omezují začátek rezervace, hodiny vrácení omezují její konec. Místa bez vlastních hodin vyřízení se řídí otevírací dobou.

**5. Každá jednotka je volná pro celé období (rezervace)**

Každá potřebná jednotka musí být **bez [konfliktů](https://www.twicecommerce.com/docs/cs/concepts/orders/stock-item-conflicts.md)** po **celé období** – požadované **množství** nesmí přesáhnout počet jednotek dostupných v daném období.

[Odstup](https://www.twicecommerce.com/docs/cs/inventory/stock-items/fulfillment.md) prodlužuje okno konfliktu oběma směry – odstup před rezervací blokuje položku před jejím začátkem, odstup po rezervaci ji blokuje po jejím skončení. Položka s odstupem 1 hodinu před a 2 hodiny po je nedostupná od 1 hodiny před vyzvednutím až do 2 hodin po vrácení.

Jedna rezervace z této kontroly vyjmuta je: ta, kterou drží právě upravovaná řádková položka – viz [Úprava existující řádkové položky](#úprava-existující-řádkové-položky).

**6. Uplynul minimální předstih z odstupu před rezervací (rezervace)**

**Odstup před rezervací** skladové položky ve výkladní skříni zároveň vynucuje minimální předstih: rezervace začínající dříve, než odstup dovoluje, se zobrazí jako nedostupná. Personál administrace je z tohoto omezení vyňat.

**7. Začátek je na mřížce rezervačního intervalu (rezervace)**

Rezervace může začít každých N minut, počítáno od místní půlnoci v servisním místě. Účet nastavuje interval v [Nastavení → Provoz → Rezervace](https://www.twicecommerce.com/docs/cs/settings/bookings.md) a inzerát jej může přepsat na své [kartě Limity](https://www.twicecommerce.com/docs/cs/catalog/listings/limits.md).

Výběry generují své počáteční časy na této mřížce, takže čas mimo mřížku je zřídka dosažitelný. Kontroluje to i košík výkladní skříně: řádek mimo mřížku je označen upozorněním `off_booking_interval` a pokladna odmítne začátek při vytváření objednávky.

Berte interval jako mřížku pro výběr, ne jako odpověď o dostupnosti. Endpointy dostupnosti začátek mimo mřížku neodmítají a správa objednávek v administraci úmyslně rezervuje mimo mřížku.

**8. Termín objednávky neuplynul (rezervace a předplatná)**

Pokud má inzerát nastavený [termín objednávky](https://www.twicecommerce.com/docs/cs/catalog/listings/limits.md), musí zákazník zadat objednávku před uzávěrkou:

* **V pevně stanovený čas předem** – čas začátku minus pevný odstup (např. 2 hodiny před začátkem).
* **Do určité denní doby** – mezní čas dřívějšího dne, vyhodnocený v časovém pásmu servisního místa (např. do 18:00, 1 den před začátkem).

Časy začátku po termínu se v kalendáři výkladní skříně zobrazují jako nedostupné. Pokud má zákazník položku v košíku a termín uplyne před placením, košík položku označí upozorněním `order_deadline`. Uživatelé administrace jsou z toho vyňati – personál může vytvářet objednávky i po termínu.

Odpověď, kterou vidí zákazník, odráží nejhlubší dosaženou vrstvu: *„Dostupné na 3 místech"*, než zvolí místo, *„Z tohoto místa není dostupné"*, když tam selže způsobilost, *„Žádné dostupné dny"*, když neprojde žádné datum, a počet jednotek jako *„Zbývá jen 1"*, když je blokujícím faktorem množství.

### Úprava existující řádkové položky

Když se dostupnost počítá pro řádkovou položku, která je právě **upravována**, vlastní rezervace této řádkové položky je z kontroly vyloučena, spolu s rezervacemi jakýchkoli k ní připojených doplňků. Výjimka pokrývá celou rezervovanou stopu, [okna odstupu](https://www.twicecommerce.com/docs/cs/inventory/stock-items/fulfillment.md) včetně, takže řádková položka nikdy neblokuje vlastní úpravu.

Bez ní by se vlastní odstup položky počítal proti ní: skladová položka s dvouhodinovým odstupem po rezervaci by odmítla hodinové prodloužení téhož rezervačního období, které tento odstup vytvořilo.

Vyloučení **prodané** skladové položky uvolňuje kapacitu, kterou prodej zabral, stejným způsobem, takže přeplánování prodeje vidí vlastní jednotku znovu jako dostupnou.

Pravidlo platí všude, kde se existující řádková položka přeplánovává nebo se jí mění výběr – v editoru [řádkové položky](https://www.twicecommerce.com/docs/cs/orders/order-tabs/line-items.md) v administraci i v úpravě košíku ve výkladní skříni. Nevztahuje se na *jiné* řádkové položky téže objednávky – ty si drží své rezervace normálně a úprava, která se s některou střetne, se nahlásí jako nedostupná.

### Položky již v košíku

Položky v košíku se kontrolují, jako by už byly rezervované, včetně odstupů. Druhý pronájem téže skladové položky, který začíná uvnitř odstupu po prvním pronájmu, se nenabízí, i když se samotná rezervační období nepřekrývají.

Totéž platí pro kontrolu jednotlivých obchodů na stránce košíku – obchod se počítá jako „Košík je dostupný" jen tehdy, když dokáže naráz udržet každou položku v košíku i s jejími okny odstupu.

### Příklady

> **Pronájem prodávaný v obchodě, který nabízí vyzvednutí jen pro prodej**
>
> Inzerát je aktivní a skladem v daném obchodě, ale pravidla vyřízení obchodu povolují vyzvednutí v obchodě jen pro **prodej**. Pronájem je tam **nezpůsobilý**, takže výkladní skříň zobrazí *„Z tohoto místa není dostupné"* – i když jednotky existují. Stále může být rezervovatelný v jiném obchodě, který nabízí vyzvednutí pro pronájem.

> **Skladem, ale zvolená data jsou v konfliktu**
>
> Položka je způsobilá a má jednotky, ale každá jednotka na zvoleném místě je již vázaná na část požadovaného období. V signálu procházení se čte jako *dostupná*, přesto kalendář pro daná přesná data nevrátí **žádné rezervovatelné období** – jiná data nebo jiné místo to vyřeší.

> **Prodloužení pronájmu, kterému stojí v cestě vlastní odstup**
>
> Skladová položka nese dvouhodinový odstup po rezervaci a zákazník volá, aby si prodloužil pronájem o hodinu. Ta hodina spadá do odstupu, který sám pronájem vytvořil.
>
> Protože je upravovaná řádková položka z kontroly vyloučena, hodina se čte jako volná a nová data se uloží. Rezervace jiného zákazníka v tomtéž okně by ji stále blokovala.

> **Rezervovatelné, ale ne v požadovaný den nebo na požadovanou dobu**
>
> Jediný rezervační řádek je omezen na Po–Pá (`weekdays`) s dvoudenním minimem. Sobotní začátek nebo jednodenní rezervace neodpovídá **žádnému řádku** – neexistuje cena, takže pro tento výběr nejde rezervovat, i když je zásoba volná.
>
> Výkladní skříň to zákazníkovi ukáže dřív, než se zaváže: v rozbalovací nabídce **Možnosti rezervace** v rezervačním widgetu je možnost, kterou nelze v daný den zahájit, zešedlá a popsaná dalším možným datem – *„Pro vybraná data není k dispozici – další dostupné po 18. 8."* Jejím výběrem se datum začátku přesune na tento den. Viz [Možnosti rezervace a zvolené datum](https://www.twicecommerce.com/docs/cs/concepts/sales-channels/online-store.md).

> **Množství přesahuje to, co drží jedno místo**
>
> Zákazník chce 3 jednotky; zvolené místo má pro dané období volnou 1 a jiné místo má 2. Žádné z nich nepokryje všechny 3 samo, takže se položka celkově zobrazuje jako *dostupná*, ale zvolené místo je omezeno na 1. Snížení množství, nebo výběr místa s dostatečnou zásobou, to vyřeší.

> **Prodejní položka bez pravidel zásob**
>
> Prodejní inzerát na zakázku s neomezenou dostupností přeskakuje vrstvy zásob i konfliktů zcela: dokud je aktivní, v kanálu a prodává se na způsobilém místě, je koupitelný bez stropu na množství.

> **Položka v košíku vypadne z mřížky po změně intervalu**
>
> Zákazník přidá rezervaci na 10:45, zatímco účet běží na patnáctiminutovém intervalu. Obchodník poté přepne účet na 30 minut a košík označí řádek jako `off_booking_interval`: 10:45 už není začátek, který mřížka nabízí.
>
> Rezervace už objednané na 10:45 si svůj čas ponechají. Kontroluje se jen vytvářený začátek, takže žádná objednávka v historii se změnou neznehodnotí.

> **Termín objednávky uplyne, zatímco je položka v košíku**
>
> Inzerát má termín objednávky „2 hodiny před začátkem". Zákazník v 11:30 přidá do košíku rezervaci na 14:00, ale zaplatí až ve 12:15. Košík položku označí – termín byl ve 12:00 a objednávku pro tento začátek už nelze zadat. Zákazník může zvolit pozdější začátek nebo položku odebrat.

## Dotazování dostupnosti přes API

Ověřte se hlavičkou `X-API-KEY` (viz [Klíče API](https://www.twicecommerce.com/docs/cs/concepts/integrations/api-keys.md)). Hlavní endpointy:

| Endpoint | Účel |
| - | - |
| `GET /v1/admin/availability/{catalogItemId}/period` | Vypočítaná dostupnost pro rozsah dat, s omezeními, která ji ovlivnila |
| `GET /v1/admin/availability/{catalogItemId}/range` | Dostupnost napříč rozsahem, rozdělená na dílčí rozsahy |
| `GET /v1/admin/catalog/{id}/quantity` | Dostupné množství pro inzerát, volitelně podle místa a dat |
| `GET /v1/admin/articles/available` | Dostupné skladové položky pro rozsah a filtry |

Mezi běžné parametry dotazu patří `from` / `to` (rozsah dat), `serviceLocationIds` a `variantValueIds`.

Oba endpointy `availability` jsou součástí dokumentovaného Admin API. Poslední dva jsou dosažitelné, ale nejsou publikovány v referenci, takže se mohou bez upozornění změnit. Stavte na nich jen tehdy, pokud to dokážete unést.

Úplné parametry a schémata odpovědí najdete v [API referenci](https://www.twicecommerce.com/docs/cs/api-reference) – je generovaná z živého API, takže vždy odráží aktuální pole.

## Související články

> **[Inzeráty](https://www.twicecommerce.com/docs/cs/concepts/catalog/listings.md)**
>
> Zákaznická katalogová entita, pro kterou se dostupnost vyhodnocuje.

> **[Stav skladové položky](https://www.twicecommerce.com/docs/cs/concepts/inventory/stock-item-state.md)**
>
> Vazby U vás / U zákazníka, které řídí, co je dostupné.

> **[Naplánované události](https://www.twicecommerce.com/docs/cs/concepts/inventory/events.md)**
>
> Rezervace a blokace, které dostupnost na dané období omezují.

> **[Cenové tabulky](https://www.twicecommerce.com/docs/cs/concepts/catalog/price-tables.md)**
>
> Ceny vrácené společně s dostupností u rezervací.

> **[Místa](https://www.twicecommerce.com/docs/cs/concepts/admin/locations)**
>
> Kde se inzeráty prodávají a jaká pravidla vyřízení řídí způsobilost k vyzvednutí.

> **[Nastavení rezervací](https://www.twicecommerce.com/docs/cs/settings/bookings.md)**
>
> Celoúčetní rezervační interval, na kterém každý výběr generuje počáteční časy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.