Przegląd API i integracji

Commerce API v1 to publiczne API, przez które Twój sklep przekazuje dane handlowe (katalog, klientów, zamówienia oraz intencje ponownego zakupu — repurchase intent), a CallBotAgent zamienia je w rozmowy telefoniczne i zwraca ustrukturyzowane wyniki. Ta sekcja opisuje kontrakt integracji: formaty danych, uwierzytelnianie, obsługę błędów, limity oraz webhooki.

Bazowy adres wszystkich zasobów to:

https://api.callbotagent.ai/api/v1/commerce

Dla kogo jest to API

Dokumentacja jest przeznaczona dla developerów, którzy integrują sklep (własny backend e-commerce lub platformę spoza gotowych connectorów) z CallBotAgent. Zakładamy, że pracujesz po stronie serwera i możesz bezpiecznie przechowywać tajny sekret klucza — podpisywanie requestów nigdy nie odbywa się w przeglądarce ani w aplikacji mobilnej klienta.

Jeśli korzystasz z gotowego connectora, większość integracji skonfigurujesz bez kodu — patrz Custom store / API connector.

Jak dane sklepu stają się rozmowami

Przepływ end-to-end wygląda tak:

1. Synchronizacja katalogu i klientów — wysyłasz produkty, warianty i dane klientów, aby bot miał kontekst rozmowy.
2. Zdarzenie handlowe — przekazujesz zamówienie albo intencję ponownego zakupu (repurchase intent), która kwalifikuje kontakt do rozmowy.
3. Rozmowa — CallBotAgent wykonuje połączenie zgodnie z regułami sprzedaży i zgodami kontaktowymi.
4. Wynik — otrzymujesz ustrukturyzowany rezultat rozmowy: przez webhook (push) lub przez odpytywanie zasobu wyników (polling).

Mapa dokumentacji

• Szybki start — od utworzenia klucza do pierwszego wyniku w czterech krokach.
• Uwierzytelnianie — HMAC, key ID, nagłówki podpisu, scopes i rotacja kluczy.
• Idempotency — bezpieczne ponawianie mutacji, source_version.
• Błędy — format Problem Details i pełna lista kodów.
• Paginacja i limity — cursor pagination, limity payloadów i rate limits.
• Webhooki — odbiór i weryfikacja zdarzeń push.
• Bezpieczeństwo i dane — ochrona sekretu, TLS, zgody i DNC.

Zasady kontraktu

Wszystkie zasoby dzielą te same konwencje formatów. Trzymaj się ich, aby uniknąć błędów walidacji.

Kwoty przekazuj zawsze jako tekst, a nie liczbę zmiennoprzecinkową — chroni to przed błędami zaokrągleń. Waluta i kwota są zawsze podawane razem.

Kontrakt v1 jest wersjonowany w ścieżce (/v1/). Zmiany niekompatybilne wstecznie trafią do kolejnej wersji; w obrębie v1 dodajemy wyłącznie zgodne rozszerzenia (nowe, opcjonalne pola). Nieznane pola w odpowiedziach ignoruj, zamiast traktować je jako błąd.