Váš obchod.
Vaše aplikace.

První požadavek

1. Přihlaste se do pohni.cz, připojte obchod a ověřte jeho předplatné.
2. Ve správě API klíčů vytvořte klíč s oprávněním products.read. Tajnou hodnotu si uložte při vytvoření.
3. Na serveru aplikace nastavte SHOPSENSE_ORIGIN na provozní adresu uvedenou v přehledu API klíčů a SHOPSENSE_API_KEY na svůj tajný klíč. Obě hodnoty načítejte z konfigurace serveru.

curl --fail-with-body \
  "$SHOPSENSE_ORIGIN/api/shopsense/v1/products" \
  -H "Shoptet-Access-Token: $SHOPSENSE_API_KEY"

// Tento kód běží na serveru vaší aplikace.
const origin = process.env.SHOPSENSE_ORIGIN;
const key = process.env.SHOPSENSE_API_KEY;
if (!origin || !key) throw new Error("Chybí konfigurace API");

const response = await fetch(new URL("/api/shopsense/v1/products", origin), {
  headers: { "Shoptet-Access-Token": key },
  signal: AbortSignal.timeout(100_000),
});
const result = await response.json();
if (!response.ok || result.errors?.length) {
  throw new Error("API požadavek nebyl úspěšný");
}
const products = result.data.products;

<?php
// Tajný klíč načítejte ze serverového prostředí.
$origin = rtrim(getenv('SHOPSENSE_ORIGIN') ?: '', '/');
$key = getenv('SHOPSENSE_API_KEY');
if (!$origin || !$key) throw new RuntimeException('Chybí konfigurace API');

$request = curl_init($origin . '/api/shopsense/v1/products');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 100,
    CURLOPT_HTTPHEADER => ['Shoptet-Access-Token: ' . $key],
]);
$body = curl_exec($request);
if ($body === false) throw new RuntimeException('Požadavek se nepodařil');
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
curl_close($request);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || !empty($result['errors'])) {
    throw new RuntimeException('API požadavek nebyl úspěšný');
}

Požadavek používá obchod přiřazený ke klíči. Identifikátor jiného obchodu mu nepřidávejte.

Klíče a oprávnění

Použijte jednu hlavičku: Shoptet-Access-Token s naším klíčem, nebo Authorization: Bearer. Požadavek s oběma hlavičkami je odmítnutý. Klíče neposílejte v URL.

Klíč má tvar ss_sk_…. Při vytvoření dostanete jeho plnou hodnotu jednou; přehled potom ukazuje pouze prefix. Pro každou integraci vytvořte samostatný klíč a nastavte nejmenší potřebná oprávnění.

Oprávnění povoluje pouze operace zveřejněné v referenci. Přístup se zároveň řídí současným členstvím, stavem obchodu a platností předplatného. Vydání klíče předplatné neprodlužuje.

Výměna a odvolání

Vytvořte nový klíč, nastavte ho na serveru aplikace a ověřte první požadavek. Potom starý klíč odvolejte v přehledu. Při úniku klíče ho odvolejte ihned. Tajnou hodnotu neposílejte podpoře.

Podporované operace

Všechny cesty níže začínají /api/shopsense/v1. Profil pracuje s administrativními ID připojeného obchodu. Nepřijímá oficiální GUID ani parametry, které nejsou uvedené v referenci.

Datová pole a omezení

Názvy mají 1 až 200 znaků, bez HTML. Popisky mají nejvýše 12 000 znaků a přijímají prostý text nebo podporované jednoduché HTML bez atributů. Neposílejte skripty, odkazy, obrázky ani styly.

Detail produktu může obsahovat indexName, code, ean, description, shortDescription, visibility, price, currencyId, taxClassId, defaultCategoryId a categoryIds, pokud jsou dostupná ve zdroji. Chybějící hodnoty se nevymýšlejí. Číselné hodnoty formuláře mohou zůstat řetězci; cenu nepovažujte za převedený oficiální cenový model.

Odpovědi a chyby

JSON odpověď obsahuje data, errors a metadata. V metadatech najdete requestId a profil. Při podpoře stačí identifikátor požadavku; neposílejte klíč ani obsah obchodu.

Výpisy produktů a kategorií uvádějí rozsah v data.listing, včetně limit, returned a complete:false. Čtení může zahrnovat jen část administrativního přehledu. Omezený výsledek nepovažujte za úplný export katalogu.

Provozní limity

Počáteční profil má omezenou sdílenou kapacitu. Uvedené limity jsou ochrany provozu, nikoli příslib rychlosti nebo dostupnosti.

Od verze0.5.46 gateway uvádí v Retry-After počet sekund do resetu; starší nebo časné vstupní limity mohou vrátit60, obsazená kapacita5. Hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset popisují minutovou kvótu klíče; reset je Unix čas v sekundách. Vedle ní platí společná kvóta vydávajícího uživatele a kapacita. U zápisů se tím nepovoluje opakované provedení; nejdřív ověřte evidovaný výsledek.

IP omezení nového klíče (od0.5.46)

Při vydání můžete povolit nejvýše16 IPv4/IPv6 adres nebo kanonických sítí CIDR svého serveru. Prázdný seznam povoluje libovolnou IP. Změna seznamu vyžaduje nový klíč a odvolání původního. Podvržená hlavička nebo doména toto omezení nenahrazuje; klíč stále nepatří do JavaScriptu e-shopu.

API nepodporuje podmíněné ani částečné HTTP požadavky. Hlavičky If-None-Match, If-Modified-Since, If-Match, If-Unmodified-Since, If-Range a Range vracejí 400. Platí to i pro veřejný katalog. Nepoužívejte je jako ochranu souběžného zápisu; tuto sémantiku služba neimplementuje.

Zápisy a opakování

Ke každému zápisu přidejte hlavičku Idempotency-Key s unikátním identifikátorem operace: 8 až 128 znaků z A–Z a–z 0–9 . _ : -. Stejný identifikátor použijte pouze pro tentýž požadavek. Opakované volání vrací stav evidovaného požadavku a samo znovu neprovádí změnu.

curl --fail-with-body \
  -X POST "$SHOPSENSE_ORIGIN/api/shopsense/v1/products" \
  -H "Shoptet-Access-Token: $SHOPSENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-product-unique-operation" \
  --data '{"name":"Testovací produkt","defaultCategoryId":12}'

V příkladu nahraďte defaultCategoryId skutečným ID vlastní kategorie a identifikátor operace vytvořte pro každý nový záměr zvlášť. Klíč potřebuje oprávnění products.write.

Přerušení spojení nebo timeout neprokazuje, že se změna neprovedla. Při nejasném výsledku nezakládejte nový požadavek s jiným klíčem. Nejdřív ověřte stav operace a výsledek v obchodě. Nepřidávejte automatické retry zápisů do HTTP klienta.

Stav rejected znamená prokázané odmítnutí před odesláním změny do Shoptetu. Po odstranění příčiny můžete vytvořit nový požadavek s novým identifikátorem. Stav uncertain takové potvrzení nedává a nový zápis nesmí následovat bez ověření. Chybový kód WRITE_OUTCOME_UNKNOWN je samostatná informace v chybové odpovědi.

Klíč s oprávněním zápisu je souhlas s podporovanými operacemi dané integrace. Jejich přesný obsah a omezení ověřte před zapnutím automatizace. Oprávnění tohoto klíče nemění přístup připojených AI asistentů.

Co patří do frontendu e-shopu

Tajný API klíč patří na server integrace. HTML a JavaScript vložený do Shoptetu si může návštěvník přečíst, včetně všech vložených klíčů. Kontrola domény nebo CORS z veřejného klíče tajný údaj neudělá.

Pokud nemáte vlastní backend, použijte serverovou funkci nebo konkrétní hostovaný postup. Obecnou proxy s tajným klíčem veřejnosti nezpřístupňujte. Návštěvník e-shopu tím nesmí získat přístup správce.

Veřejný výběr produktů — omezený pilot

Pro serverově povolený pilot připravíte v dashboardu přesný náhled veřejných názvů a odkazů. Teprve výslovné zveřejnění vytvoří odkaz /api/public/v1/catalogs/… a ukázku JavaScriptu bez tajného klíče. Obchodník musí mít aktuální přístup správce a předplatné.

Výběr má nejvýše 20 položek a 12 KB. Odpověď obsahuje pouze products[publicId,name,publicURL], complete:false, verifiedAt a expiresAt. Neobsahuje ceny, sklad ani administrativní identifikátory a nepředstavuje celý katalog. Platí nejvýše 24 hodin od ověření; čtení platnost neprodlužuje a změny produktů se do něj automaticky nepřenášejí.

Anonymní GET/HEAD čte pouze uloženou publikaci. Použijte credentials:"omit" a cache:"no-store"; neposílejte API klíč. Chybějící, vypnutý nebo prošlý výběr vrací obecnou 404, překročení limitu 429 s Retry-After. Katalog lze v dashboardu vypnout i po skončení předplatného. Vypnutí smaže obsah publikace ze živé databáze; pravidelný úklid maže prošlý obsah. Tento postup neslibuje okamžité odstranění z databázových záloh.

Dostupné pouze pro serverově povolený pilot. Citlivé změny obchodu nejsou součástí anonymního odkazu.

Hostovaná změna názvu produktu — omezený pilot

Pro serverově povolený pilot otevřete hostovanou změnu názvu produktu. Do frontendu nemusíte vkládat API klíč. Přihlásíte se do pohni.cz, ručně vyberete obchod a produkt, připravíte přesný náhled původního a nového názvu a změnu samostatně potvrdíte. Náhled platí pět minut. Potřebujete současné oprávnění vlastníka nebo správce, zápis do obchodu a platné stávající předplatné.

Samotný odkaz nic neschvaluje a změnu nespustí. Po nejistém výsledku zápis neopakujte. Nejprve ručně zkontrolujte uložený stav požadavku; potom můžete samostatně načíst aktuální stav produktu. Čtení je možné nejdříve pět minut od začátku původního pokusu a jeho další ochranné podmínky ověří server. Shoda současného názvu nepotvrzuje úspěch původního zápisu a nejistý požadavek dál blokuje další změnu v tomto hostovaném postupu.

Tento přihlášený ruční postup není stabilní programmatic API a nepřidává další operaci do administrativního ani kompatibilního profilu. Jeho interní HTTP route nepoužívejte jako náhradu serverové integrace.

Přechod z oficiálního Shoptet API

pohni.cz je nezávislá služba. Náš klíč není oficiální Shoptet token a profil shopsense-admin-v1 má vlastní kontrakt s 10 nativními operacemi. Pouhá změna domény v existující integraci nezaručuje kompatibilitu.

Samostatná kompatibilní OpenAPI specifikace popisuje pole a omezení dostupných GET pilotů. Úplnou shodu s oficiálním Shoptet API, včetně všech chyb a stránkování, negarantujeme.

Pilot vyžaduje serverově povolený obchod, současný přístup a předplatné i scope uvedený u operace. Pošlete právě jednu hlavičku Shoptet-Access-Token nebo Shoptet-Private-Api-Token s naším klíčem ss_sk_… a povinný Content-Type: application/json; volitelný UTF-8 charset je povolený. Obě token hlavičky současně, Authorization: Bearer, query parametry a tělo GET se odmítají. Klíč patří na server integrace; browser požadavky se odmítají a CORS není povolený.

Seznamy mailing lists, jednotek a záruk podporují pouze úplnou první stránku, nejvýše 250 položek. Neúplný, vícestránkový, nekonzistentní nebo změněný výsledek se odmítá bez částečné odpovědi. Úplnost vůči oficiálnímu Shoptet API pro každé nastavení poskytovatele negarantujeme.

U záruk se inMonths:null, -1 pro doživotní záruku, 0 a počet měsíců zachovávají bez převodu či odvozování z názvu nebo ID. system je boolean; záporná ID jsou systémová, kladná vlastní. Počty použití a další metadata se nevracejí. Mailing lists nevracejí adresy příjemců.

Úspěšná obálka má data, errors:null a metadata.requestId. Chybové kódy a instance:"shopsense" jsou rozšíření pohni.cz s vlastním významem. Úplnou shodu všech hodnot a chyb s oficiálním Shoptet API negarantujeme.

Při migraci porovnejte používané operace s naší referencí, upravte autentizaci a identifikátory a ověřte význam každého zapisovaného pole. Ostatní oficiální cesty, GUID, eventy, platební a addonové kontexty tím nejsou slíbené. Pro oficiální kontrakt použijte dokumentaci Shoptet API.