Zapowiedź

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

Kwalifikacja i harmonogram

Kwalifikacja i harmonogram nie są zestawem endpointów partnera — to polityka po stronie platformy, przez którą przechodzi każde przyjęte zamówienie i każda intencja ponownego zakupu. Partner dostarcza dane i zawęża ofertę, ale nie może poluzować polityki właściciela konta.

Base URL: https://api.callbotagent.ai/api/v1/commerce. Żądania podpisujesz HMAC (X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Signature).

Ścieżka przyjętego zamówienia

Po POST /orders rekord przechodzi kolejne bramki. Każda może go odrzucić (wtedy processing_state: rejected z powodem) albo przepuścić dalej:

Etap	Sprawdzenie
Zgoda	`consent.status: granted` i ważny dowód zgody klienta.
DNC	Numer nie znajduje się na liście Do-Not-Call ani nie został wycofany.
Filtry	Filtry właściciela (tagi, wykluczenia produktów/kategorii, reguły sprzedaży).
Dostępność	Produkt i wariant `active` oraz dostępny (`inventory > 0`).
Budżet	Konto ma dostępny budżet/pojemność na kontakt.

Po pozytywnej kwalifikacji rekord trafia do harmonogramu: okna godzin i dni, strefa czasowa klienta, ciche godziny oraz contact_not_before (dla intencji — przewidywana data). System nie zadzwoni wcześniej niż pozwala najbardziej restrykcyjne z tych ograniczeń.

Hierarchia polityk

Gdy ustawienia się nakładają, wygrywa najbardziej restrykcyjne. Kolejność nadrzędności:

Priorytet	Warstwa	Może
1 (najwyższy)	DNC i zgodność	zablokować kontakt bezwarunkowo
2	Właściciel konta	ustawić okna, budżet, filtry, ciche godziny
3 (najniższy)	Partner (API)	tylko zawężać ofertę i cel w ramach 1–2

Partner nigdy nie rozszerza polityki. Ustawienia przysłane przez API mogą wyłącznie zawęzić to, co dopuścił właściciel konta i wymogi zgodności (DNC, zgody).

Podgląd efektywnej konfiguracji

GET /configuration/effective

Read-only. Zwraca efektywną konfigurację, gotowość (readiness) i listę blokerów — bez żadnych sekretów. Scope configuration:read. Użyj do diagnozy „dlaczego rekord nie dzwoni".

curl https://api.callbotagent.ai/api/v1/commerce/configuration/effective \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-10T12:34:56Z" \
  -H "X-CBA-Signature: v1=9f8c2a...e41"
# 200 OK → {
#   "readiness": "blocked",
#   "calling_windows": { "timezone": "Europe/Warsaw", "days": ["mon","tue","wed","thu","fri"],
#     "hours": "09:00-17:00" },
#   "blockers": [{ "code": "no_budget", "message": "Brak dostępnego budżetu na kontakt" }]
# }

const res = await fetch(
  "https://api.callbotagent.ai/api/v1/commerce/configuration/effective",
  { headers: {
    "X-CBA-Key-Id": "cba_test_••••••••",
    "X-CBA-Timestamp": "2026-07-10T12:34:56Z",
    "X-CBA-Signature": "v1=9f8c2a...e41",
  } },
);
const cfg = await res.json();
// { readiness: "blocked", calling_windows: {...}, blockers: [{ code: "no_budget", ... }] }

$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/configuration/effective");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-CBA-Key-Id: cba_test_••••••••",
    "X-CBA-Timestamp: 2026-07-10T12:34:56Z",
    "X-CBA-Signature: v1=9f8c2a...e41",
  ],
]);
$cfg = json_decode(curl_exec($ch), true);
// { readiness: "blocked", calling_windows: {...}, blockers: [...] }

Stan processing_state pojedynczego rekordu odczytasz przez GET /orders/{externalOrderId} (./orders.md); pełny model wyniku i prób opisuje ./results.md.