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

# Propojení AI nástroje s TWICE Commerce

> Ptejte se dokumentace TWICE na TWICE Commerce ze svého AI nástroje přes MCP a dejte nástroji klíč API, když chcete, aby plnil úlohy na vašem účtu.

Propojte TWICE Docs se svým AI nástrojem a ptejte se ho, jak TWICE Commerce funguje. Pokud chcete, aby nástroj plnil úlohy na vašem účtu přes Admin API, dejte mu také klíč API.

| | Claude Desktop | Claude Code, Cursor, VS Code (režim agenta) |
| - | - | - |
| Ptát se na TWICE Commerce: administrace, nastavení, pojmy a API | Ano | Ano |
| Plnit úlohu na vašem účtu s klíčem API | Ne. Napíše požadavky, které spustíte sami | Ano |

## Ptejte se TWICE Docs ze svého AI nástroje

Přidejte `https://www.twicecommerce.com/docs/mcp` do svého nástroje jako server MCP. Nepotřebuje přihlášení ani klíč API.

**Claude Desktop**

**1. Přidejte vlastní konektor**

V nastavení Claude otevřete stránku **Connectors** a zvolte **Add custom connector**.

**2. Nastavte TWICE Docs**

Zadejte tyto údaje, **Authentication** ponechte na **No sign-in** a zvolte **Add**:

* **Name**: TWICE Docs
* **URL**: `https://www.twicecommerce.com/docs/mcp`

**3. Zapněte ho v konverzaci**

Otevřete nabídku příloh (ikona plus) a zvolte **TWICE Docs**.

**Claude Code**

**1. Přidejte server**

Spusťte v terminálu:

```bash theme={null}
claude mcp add --transport http twice-docs https://www.twicecommerce.com/docs/mcp
```

**2. Ověřte, že se server zobrazuje**

Spusťte `claude` a zadejte `/mcp`. **twice-docs** se zobrazí jako připojený.

**Cursor**

**1. Otevřete nastavení MCP**

Otevřete paletu příkazů klávesami `Command + Shift + P` (`Ctrl + Shift + P` ve Windows). Vyhledejte **„Open MCP settings“** a zvolte **Add custom MCP**. Otevře se soubor `mcp.json`.

**2. Přidejte server TWICE Docs**

Do `mcp.json` přidejte tuto konfiguraci:

```json theme={null}
{
  "mcpServers": {
    "TWICE Docs": {
      "url": "https://www.twicecommerce.com/docs/mcp"
    }
  }
}
```

**3. Ověřte, že se server zobrazuje**

Zeptejte se v chatu Cursoru: „What tools do you have available?“ TWICE Docs se v odpovědi objeví.

> [!TIP]
>
> Viz [Installing MCP servers](https://docs.cursor.com/context/context-mcp) v dokumentaci Cursoru.

**VS Code**

**1. Přidejte server TWICE Docs**

Ve svém pracovním prostoru vytvořte `.vscode/mcp.json` s touto konfigurací:

```json theme={null}
{
  "servers": {
    "TWICE Docs": {
      "type": "http",
      "url": "https://www.twicecommerce.com/docs/mcp"
    }
  }
}
```

**2. Spusťte server**

Zvolte **Start server** nad záznamem serveru v `mcp.json`.

> [!TIP]
>
> Viz [dokumentace MCP pro VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

Ptejte se na cokoli, co byste hledali v této dokumentaci, vlastními slovy a ve svém jazyce:

* „Jak přidám nové místo a nastavím jeho otevírací dobu?“
* „Proč si zákazníci nemohou objednat tento výpis?“
* „Jak přes API načtu objednávky změněné za posledních 45 dní?“

Nástroj odpoví vlastními postupy a cestami v administraci TWICE Commerce, například **Nastavení → Místa**, a odkáže na stránky, které použil. U otázky na API správná odpověď prochází stránky přes `GET /v1/admin/orders/list` a posílá `filters` jako jeden parametr kódovaný v JSON s filtrem `updatedAt` a `"scope":"all"`.

## Nechte nástroj pracovat s vaším účtem

Dejte Claude Code, Cursoru nebo VS Code klíč API a nástroj za vás volá Admin API TWICE Commerce: načítá objednávky, mění zásoby, vytváří výpisy. Každý požadavek posílá nástroj sám z vašeho počítače, s klíčem, který tam nastavíte.

**1. Vytvořte klíč**

Otevřete [Nastavení → Integrace & API](https://www.twicecommerce.com/docs/cs/settings/integrations.md) a v části **Klíče API** stiskněte **Vytvořit klíč**. Vyplňte **Štítek klíče k API**, který pojmenuje nástroj, například `Cursor – Anna`, a vyberte, kdy klíči nastane **Vypršení**.

**2. Dejte mu jen oblasti, které vaše úlohy potřebují**

V kroku **Přístup** zvolte **Omezený přístup** a každou oblast, kterou vaše úlohy potřebují, nastavte na **Čtení** nebo **Zápis**. Část **Spusťte úlohu** níže uvádí oblasti pro každou úlohu. Začněte s **Čtení** a **Zápis** přidejte, až budete chtít, aby nástroj data měnil.

**3. Zkopírujte klíč**

Stiskněte **Vytvořit klíč API** a klíč zkopírujte. Celá hodnota se zobrazí jen jednou.

**4. Nastavte klíč tam, kde nástroj spouští příkazy**

Nastavte ho jako proměnnou prostředí `TWICE_API_KEY` podle postupu pro váš nástroj níže.

> [!WARNING]
>
> Klíč nevkládejte do konverzace ani do konektoru TWICE Docs. Konverzace se ukládá u vašeho poskytovatele AI. Hlavička na konektoru jde na server dokumentace, který ji nepoužívá. Klíč s přístupem **Zápis** mění váš účet.

**Claude Code**

Přidejte klíč do `.claude/settings.local.json` ve svém projektu. Claude Code drží tento soubor mimo git a nastaví proměnnou pro každý příkaz, který spustí:

```json theme={null}
{
  "env": {
    "TWICE_API_KEY": "sem-vlozte-svuj-klic"
  }
}
```

Po uložení souboru `claude` restartujte.

**Cursor**

Nastavte proměnnou v shellu a Cursor z něj spusťte, aby ji terminál agenta zdědil:

```bash macOS a Linux theme={null}
export TWICE_API_KEY="sem-vlozte-svuj-klic"
cursor .
```

```powershell Windows (PowerShell) theme={null}
$env:TWICE_API_KEY = "sem-vlozte-svuj-klic"
cursor .
```

Úlohy spouštějte v chatu v režimu **Agent**, který umí spouštět příkazy v terminálu.

**VS Code**

Nastavte proměnnou v shellu a VS Code z něj spusťte, aby ji terminál agenta zdědil:

```bash macOS a Linux theme={null}
export TWICE_API_KEY="sem-vlozte-svuj-klic"
code .
```

```powershell Windows (PowerShell) theme={null}
$env:TWICE_API_KEY = "sem-vlozte-svuj-klic"
code .
```

Úlohy spouštějte v Copilot Chat v režimu **Agent**, který umí spouštět příkazy v terminálu.

Aby klíč v Cursoru a VS Code vydržel mezi relacemi, přidejte řádek `export` do profilu shellu (`~/.zshrc` nebo `~/.bashrc`), nebo ho ve Windows nastavte jako uživatelskou proměnnou prostředí.

Propojení ověřte klíčem, který má **Katalog → Výpisy** na úrovni **Čtení**. Zeptejte se: „Spočítej moje výpisy přes `GET /v1/admin/catalog` s klíčem API z `TWICE_API_KEY`.“ Počet odpovídá **Katalog → Výpisy** v administraci.

## Spusťte úlohu

Pojmenujte úlohu a řekněte, kde je klíč. Nástroj si z TWICE Docs přečte odpovídající dovednost, zavolá API a ověří výsledek:

> Použij klíč API TWICE Commerce z `TWICE_API_KEY`. Načti moje objednávky změněné za posledních 7 dní a seřaď je podle stavu.

Každý požadavek, který nástroj navrhne, si před schválením přečtěte.

Dovednosti jsou v angličtině, stejně jako API a jeho pole. Nástroj vašemu zadání v češtině přesto rozumí.

| Dovednost | Požádejte ho, aby | Klíč potřebuje |
| - | - | - |
| `sync-orders` | načítal, synchronizoval, exportoval nebo vykazoval objednávky pomocí webhooků a nočního doplňovacího průchodu | **Objednávky → Detaily objednávky** na úrovni Čtení. **Nastavení účtu → Webhooky** na úrovni Zápis pro správu webhooků |
| `manage-inventory-quantities` | četl stav zásob po místech a přidával nebo odebíral kusy | **Inventář → Skladové položky** a **Inventář → SKU**. Čtení pro čtení, Zápis pro změny |
| `create-listings-and-pricing` | vytvořil výpis, propojil ho se zásobami a nacenil ho | **Katalog → Výpisy** na úrovni Zápis |
| `customize-storefront` | změnil motiv, vlastní CSS nebo navigaci online obchodu | **Online obchod** na úrovni Zápis |
| `configure-store-and-locations` | změnil nastavení účtu, místa a otevírací dobu | **Lokace** a **Nastavení účtu → Obecné nastavení, objednávky, daně, zásady a šablony e-mailů** na úrovni Zápis |
| `set-buffer-times` | nastavil čas na přípravu a údržbu mezi rezervacemi | **Inventář → Skladové položky** a **Inventář → SKU** na úrovni Zápis |
| `bulk-import-and-migrate` | hromadně nahrál SKU, skladové položky a zákazníky nebo přešel z TWICE 1.0 | **Inventář**, **Zákazníci** a **Katalog → Výpisy** na úrovni Zápis |

Dovednost `twicecommerce` obsahuje pravidla společná všem voláním: ověřování, oprávnění (scopes), kódování parametrů dotazu, stránkování, částky, chyby a limity požadavků. Každá dovednost uvádí endpoint, který použít, endpointy, kterým se vyhnout, a jak výsledek ověřit, a nese datum, kdy byla naposledy ověřena proti produkčnímu API.

Přes MCP čte váš nástroj dovednosti jako zdroje. Pokud váš nástroj čte soubory dovedností, nainstalujte je příkazem `npx skills add https://www.twicecommerce.com/docs`.

## Řešení potíží a časté chyby

> **Odpovědi jsou obecné a TWICE Commerce nezmiňují**
>
> Server TWICE Docs v této konverzaci není zapnutý. V Claude Desktop zvolte **TWICE Docs** v nabídce příloh. V Claude Code spusťte `/mcp` a ověřte, že je **twice-docs** připojený.

> **Nástroj tvrdí, že nemůže posílat požadavky na váš účet**
>
> Nástroj neumí spouštět příkazy, nebo je v režimu, kde jen konverzuje. Použijte Claude Code, nebo Cursor či VS Code v režimu **Agent**. V Claude Desktop nechte nástroj požadavek napsat a spusťte ho sami.

> **Požadavek vrací 401**
>
> Nástroj neposlal žádný klíč, poslal špatný, nebo klíč vypršel. Požádejte nástroj, aby vypsal první čtyři znaky `$TWICE_API_KEY`. Pokud nevypíše nic, proměnnou nastavte znovu a nástroj restartujte. Klíč, jehož platnost vypršela, vrátí zprávu "This API key has expired". Nahraďte ho volbou **Duplikovat** na řádku klíče.

> **Požadavek vrací 403**
>
> Klíč nemá oblast, kterou požadavek potřebuje. `details.requiredScopes` v odpovědi uvádí rozsahy, které by ho otevřely. Přidejte klíči jeden z nich v **Upravit přístup**. Změna se projeví do pěti minut.

> **Odpověď používá GET /v1/admin/orders místo /v1/admin/orders/list**
>
> Nástroj dovednost nepřečetl. Požádejte ho, aby si z TWICE Docs přečetl zdroj `mintlify://skills/sync-orders`, a zkuste to znovu. Adresa funguje, i když váš nástroj dovednost nevypisuje.

> **Odpověď je špatná**
>
> Požádejte nástroj, aby přes propojení TWICE Docs odeslal zpětnou vazbu a uvedl stránku nebo dovednost, která ho navedla špatným směrem. Zpětná vazba jde týmu dokumentace.

## Související články

> **[Klíče API](https://www.twicecommerce.com/docs/cs/concepts/integrations/api-keys.md)**
>
> Všechny oblasti, kam klíč dosáhne, vypršení a limity požadavků.

> **[Nastavení integrací](https://www.twicecommerce.com/docs/cs/settings/integrations.md)**
>
> Vytvářejte, upravujte a mažte klíče API.

> **[Webhooky](https://www.twicecommerce.com/docs/cs/concepts/integrations/webhooks.md)**
>
> Přijímejte události objednávek, jakmile nastanou.

> **[Přístup operačního systému](https://www.twicecommerce.com/docs/cs/concepts/os-approach)**
>
> Jak TWICE Commerce přistupuje k MCP a k platformě pro agenty.


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