Zapowiedź

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

Reguły sprzedaży i ograniczenia

Zasób Sales Rules steruje tym, co system może zaproponować w rozmowie: zamianę wariantu, dosprzedaż (upsell), sprzedaż komplementarną (cross-sell) oraz ograniczenia ilości i ceny. Regułę identyfikujesz swoim external_rule_id, więc upsert jest idempotentny.

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

Model reguły

Pole	Typ	Opis
`external_rule_id`	string	Twój identyfikator reguły (klucz upsertu).
`rule_type`	enum	`substitution` \| `upsell` \| `cross_sell` \| `quantity_limit` \| `price_constraint`.
`priority`	integer	Kolejność stosowania, gdy pasuje więcej niż jedna reguła (wyższy = wcześniej).
`applies_to`	object	Zakres: `category`, `external_product_id` lub `external_variant_id`.
`action`	object	Efekt reguły, np. `suggest_variant`, `min_quantity`, `max_quantity`, `price_floor`.
`enabled`	boolean	Czy reguła jest aktywna.

Reguły wskazują produkty i warianty po Twoich identyfikatorach z zasobu ./products.md. Zarchiwizowany produkt automatycznie wyłącza powiązane reguły.

Operacje

PUT /sales-rules/{externalRuleId}

Idempotentny upsert reguły. Scope rules:write.

curl -X PUT https://api.callbotagent.ai/api/v1/commerce/sales-rules/RULE-UPSELL-01 \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-10T12:34:56Z" \
  -H "X-CBA-Signature: v1=9f8c2a...e41" \
  -H "Idempotency-Key: rule-upsell-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "external_rule_id": "RULE-UPSELL-01", "rule_type": "upsell", "priority": 10,
    "applies_to": { "category": "sieci/routery" },
    "action": { "suggest_variant": "SKU-ROUTER-01-PRO", "max_quantity": 3 },
    "enabled": true
  }'
# 200 OK → { "external_rule_id": "RULE-UPSELL-01", "outcome": "upserted", "enabled": true }

const body = {
  external_rule_id: "RULE-UPSELL-01", rule_type: "upsell", priority: 10,
  applies_to: { category: "sieci/routery" },
  action: { suggest_variant: "SKU-ROUTER-01-PRO", max_quantity: 3 },
  enabled: true,
};
const res = await fetch(
  "https://api.callbotagent.ai/api/v1/commerce/sales-rules/RULE-UPSELL-01",
  { method: "PUT", headers: {
    "X-CBA-Key-Id": "cba_test_••••••••",
    "X-CBA-Timestamp": "2026-07-10T12:34:56Z",
    "X-CBA-Signature": "v1=9f8c2a...e41",
    "Idempotency-Key": "rule-upsell-01-01",
    "Content-Type": "application/json",
  }, body: JSON.stringify(body) },
);
const data = await res.json(); // { external_rule_id: "RULE-UPSELL-01", outcome: "upserted" }

$body = [
  "external_rule_id" => "RULE-UPSELL-01", "rule_type" => "upsell", "priority" => 10,
  "applies_to" => ["category" => "sieci/routery"],
  "action" => ["suggest_variant" => "SKU-ROUTER-01-PRO", "max_quantity" => 3],
  "enabled" => true,
];
$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/sales-rules/RULE-UPSELL-01");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "PUT", 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",
    "Idempotency-Key: rule-upsell-01-01",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($body),
]);
$data = json_decode(curl_exec($ch), true); // { external_rule_id: "RULE-UPSELL-01", ... }

GET /sales-rules

Lista z paginacją opaque cursor (?cursor=…&limit=50, maks. 200) i filtrem rule_type. Scope rules:read.

GET /sales-rules/{externalRuleId}

Zwraca pojedynczą regułę; brak zasobu → 404 resource_not_found.

DELETE /sales-rules/{externalRuleId}

Archiwizacja, nigdy hard delete. Reguła zostaje oznaczona jako nieaktywna i przestaje być stosowana, ale pozostaje w historii. Operacja jest idempotentna.

Reguły partnera zawężają ofertę, ale nie mogą poluzować polityki właściciela konta ani ograniczeń zgodności — pełna hierarchia w ./qualification-scheduling.md.