Klíče API

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.

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) 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 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ů.

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

{
  "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í

Otevřete Nastavení → Integrace & API a v části Klíče API stiskněte Vytvořit klíč.
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í.
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.
Stiskněte Vytvořit klíč API a klíč zkopírujte. Celá hodnota se zobrazí jen jednou.
Přidejte klíč do integrace jako hlavičku požadavku X-API-KEY.

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:

curl "https://server.twicecommerce.com/v1/admin/catalog" \
  -H "X-API-KEY: {key}"

{
  "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:

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.

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.

Související články

Reference API

Procházejte všechny endpointy a jejich rozsahy.

Webhooky

Přijímejte události při změně dat.

Hromadné vytváření

Vytvořte mnoho záznamů jedním voláním místo smyčky.

Nastavení integrací

Spravujte klíče a propojené systémy.

Vítejte v dokumentaci TWICE

Orientace v TWICE

Jak systém funguje

Jak to funguje

Oblasti, které klíč může dostat

Oblasti, kam žádný klíč nedosáhne

Vyřešte odmítnutý požadavek

Použití

Verze API

Limity požadavků

Související články

Reference API

Webhooky

Hromadné vytváření

Nastavení integrací

​Jak to funguje

​Oblasti, které klíč může dostat

​Oblasti, kam žádný klíč nedosáhne

​Vyřešte odmítnutý požadavek

​Použití

​Verze API

​Limity požadavků

​Související články

Reference API

Webhooky

Hromadné vytváření

Nastavení integrací

Jak to funguje

Oblasti, které klíč může dostat

Oblasti, kam žádný klíč nedosáhne

Vyřešte odmítnutý požadavek

Použití

Verze API

Limity požadavků

Související články