ConnectWiz + API a webhooky
Integrácia v prevádzkeAPI, ktoré predávame, je API, ktoré používame
Celá platforma je opísaná jedným kontraktom OpenAPI, z ktorého sa generuje náš vlastný panel aj mobilná aplikácia – žiadne skryté endpointy, žiadna dokumentácia, ktorá sa rozchádza s realitou. Nad tým stoja Commerce API kľúče s vymedzeným rozsahom, zabezpečené webhookové spúšťače a scenáre, ktoré volajú vaše systémy.
Pre vývojárov
Čo presne robí
Jeden záväzný kontrakt
Platformu opisuje jediný dokument OpenAPI 3 a generujú sa z neho aj naši vlastní klienti v TypeScripte – dokumentácia sa nemôže rozísť s realitou, pretože realita sa stavia z dokumentácie.
Commerce API kľúče
Kľúče, ktoré si vydáva tenant, s výslovne určenými rozsahmi – čítanie katalógu, čítanie objednávok, zápis objednávok – poháňajú váš vlastný e-shop alebo aplikáciu na tom istom objednávkovom systéme a ceny sa vždy určujú na serveri.
Zabezpečené prichádzajúce webhooky
Každý webhookový spúšťač scenára má vlastnú URL a tajný kľúč, overenie HMAC nad surovým telom požiadavky a ochranu proti opakovanému prehraniu. Payload môže pomenovať osobu, no vnútro scenára riadiť nikdy nemôže.
Smerom von cez scenáre
Krok REST volá vaše systémy presne v momentoch, ktoré si nakreslíte na plátne – prijatá objednávka, udelený súhlas, vytvorená rezervácia.
Technické pozadie
Zásady návrhu API povedané nahlas
Ceny nikdy neprichádzajú od klienta
Požiadavka na objednávku hovorí len čo a koľko – názov a cenu si server v tej chvíli načíta z katalógu a zapíše ich do položky ako snímku. Podvrhnutá požiadavka si zľavu nevymyslí.
Najprv schopnosti, potom volania
Každé integračné rozhranie zverejňuje kontrakt svojich schopností – vie párovať podľa telefónu, vypísať objednávky hostí, vytvárať objednávky? – a volanie, ktoré ide proti vyhlásenému „nie“, okamžite skončí chybou namiesto toho, aby zlyhalo niekde hlboko vo vnútri.
Chyby, ktoré niečo znamenajú
Transportná vrstva rozlišuje „neautorizované“ a „služba nefunguje“ – takže z „obchod je nedostupný“ sa nikdy nestane „tento zákazník nikdy nič nekúpil“. Pomenované chyby sú rozdiel medzi API a hádaním.
Webhooky odolné voči opakovaniu
Každá prichádzajúca udalosť si ešte pred spracovaním zaberie jedinečný kľúč v evidencii idempotencie – zopakované alebo znovu prehrané doručenie skončí na úrovni databázy, nie vo vašej automatizácii.
Kľúče hashované, tajomstvá ohraničené
API kľúče sa ukladajú ako hashe a pri vstupe sa dá zistiť len hash a rozsahy – uniknutý riadok databázy nepomenuje žiadny pracovný priestor a neodomkne nič nad rámec svojich rozsahov.
Koncept a potvrdenie sú výslovné
Vytvorenie objednávky má výslovný parameter confirm: verejné API predvolene potvrdzuje, scenáre v paneli môžu pripraviť koncept. Otázka „je to naostro?“ je teda pole, nie zvyklosť.
Nastavenie
Ako sa pripája
Vydajte kľúč
V paneli vytvorte Commerce API kľúč s vymedzeným rozsahom – rovnako ľahko ho aj zrušíte.
Zapojte webhook
Vytvorte scenár s webhookovým spúšťačom a požiadavky podpisujte jeho tajným kľúčom.
Volajte von
Pridajte kroky REST tam, kde sa o udalosti musia dozvedieť vaše systémy.
Spolu lepšie
S čím sa spája
Flows
Webhookové spúšťače spúšťajú scenáre; kroky REST zas volajú vaše systémy v momentoch, ktoré nakreslíte – prichádzajúca aj odchádzajúca automatizácia má jedno spoločné plátno.
Commerce
Náš katalóg a objednávkový systém za týmto API je ten istý, ktorý používa obchod v chate aj AI – jedna pravda o objednávkach, štyri vstupy.
Vlastný e-shop
Tímy už dnes prevádzkujú na Commerce API headless e-shopy – presne túto cestu poctivo odporúča stránka Shopify na obdobie, kým vzniká natívny konektor.
Bezpečnosť a záruky
Nudné záruky
HMAC nad surovým telom
Overenie webhooku podpisuje surové telo požiadavky tajným kľúčom daného spúšťača a porovnáva v konštantnom čase – parsovanie prichádza až po dôkaze.
Payload nesie dáta, nikdy príkazy
Payload webhooku môže odkazovať na osobu, nikdy však nemôže riadiť vnútro scenára, prepisovať prompty ani volať nástroje. Hranicu medzi dátami a inštrukciami určuje architektúra, nie správanie.
Limity požiadaviek na každom vstupe
Verejné endpointy majú štandardné obmedzovanie rýchlosti a limity čítania sa orezávajú na serveri – klient, ktorý sa správa zle, spomalí sám seba, nie platformu.
Drobné písmo bez prikrášľovania
Hranice povedané nahlas
Zatiaľ žiadny prúd všetkých udalostí
Všeobecný webhookový kanál typu „odoberaj všetko“ postavený nie je – odchádzajúce udalosti dnes idú cez kroky scenárov. Píšeme to sem, aby nikto na obchodnom hovore nemusel naznačovať opak.
Ohraničené čítanie, zámerne
Čítanie vráti najviac 100 riadkov a ďalej sa stránkuje kurzorom – API je stavané na prevádzkovú integráciu, nie na hromadný export. Hromadné potreby riešime rozhovorom, nie kľučkou.
Poctivo prepojené je viac než hlasno ohlásené.
Každá integrácia je tu opísaná tým, čo naozaj robí – vrátane smeru, vlastníctva dát a limitov.