API pro objednávky přes AI asistenta: transakční protokol
Jak navrhnout transakční protokol, ve kterém AI asistent zjistí nabídku, člověk ji potvrdí a systém spolehlivě dokončí objednávku.

API pro objednávky přes AI asistenta musí řešit něco podstatnějšího než převod věty do formuláře. V Evropě, včetně Česka, lze aktuálně objednat jízdu Bolt přes ChatGPT. Pro provozovatele české služby je to hlavně signál, že zákazník může zahájit transakci mimo firemní web. Cena, dostupnost, platba a odpovědnost však stále patří do systému poskytovatele.
Není proto rozumné slibovat napojení na konkrétního asistenta dříve, než existuje spolehlivé transakční jádro. Lepší pořadí je opačné: definovat strojově čitelnou nabídku, stavový model objednávky, souhlas člověka a pravidla pro opakované požadavky. Teprve potom se řeší, zda klientem API bude web, mobilní aplikace nebo konverzační rozhraní.
Co příklad Boltu skutečně mění?
Mění místo, kde zákazník vyjadřuje záměr, nikoli obchodní realitu služby. Uživatel může požádat asistenta o jízdu, ale autoritativní cenu, dostupnost řidiče, stav objednávky a podmínky poskytuje systém služby. Aktuální kontext najdete na oficiálním webu Bolt.
Stejný princip platí pro servisní zásah, pronájem vybavení, kurz, konzultaci nebo ubytování. Asistent může sesbírat parametry a vysvětlit možnosti. Neměl by odhadovat cenu, držet vlastní kopii kalendáře ani považovat starou odpověď za stále platnou nabídku.
Technický návrh proto začíná oddělením tří věcí: záměru zákazníka, ověřené nabídky systému a závazného příkazu. Když jsou slité do jednoho endpointu, těžko se dokazuje, co člověk odsouhlasil a proč systém vytvořil právě tuto objednávku.
Jak má vypadat smlouva mezi asistentem a službou?
Dobré API popisuje obchodní význam, ne jen technický formát. Klient musí zjistit podporované služby, povinné parametry, časové pásmo, měnu, dostupné termíny, platební varianty a podmínky storna. Každá odpověď má jednoznačné typy a stabilní kódy chyb, aby asistent nemusel hádat význam volného textu.
Klíčovým objektem je quote, tedy konkrétní nabídka vytvořená systémem. Obsahuje identifikátor, rozsah služby, položky ceny, konečnou částku, měnu, dostupnost, podmínky a expiraci. Nabídka může být krátkodobá, ale během své platnosti musí být dohledatelná ve stejné podobě, v jaké ji viděl zákazník.
Pokud se mezitím změnila kapacita nebo cena, API vrátí nový quote. Nesmí objednávku tiše dokončit za jiných podmínek. Asistent zobrazí rozdíl a vyžádá nové potvrzení. Pro širší návrh rozhraní lze navázat na článek o API-first návrhu custom systému pro českou SMB firmu.
Jak oddělit souhlas od samotného příkazu?
Člověk má potvrdit konkrétní souhrn bezprostředně před závazným krokem. Souhrn zahrnuje poskytovatele, službu, místo, termín, konečnou cenu, platební metodu a podstatné storno pravidlo. Obecná věta typu zařiď to nestačí, pokud od posledního zobrazení nabídky došlo ke změně.
Po potvrzení vznikne krátce platný autorizační kontext navázaný na identitu uživatele a identifikátor quote. Zápisový endpoint přijme jen takto autorizovaný příkaz. Systém pak umí prokázat, jaká nabídka byla potvrzena, kdy k tomu došlo a který klient příkaz odeslal.
V LucidMark tento přístup popisujeme jako read-first: automatizace může číst, připravit varianty a předvyplnit údaje. Změnu objednávky nebo peněžní operaci potvrzuje člověk a důležitý krok se uloží do auditu. Nejde o obecný příslib bezpečnosti, ale o konkrétní rozdělení oprávnění.
Jak zabránit dvojí objednávce a dvojí platbě?
Každý zápisový příkaz potřebuje idempotency key. Když klient po časovém limitu neví, zda požadavek uspěl, může jej zopakovat se stejným klíčem. Server vrátí původní výsledek místo vytvoření další objednávky. Pokud někdo pod stejným klíčem pošle jiné parametry, požadavek se odmítne.
Tento mechanismus podrobně vysvětluje dokumentace Stripe k idempotentním požadavkům. Stejný princip má chránit vytvoření rezervace, přijetí webhooku i storno. Praktické souvislosti rozebírá také článek o idempotentním webhooku.
Platba má vlastní stavový automat. Nestačí příznak zaplaceno. Systém rozlišuje vznik platebního záměru, požadavek na autorizaci, úspěch, selhání, zrušení a vrácení. Payment Intents ukazují, proč platba může projít několika stavy a proč se konečný výsledek ověřuje podle důvěryhodné události platební brány.
Jak vypadá modelový transakční tok?
Zákazník může vnímat jednu konverzaci, uvnitř však proběhne řízená sekvence s jasnými hranicemi odpovědnosti:
- Asistent převede záměr na strukturované parametry služby.
- Čtecí endpoint ověří dostupnost a vrátí varianty.
- Quote endpoint vytvoří konkrétní nabídku s cenou a expirací.
- Asistent zobrazí souhrn a požádá o výslovné potvrzení.
- Po souhlasu odešle objednávkový příkaz s idempotency key.
- Systém vytvoří objednávku v odpovídajícím mezistavu.
- Platební brána provede potřebnou autorizaci a odešle ověřenou událost.
- Objednávka přejde do potvrzeného stavu a zákazník dostane doklad s identifikátorem.
Každý přechod zapisuje předchozí a nový stav, čas, aktéra, kanál, identifikátor požadavku a důvod. Audit nesmí obsahovat číslo karty nebo zbytečné osobní údaje. Pro kontrolu oprávnění a expozice objektů je užitečný rámec OWASP API Security Project.
Jak řešit storno bez provozního chaosu?
Storno není přepsání stavu na zrušeno. Nejprve čtecí operace vrátí, zda lze objednávku zrušit, do kdy, za jakých podmínek a jaká částka se případně vrátí. Uživatel tento dopad potvrdí a teprve potom se odešle samostatný idempotentní příkaz.
Výsledek storna musí aktualizovat objednávku, platbu, kapacitu i potvrzení zákazníka. Pokud je nutný zásah pracovníka, API vrátí stav čeká na zpracování, nikoli falešný úspěch. Podpora díky auditu vidí, kterou nabídku zákazník přijal, co bylo účtováno a jak storno pokračovalo.
Jaký checklist má projít česká SMB služba?
Před hledáním konkrétní integrace zkontrolujte připravenost vlastního systému. Praktický checklist zahrnuje:
- Jeden zdroj pravdy pro katalog, kapacitu, cenu a stav objednávky.
- Oddělené operace pro vyhledání, quote, objednávku, platbu a storno.
- Quote s identifikátorem, měnou, položkami ceny, podmínkami a expirací.
- Výslovný souhlas navázaný na konkrétní verzi nabídky.
- Idempotency key u každého zápisu a zpracování webhooku.
- Samostatný stavový model objednávky a platby.
- Storno s předběžným vyčíslením dopadu a následným potvrzením.
- Audit přechodů bez citlivých platebních údajů.
- Role, omezení oprávnění a cesta k člověku pro nejednoznačné případy.
- Testy opakovaných požadavků, expirovaných nabídek a zpožděných událostí.
Co připravit jako první?
API pro objednávky přes AI asistenta začíná mapou stavů a odpovědností. Sepište, odkud pochází cena, kdy je kapacita závazně držena, co přesně potvrzuje zákazník, jak se obnovuje přerušená platba a co se stane při opakovaném požadavku.
Příklad objednání Boltu přes ChatGPT ukazuje nový vstupní kanál. Dlouhodobou hodnotu ale vytváří protokol, který funguje stejně spolehlivě pro vlastní web i budoucí schválené klienty. Dobře popsané API, ověřený quote, lidský souhlas, idempotence a auditní stopa jsou základ, na kterém lze další rozhraní stavět bez přepisování obchodních pravidel.


