Zapowiedź

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

Produkty, warianty, kategorie

Katalog to podstawa rozmów: bez aktualnego produktu, ceny i dostępności system nie zbuduje poprawnego skryptu. Zasób Products utrzymujesz jako lustro sklepu — zwykle jednym zbiorczym uploadem, a potem aktualizacjami przyrostowymi.

Base URL: https://api.callbotagent.ai/api/v1/commerce. Każde żądanie podpisujesz nagłówkami HMAC (X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Signature); mutacje dodają Idempotency-Key. Budowa podpisu: ./authentication.md, semantyka powtórzeń: ./idempotency.md.

Model produktu

Ciało w JSON snake_case. Ceny to decimal string z osobnym kodem waluty ISO 4217.

Pole	Typ	Opis
`external_product_id`	string	Twój identyfikator produktu (klucz upsertu).
`title`	string	Nazwa produktu widoczna w skrypcie rozmowy.
`category`	string	Kategoria/ścieżka katalogowa używana przez reguły sprzedaży.
`status`	enum	`active` \| `draft` \| `archived`.
`availability`	enum	`in_stock` \| `out_of_stock` \| `preorder`.
`variants[]`	array	Do 100 wariantów na produkt.
`archived_at`	string \| null	Znacznik RFC 3339 UTC ustawiany przy archiwizacji.

Wariant (variants[]): external_variant_id (SKU), price (decimal string, np. "149.00"), currency (ISO 4217), inventory (integer; 0 = brak dostępności), min_quantity, max_quantity (integer | null).

Operacje

POST /products/batch

Idempotentny upsert do 500 produktów na żądanie (po 100 wariantów każdy). Scope catalog:write. Powtórzenie z tym samym Idempotency-Key zwraca ten sam wynik.

curl -X POST https://api.callbotagent.ai/api/v1/commerce/products/batch \
  -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: catalog-sync-2026-07-10-01" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{
      "external_product_id": "SKU-ROUTER-01", "title": "Router Mesh Home",
      "category": "sieci/routery", "status": "active", "availability": "in_stock",
      "variants": [{ "external_variant_id": "SKU-ROUTER-01-BLK",
        "price": "349.00", "currency": "PLN",
        "inventory": 42, "min_quantity": 1, "max_quantity": 5 }]
    }]
  }'
# 200 OK → { "accepted": 1, "rejected": 0,
#   "results": [{ "external_product_id": "SKU-ROUTER-01", "outcome": "upserted" }] }

const body = { products: [{
  external_product_id: "SKU-ROUTER-01", title: "Router Mesh Home",
  category: "sieci/routery", status: "active", availability: "in_stock",
  variants: [{ external_variant_id: "SKU-ROUTER-01-BLK", price: "349.00",
    currency: "PLN", inventory: 42, min_quantity: 1, max_quantity: 5 }],
}] };
const res = await fetch(
  "https://api.callbotagent.ai/api/v1/commerce/products/batch",
  { method: "POST", headers: {
    "X-CBA-Key-Id": "cba_test_••••••••",
    "X-CBA-Timestamp": "2026-07-10T12:34:56Z",
    "X-CBA-Signature": "v1=9f8c2a...e41",
    "Idempotency-Key": "catalog-sync-2026-07-10-01",
    "Content-Type": "application/json",
  }, body: JSON.stringify(body) },
);
const data = await res.json(); // { accepted: 1, rejected: 0, results: [...] }

$body = ["products" => [[
  "external_product_id" => "SKU-ROUTER-01", "title" => "Router Mesh Home",
  "category" => "sieci/routery", "status" => "active", "availability" => "in_stock",
  "variants" => [["external_variant_id" => "SKU-ROUTER-01-BLK", "price" => "349.00",
    "currency" => "PLN", "inventory" => 42, "min_quantity" => 1, "max_quantity" => 5]],
]]];
$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/products/batch");
curl_setopt_array($ch, [
  CURLOPT_POST => true, 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: catalog-sync-2026-07-10-01",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($body),
]);
$data = json_decode(curl_exec($ch), true); // { accepted: 1, ... }

GET /products

Lista z paginacją opaque cursor (?cursor=…&limit=50, maks. 200) i filtrami (status, availability, category). Scope catalog:read.

GET /products/{externalProductId}

Zwraca pojedynczy produkt z wariantami; brak zasobu → 404 resource_not_found.

DELETE /products/{externalProductId}

Archiwizacja (tombstone), nigdy hard delete. Produkt dostaje status: archived i archived_at, znika z nowych rozmów, ale pozostaje powiązany z historycznymi zamówieniami i regułami. Operacja jest idempotentna; wariant z inventory: 0 nie jest oferowany w rozmowie.