> ## 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. # Klíče API > Ověřujte externí systémy vůči API TWICE Commerce pomocí klíčů API a omezte každý klíč na oblasti, které jeho integrace potřebuje. Vytvořte pro každou integraci, skript a headless výkladní skříň vlastní klíč API a dejte mu jen přístup, který integrace potřebuje. Klíč posílejte v hlavičce `X-API-KEY`. Ověřuje se vůči stejnému API, které používá administrace. > [!NOTE] > > Admin API TWICE je ve fázi alfa. Endpointy a schémata se mohou změnit bez upozornění. Připněte verzi API (viz [Verze API](#verze-api)) a před upgradem integrace zkontrolujte referenci. ## Jak to funguje Klíč má buď **Plný přístup**, nebo **Omezený přístup**: * **Plný přístup** dosáhne na každý endpoint, na který klíč dosáhnout může, včetně endpointů přidaných později. * **Omezený přístup** dosáhne jen na oblasti, které nastavíte, každou na úrovni **Čtení** nebo **Zápis**. Zápis zahrnuje čtení. Oblast pokrývá vše pod sebou, včetně toho, co do ní přibude později. **Katalog** na úrovni **Čtení** čte výpisy, sbírky, cenové tabulky a slevy. Každá nastavená oblast se na klíči uloží jako rozsah (scope): cesta oblasti a její úroveň, například `orders.details.read` nebo `inventory.stock_items.write`. Každý endpoint v [referenci API](https://www.twicecommerce.com/docs/api-reference) uvádí rozsahy, které ho otevírají, a stačí kterýkoli z nich. Klíč čte to, na co má rozsah, a k tomu data, která jsou v tom vnořená. Klíč, který čte objednávky, dostane údaje o výpisu, zákazníkovi a lokaci, které objednávka nese, i bez jejich rozsahů. > [!NOTE] > > Klíče vytvořené před zavedením rozsahů mají **Plný přístup**, dokud ho nezměníte. Každý z nich omezte v **Upravit přístup** na oblasti, které jeho integrace používá. ### Oblasti, které klíč může dostat | Oblast v administraci | Rozsah | Úrovně | Co otevírá | | :- | :- | :- | :- | | **Úkoly** | `tasks` | Čtení, Zápis | Úkoly | | **Inventář** | `inventory` | Čtení, Zápis | **Skladové položky** (`inventory.stock_items`), **SKU** (`inventory.skus`) a **Atributy** (`inventory.attributes`) se skupinami atributů | | **Katalog** | `catalog` | Čtení, Zápis | **Výpisy** (`catalog.listings`), **Sbírky** (`catalog.collections`), **Cenové tabulky** (`catalog.price_tables`) a **Slevy** (`catalog.discounts`) | | **Objednávky** | `orders` | Čtení, Zápis | **Detaily objednávky** (`orders.details`): objednávka, její řádky, zákazníci, skladové položky, plnění, komentáře, dokumenty a protokol aktivit. **Platby** (`orders.payments`): platební transakce, faktury, pokladny a platební odkazy a přijímání a vypořádání plateb | | **Zákazníci** | `customers` | Čtení, Zápis | Zákazníci a vše, co je u nich zaznamenané | | **Online obchod** | `online_store` | Čtení, Zápis | Editor motivu, výchozí obsah a nastavení online obchodu | | **Reporty** | `reports` | Čtení | Prodejní a daňové reporty a exporty reportů a účetních knih | | **Lokace** | `locations` | Čtení, Zápis | Vaše lokace a u každé kontaktní údaje, otevírací doba, prodejní kanály a dokumenty | | **Účet** | `account` | Čtení | [Protokol aktivit](https://www.twicecommerce.com/docs/cs/concepts/admin/activity-logs.md) a historie změn každého záznamu a vyhledávání čárových kódů napříč oblastmi | | **Nastavení účtu** | `settings` | Čtení, Zápis | Jedna oblast pro každou stránku nastavení, viz níže | **Detaily objednávky** a **Platby** jsou oddělené záměrně. Klíč s **Detaily objednávky** čte a vytváří objednávky, aniž by viděl platební transakce, a klíč s **Platby** přijímá platby, aniž by objednávky četl nebo vytvářel. Oblasti pod **Nastavení účtu**: | Oblast v administraci | Rozsah | Úrovně | Co otevírá | | :- | :- | :- | :- | | **Obecné nastavení, objednávky, daně, zásady a šablony e-mailů** | `settings.account` | Čtení, Zápis | Firemní údaje, obecné nastavení, jazyky, nastavení objednávek, daně, zásady a šablony e-mailů | | **Brand a šablony dokumentů** | `settings.content` | Čtení, Zápis | Nastavení brandu a šablony dokumentů | | **Platební metody** | `settings.payments.methods` | Čtení, Zápis | Způsoby, kterými mohou zákazníci platit | | **Platební účty** | `settings.payments.accounts` | Čtení, Zápis | Účty, na které se vypořádávají platby kartou a přes terminál, a čtečky karet | | **Pokladna** | `settings.checkout` | Čtení, Zápis | Nastavení pokladny | | **Odesílání e-mailů** | `settings.emails` | Zápis | Odeslání e-mailu z TWICE Commerce | | **Překlady** | `settings.translations` | Čtení, Zápis | Překlady | | **Domény** | `settings.domains` | Čtení, Zápis | Domény vašeho obchodu | | **Soubory** | `settings.files` | Čtení, Zápis | Správce souborů | | **Webhooky** | `settings.webhooks` | Čtení, Zápis | Webhooky. Integrace, která se přihlašuje k odběru událostí, potřebuje `settings.webhooks.write` | | **Automatizační flow** | `settings.flows` | Čtení, Zápis | Automatizační flow a jejich běhy | **Platební účty** dejte jen integraci, které svěříte rozhodnutí, kam se vaše peníze vypořádají. Kterákoli oblast **Účet** nebo **Nastavení účtu** čte také profil vašeho účtu: měnu, časové pásmo a jazyky. ### Oblasti, kam žádný klíč nedosáhne Tyto oblasti zůstávají lidem přihlášeným do administrace. Žádný klíč na ně nedosáhne, ani s **Plný přístup**: * Klíče API a konektory v **Nastavení → Integrace & API** * Uživatelé a role * Zabezpečení přihlášení * Otevření a uzavření účtu * Předplatné a fakturace * Vlastní profil přihlášeného člověka a jeho uložená zobrazení tabulek ### Vyřešte odmítnutý požadavek Požadavek, na který klíč nemá rozsah, vrátí `403 Forbidden` a `details.requiredScopes` uvádí rozsahy, které by ho otevřely. Přidejte klíči kterýkoli z nich v **Upravit přístup**. ```json Response theme={null} { "requestId": "3184529137502208", "code": "FORBIDDEN", "message": "This API key needs one of these scopes: orders.details.write", "details": { "requiredScopes": ["orders.details.write"] } } ``` Prázdný seznam `requiredScopes` znamená, že toto volání nemůže provést žádný klíč. Když tělo požadavku mění pole patřící do jiné oblasti, odpověď místo toho obsahuje `details.deniedFields`: každá položka uvádí svá pole (`fields`) a jejich rozsahy (`requiredScopes`) a klíč potřebuje jeden rozsah z každé položky. Změna přístupu klíče obvykle platí od dalšího požadavku integrace, nejpozději do pěti minut. ## Použití 1. 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íč**. 2. Vyplňte **Štítek klíče k API**, který pojmenuje integraci, a vyberte, kdy klíči nastane **Vypršení**. Pro integraci, která běží bez dohledu, zvolte **Bez vypršení**. 3. V kroku **Přístup** zvolte **Omezený přístup** a každou oblast, kterou integrace používá, nastavte na **Čtení** nebo **Zápis**. **Plný přístup** zvolte jen pro integraci, která potřebuje všechny oblasti. 4. Stiskněte **Vytvořit klíč API** a klíč zkopírujte. Celá hodnota se zobrazí jen jednou. 5. Přidejte klíč do integrace jako hlavičku požadavku `X-API-KEY`. > [!WARNING] > > Každý klíč uchovávejte jako tajemství a nikdy ho neukládejte do zdrojového kódu. Klíč se **Zápis** na objednávky, platby nebo nastavení je může měnit v celém vašem účtu. Klíč spravujte z nabídky na jeho řádku: * **Upravit přístup** změní oblasti, na které klíč dosáhne. * **Duplikovat** vytvoří nový klíč se stejným štítkem a přístupem a s novým tajemstvím. Původní klíč funguje, dokud nevyprší nebo ho nesmažete. Takto nahraďte uniklý nebo vypršující klíč: přepněte integraci na kopii a pak původní klíč smažte. * **Vymazat** otevře dialog **Smazat klíč API**. Každá integrace, která se tímto klíčem ověřuje, přestane fungovat v okamžiku potvrzení a smazání nelze vrátit zpět. Klíč může vypršet po 1 nebo 6 hodinách nebo po 1, 3, 7, 14, 30, 60, 90, 180 či 365 dnech. Každá odpověď klíči s vypršením nese datum vypršení v hlavičce `X-Api-Key-Expires-At` a sloupec **Vypršení** klíč zvýrazní v jeho posledních 14 dnech. Klíč po vypršení vrací `401` se zprávou "This API key has expired". Platnost nelze prodloužit, proto klíč nahraďte pomocí **Duplikovat**. Klíč posílejte s každým požadavkem na `https://server.twicecommerce.com`. Endpointy pro obchodníky, tedy Admin API TWICE, najdete pod `/v1/admin/`. Příklad výpisu položek katalogu klíčem s rozsahem `catalog.listings.read`: ```bash cURL theme={null} curl "https://server.twicecommerce.com/v1/admin/catalog" \ -H "X-API-KEY: {key}" ``` ```json Response theme={null} { "data": [ { "id": "b4f0a2ce-58d1-4f6e-9a1d-7c2e0f3a9b41", "name": "Trail Bike", "internalName": "trail-bike-2026", "status": "active", "taxonomyCategoryId": null, "createdAt": "2026-07-14T09:32:11.000Z" } ], "pagination": { "page": 0, "pageSize": 50, "total": 1, "totalPages": 1 } } ``` ## Verze API API je verzováno podle data. Aktuální verze je **`2025-06`**. Verzi pošlete v hlavičce `X-API-Version`, čímž požadavek na ni připnete: ```bash cURL theme={null} curl "https://server.twicecommerce.com/v1/admin/catalog" \ -H "X-API-KEY: {key}" \ -H "X-API-Version: 2025-06" ``` Požadavek bez hlavičky verze, nebo s verzí, kterou API nezná, míří na nejnovější verzi. Hlavičku připněte u integrace, kterou nechcete měnit pod rukama při vydání nové verze. Webhooky se připínají samostatně: každý webhook si ponechá verzi, která byla nejnovější v době jeho vytvoření, takže nová verze API nikdy nezmění payload, který už přijímáte. Viz [Webhooky](https://www.twicecommerce.com/docs/cs/concepts/integrations/webhooks.md). > [!NOTE] > > Integrace napsané pro starší cesty `https://server.twicecommerce.com/internal/…` fungují dál, protože tyto URL vedou na `/v1/admin/`. Nové integrace pište proti `/v1/admin/`. ## Limity požadavků API omezuje požadavky ve třech vrstvách: * **Na IP adresu**: ochrana před ověřením. Každá IP adresa klienta má minutový rozpočet požadavků. Požadavky s chybějícím nebo botovým user agentem spotřebují z rozpočtu víc na jedno volání. * **Na účet**: veškerý ověřený provoz vašeho účtu, tedy administrace i klíče API dohromady, sdílí minutový limit, který roste s vaším plánem. * **Na klíč API**: každý klíč má trvalou rychlost požadavků za sekundu, krátkodobou špičkovou rezervu a měsíční strop požadavků. Všechny tři hodnoty rostou s plánem. Měsíční strop je příspěvek volání API, který se sdílí napříč všemi vašimi lokalitami. Odpovědi obsahují hlavičky limitů: | Hlavička | Význam | | :- | :- | | `X-RateLimit-Limit` | Rozpočet požadavků v aktuálním okně limitu | | `X-RateLimit-Remaining` | Zbývající požadavky v okně | | `X-RateLimit-Reset` | Unixové časové razítko (v sekundách), kdy se okno obnoví | | `Retry-After` | Počet sekund čekání před opakováním, posílá se s `429 Too Many Requests` | | `X-RateLimit-Warning` | Nastaví se, když se klíč blíží měsíčnímu stropu | | `X-RateLimit-Overage` | Nastaví se na `true`, když byl požadavek nad měsíčním stropem obsloužen a zaúčtován jako překročení místo odmítnutí | Když požadavek překročí limit, API vrátí `429 Too Many Requests`. Před dalším pokusem počkejte `Retry-After` sekund. Překročení měsíčního stropu nevrací vždy `429`. Účty se zapnutým překročením dostanou požadavek obsloužený a zaúčtovaný jako překročení, účty bez něj dostanou `429` na každé volání nad stropem. Požadavek, který odmítne špičkový limit, se k měsíčnímu stropu nedostane, a proto se do něj nepočítá. Příspěvky pro jednotlivé plány najdete v sekci Ceny stránky [plány](https://www.twicecommerce.com/docs/cs/twice-commerce-overview). ## Související články > **[Reference API](https://www.twicecommerce.com/docs/api-reference)** > > Procházejte všechny endpointy a jejich rozsahy. > **[Webhooky](https://www.twicecommerce.com/docs/cs/concepts/integrations/webhooks.md)** > > Přijímejte události při změně dat. > **[Hromadné vytváření](https://www.twicecommerce.com/docs/cs/concepts/integrations/bulk-creation.md)** > > Vytvořte mnoho záznamů jedním voláním místo smyčky. > **[Nastavení integrací](https://www.twicecommerce.com/docs/cs/settings/integrations.md)** > > Spravujte klíče a propojené systémy. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.