Zapowiedź

Dokumentacja poglądowa. Interfejs jest w trakcie udostępniania — przykłady mają charakter zapowiedzi, a finalne wartości potwierdzimy przy starcie.

Szybki start

Ten przewodnik przeprowadzi Cię od utworzenia klucza do odebrania pierwszego wyniku rozmowy w czterech krokach. Wszystkie wywołania kierujesz na bazowy adres https://api.callbotagent.ai/api/v1/commerce, a każdy request podpisujesz kluczem HMAC. W przykładach key ID jest zawsze maskowany: cba_test_••••••••.

Zanim zaczniesz

Aktywne konto i skonfigurowany sklep.
Klucz API z sekretem (tworzysz go w panelu — sekret zobaczysz tylko raz).
Środowisko po stronie serwera, w którym bezpiecznie przechowasz sekret.

Cztery kroki

Utwórz klucz API

W panelu wygeneruj parę: publiczny key_id oraz tajny sekret. Zapisz sekret w bezpiecznym miejscu (menedżer sekretów, zmienne środowiskowe). Nadaj kluczowi tylko potrzebne scopes — do tego scenariusza wystarczą orders:write i results:read. Szczegóły: Uwierzytelnianie.

Podpisz request

Zbuduj kanoniczny string z metody, ścieżki, query, znacznika czasu, nonce oraz hasha body i policz podpis HMAC-SHA256. Dołącz nagłówki X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Nonce, X-CBA-Content-SHA256 i X-CBA-Signature. Znacznik czasu musi mieścić się w oknie 300 sekund. Pełny algorytm opisuje sekcja Uwierzytelnianie.

Wyślij zamówienie lub intencję ponownego zakupu

Wykonaj POST /orders, aby przekazać zdarzenie handlowe kwalifikujące kontakt do rozmowy. Do mutacji dołącz nagłówek Idempotency-Key, aby bezpiecznie ponowić request — patrz Idempotency. Przykład niżej.

Odbierz wynik

Wynik rozmowy otrzymasz na dwa sposoby: przez webhook (push, rekomendowane) albo przez odpytywanie zasobu wyników (polling z użyciem scope results:read). Webhook jest szybszy i nie obciąża limitów odczytu.

Przykład: utworzenie zamówienia

POST /orders

curl -X POST "https://api.callbotagent.ai/api/v1/commerce/orders" \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-11T10:00:00Z" \
  -H "X-CBA-Nonce: 6a1f9c2e-7b40-4d2a-9c11-2e5f8a0d1b33" \
  -H "X-CBA-Content-SHA256: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4" \
  -H "X-CBA-Signature: hmac-sha256=…" \
  -H "Idempotency-Key: 9f4e6c1a-2d5b-4c8e-9a7f-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
        "external_id": "ORD-2026-0001",
        "currency": "PLN",
        "total_amount": "129.00",
        "locale": "pl-PL",
        "customer": { "phone": "+48512345678" },
        "line_items": [
          { "sku": "SKU-100", "quantity": 1, "unit_amount": "129.00" }
        ]
      }'

const res = await fetch(`${baseUrl}/api/v1/commerce/orders`, { method: 'POST', headers: signedHeaders(keyId, body), body: JSON.stringify(body) });

$response = $client->post('/api/v1/commerce/orders', ['headers' => signed_headers($keyId, $body), 'json' => $body]);

Odpowiedź 201 Created zawiera identyfikator zamówienia po stronie CallBotAgent. Jeśli ten sam Idempotency-Key powtórzysz z identycznym body, otrzymasz tę samą zapisaną odpowiedź, a nie duplikat.

Następne kroki

Idempotency — jak bezpiecznie ponawiać zapisy.
Paginacja i limity — rozmiary payloadów i rate limits.
Błędy — jak czytać application/problem+json.
Custom store / API connector — pełna konfiguracja integracji własnego sklepu.