Přejít na hlavní obsah
Na této stránce▾

Vlastní obchod nebo ERP je takový, pro který neexistuje hotový plug-in, takže váš vývojář připojuje konfigurátor k košíku sám. Pravidlo, které stojí za vším zde, je jedna věta: cena, kterou poslal prohlížeč, se nesmí nikdy stát cenou v košíku. Váš server ji nejprve ověří u CutOptim.

CutOptim nevybírá platby a nehostuje obchod; košík, pokladna a platba zůstávají vaše. Zatím neexistuje SDK. Referenční dokumentace API konfigurátoru uvádí každou trasu, chybový kód a limit, s dokumentem OpenAPI 3.1; tato stránka, stránka o objednávkách a referenční kód provedou integrací krok za krokem.

Dva klíče

  • Veřejný klíč (publishable key) je na vaší stránce pro vložení. Může dělat jen to, co nakupující, a jen z domén, které jste pro něj uvedli.
  • Tajný klíč (secret key) je pro váš server a nikdy se nedává na stránku. Posílá se jako Authorization: Bearer <key> na službu, ve výchozím nastavení https://cfg.cutoptim.com. U požadavku POST vždy posílejte Content-Type: application/json.

Krok 1: ověřte nabídku před košíkem

Když zákazník objedná, vaše stránka obdrží událost cutoptim:order s tokenem nabídky. Pošlete token na svůj server a odtud:

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

Odpověď je 200 s {"valid": true, "redeemed": false, "claims": {...}} nebo {"valid": false, "reason": "..."}. Odmítnutí je stále 200, takže čtěte valid. Vypršení časového limitu, 401, 500 nebo nečitelné tělo berte jako neověřeno a řádek odmítněte. Poté porovnejte údaje (claims) s řádkem košíku: tenant je váš, měna je měna košíku, platnost je v budoucnosti a hash nabídky se rovná hashi nabídky, kterou zobrazila vaše stránka. Referenční kód obsahuje funkci, která tento hash počítá.

Lokální kontrola tvaru tokenu, tenanta a platnosti je levnější, ale nemůže prokázat podpis, protože podpisový klíč se nevydává. Používejte ji jen jako předběžnou kontrolu.

Krok 2: zkontrolujte objednávku

Ověření nabídky ukazuje, že slib ceny je pravý. Neukazuje, kterou objednávku prohlížeč myslí. Než něco uložíte nebo vyřídíte podle id objednávky, načtěte ji na svém serveru pomocí GET /cfg/v1/orders/{id} a svého tajného klíče. Vrátí hash plánu, hash nabídky, stav, měnu a tři součty v nejmenších jednotkách, a žádné osobní údaje. Porovnejte je s tím, co jste ověřili.

Krok 3: přijměte webhook

Nastavte webhook podle popisu na stránce o objednávkách. Váš příjemce:

  1. přečte surové tělo dříve, než ho zpracuje;
  2. přečte hlavičku CutOptim-Signature ve tvaru t=<unix seconds>,v1=<hex> (během obměny tajemství mohou být dvě hodnoty v1);
  3. přepočítá HMAC-SHA256(secret, "<t>.<raw body>"), porovná v konstantním čase a odmítne časové razítko vzdálené více než asi pět minut;
  4. převezme id události z CutOptim-Event-Id dříve, než udělá jakoukoli práci, a id, které už zpracoval, ignoruje;
  5. ignoruje typy událostí, které nezná, a odpoví 2xx, aby odesílatel zbytečně neopakoval.

Tajemství příjemce získáte pomocí POST /cfg/v1/admin/webhooks/{id}/secret a svého tajného klíče. Tajemství uchovávejte ve svém prostředí, nikdy na stránce, v repozitáři ani v protokolu.

Referenční kód

Dva malé příklady bez závislostí ukazují všechny tři kroky. Jsou to kódy ke čtení a kopírování, ne hostovaná služba:

Jejich tajemství jsou zástupné hodnoty. Úložiště duplicit v paměti v příkladech je náhrada: v produkci uchovávejte zpracovaná id událostí ve své databázi a id převezměte ve stejné transakci, která zaznamenává objednávku.

Stejné kroky s přesnými požadavky a odpověďmi jsou v referenci: Vlastní obchod nebo ERP.

Obměna klíčů

Klíč nebo tajemství webhooku lze obměnit s překryvem, takže starý stále funguje po nastavenou dobu, zatímco nasazujete nový. Během obměny webhooku nese doručení po dobu sedmi dnů dva podpisy v1 a přijetí kteréhokoli z nich umožňuje přepnout bez výpadku. Tlačítka v konzoli pro obměnu s překryvem zatím nejsou hotová; konzole klíče umí vytvářet a rušit.

Jiné způsoby příjmu objednávek

Pro WooCommerce použijte plug-in. Pokud potřebujete jen plány řezání uvnitř vlastního softwaru, bez vložené zákaznické obrazovky, jde o Engine API.

FAQ

Potřebuji plug-in, abych mohl konfigurátor použít ve vlastním obchodě?
Ne. Konfigurátor se vkládá skriptem a elementem a váš server dělá tři věci: ověří nabídku před košíkem, zkontroluje objednávku, ke které patří, a ověří podepsaný webhook. Tato stránka je popisuje a odkazuje na referenční kód v Node a PHP. Pro WooCommerce existuje hotový plug-in; pro žádnou jinou platformu ne.
Jak můj server zkontroluje cenu?
Pošle token nabídky na POST /cfg/v1/quote/verify na službě konfigurátoru se svým tajným klíčem. Odpověď říká, zda je platná a zda už byla uplatněna. Poté porovná údaje (claims) v tokenu s vlastním řádkem košíku: tenant, měnu, platnost a hash nabídky. Kontrola provedená jen lokálně nemůže prokázat podpis, proto podle ní o ceně nikdy nerozhodujte.
Spotřebuje ověření nabídky její platnost?
Ne. Ověření je jen pro čtení. Nabídku spotřebuje pouze zadání objednávky, a to jednou. Platná nabídka se může vrátit jako již uplatněná, proto zkontrolujte obě pole.
Jak poznám, že id objednávky z prohlížeče je objednávka, kterou jsem ověřil?
Vyhledejte ji na svém serveru: GET /cfg/v1/orders/{id} s tajným klíčem vrátí hash plánu, hash nabídky, stav a součty té objednávky, nikdy osobní údaje. Porovnejte je s ověřenou nabídkou. Bez toho by se levná ověřená nabídka mohla poslat vedle id jiné objednávky.
Existuje SDK nebo dokument OpenAPI?
Neexistuje SDK ani hostovaný adaptér, ale existuje referenční dokumentace API: každá trasa, chybový kód a limit, s dokumentem OpenAPI 3.1 na adrese /configurator/openapi.json, který umí přečíst generátor klientů. Referenční soubory jsou malé příklady bez závislostí v Node a PHP, které si přečtete a zkopírujete. Python, Java a C# pokryty nejsou; podpis je obyčejný HMAC-SHA256, takže ho zvládne jakýkoli jazyk.
Které události konfigurátoru mohu přijímat?
order.created a order.status_changed. Další názvy událostí, které konfigurace přijímá, například události nabídek nebo projektů, se nikdy neodesílají. Doručení je alespoň jednou, proto si vedte záznam o id událostí, které jste zpracovali.

Aktualizováno: 19. října 2026