ConnectWiz + API i webhooki
Integracja działaAPI, które sprzedajemy, to API, którego używamy
Cała platforma jest opisana jednym kontraktem OpenAPI, z którego generują się nasz własny panel i aplikacja mobilna – żadnych ukrytych endpointów, żadnego rozjeżdżania się dokumentacji. Na tym: klucze API do Commerce z ograniczonym zakresem, zabezpieczone wyzwalacze webhookowe i scenariusze, które wołają Twoje systemy.
Dla programistów
Co dokładnie robi
Jeden wiążący kontrakt
Platformę opisuje jeden dokument OpenAPI 3; generują się z niego nasze własne klienty w TypeScripcie – dokumentacja nie może rozjechać się z rzeczywistością, bo rzeczywistość powstaje z dokumentacji.
Klucze API do Commerce
Klucze wydawane przez tenanta, z jawnymi zakresami – odczyt katalogu, odczyt zamówień, zapis zamówień – zasilają Twój własny sklep albo aplikację na tym samym silniku zamówień, z cenami zawsze ustalanymi po stronie serwera.
Webhooki przychodzące, zabezpieczone
Każdy wyzwalacz webhookowy w scenariuszu ma własny adres URL i własny sekret, weryfikację HMAC po surowej treści oraz ochronę przed powtórzeniem. Ładunek może nazwać człowieka; nigdy nie pokieruje wnętrzem scenariusza.
Na zewnątrz przez scenariusze
Krok REST woła Twoje systemy dokładnie w tych momentach, które narysujesz na kanwie – zamówienie złożone, zgoda udzielona, rezerwacja zrobiona.
Od strony technicznej
Stanowiska projektowe wobec API, wypisane wprost
Ceny nigdy nie przychodzą od klienta
Żądanie zamówienia mówi co i ile – nazwę i cenę odczytujemy w tym momencie z katalogu, po stronie serwera, i zapisujemy w pozycji jako migawkę. Podrobione żądanie nie wymyśli rabatu.
Najpierw możliwości, potem wywołania
Każdy punkt styku integracji publikuje kontrakt możliwości – czy potrafi dopasować po telefonie, wylistować zamówienia gości, utworzyć zamówienie? – a wywołanie wbrew zadeklarowanemu „nie” rzuca błędem od razu, zamiast wysypać się gdzieś głęboko.
Błędy, które coś znaczą
Transport odróżnia „brak uprawnień” od „usługa nie działa” – więc „sklep jest nieosiągalny” nigdy nie wyświetli się jako „ten klient nigdy nic nie kupił”. Nazwane błędy to różnica między API a zgadywanką.
Webhooki odporne na powtórzenia
Każde zdarzenie przychodzące zgłasza unikalny klucz w rejestrze idempotencji przed przetworzeniem – ponowiona albo odtworzona przesyłka umiera w warstwie bazy danych, a nie w Twojej automatyzacji.
Klucze zahaszowane, sekrety z zakresem
Klucze API przechowujemy jako skróty, a przy drzwiach da się odczytać tylko skrót i zakresy – wyciekły wiersz bazy nie nazywa żadnego obszaru roboczego i nie otwiera nic poza swoimi zakresami.
Szkice i potwierdzenia są jawne
Utworzenie zamówienia przyjmuje jawny parametr potwierdzenia – publiczne API domyślnie tworzy zamówienia potwierdzone, a ścieżki w panelu mogą odkładać szkice – więc „czy to jest prawdziwe?” jest polem, a nie konwencją.
Konfiguracja
Jak się łączy
Wydaj klucz
Utwórz w panelu klucz API do Commerce z określonym zakresem; unieważnisz go równie łatwo.
Podłącz webhook
Utwórz scenariusz z wyzwalaczem webhookowym; podpisuj żądania jego sekretem.
Oddzwoń na zewnątrz
Dodaj kroki REST tam, gdzie Twoje systemy muszą się o tym dowiedzieć.
Razem lepiej
Z czym się łączy
Flows
Wyzwalacze webhookowe uruchamiają scenariusze; kroki REST oddzwaniają do Twoich systemów dokładnie w tych momentach, które narysujesz – automatyzacja przychodząca i wychodząca dzielą jedną kanwę.
Commerce
Za tym API stoi ten sam silnik katalogu i zamówień – co w sklepie na czacie i w AI: jedna prawda o zamówieniach, czworo drzwi.
Twój własny sklep
Zespoły prowadzą dziś headlessowe sklepy na Commerce API; tę właśnie drogę uczciwie poleca strona Shopify – dopóki natywny łącznik jest w budowie.
Bezpieczeństwo i gwarancje
Nudne gwarancje
HMAC po surowej treści
Weryfikacja webhooka podpisuje surową treść żądania sekretem właściwym dla danego wyzwalacza i porównuje w stałym czasie – parsowanie zaczyna się dopiero po dowodzie.
Ładunki to dane, nigdy polecenia
Ładunek webhooka może wskazać człowieka; nigdy nie pokieruje wnętrzem scenariusza, nie przepisze promptów ani nie wywoła narzędzi. Granica między danymi a instrukcjami jest architektoniczna, a nie behawioralna.
Limity tempa na każdych drzwiach
Publiczne endpointy jadą na standardowym dławieniu, a limity odczytu są przycinane po stronie serwera – rozbrykany klient pogarsza sobie, a nie platformie.
Drobny druk bez upiększeń
Granice wypisane wprost
Jeszcze bez strumienia wszystkiego
Ogólnego kanału webhooków z subskrypcją wszystkiego nie zbudowaliśmy – zdarzenia wychodzące dzieją się dziś przez kroki w scenariuszach. Piszemy to tutaj, żeby żadna rozmowa handlowa nie musiała sugerować czegoś innego.
Odczyty z granicą, z założenia
Odczyt zwraca do 100 wierszy z kursorowaniem – to API jest zbudowane do integracji operacyjnej, a nie do hurtowego eksportu. Potrzeby hurtowe to temat na rozmowę, a nie furtka.
FAQ o API i webhookach
Odpowiedzi wprost
Więcej w dziale FAQ, a jeśli wolisz – napisz do nas bezpośrednio.
Lepiej połączyć uczciwie niż głośno.
Każda integracja jest tu opisana tym, co naprawdę robi – z kierunkiem, własnością danych i ograniczeniami włącznie.