Zapowiedź

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

Zamówienia i intencje ponownego zakupu

Zasób Orders obsługuje dwa rodzaje obiektów, rozróżniane polem order_kind:

standard — kanoniczne zamówienie ze sklepu (potwierdzenie, dosprzedaż, weryfikacja).
repurchase_intent — intencja ponownego zakupu (repurchase intent): kompletne zamówienie „w zamiarze" (pozycje, ceny, ilości) do potwierdzenia w rozmowie z klientem.

Intencja ponownego zakupu to pełne zamówienie, a nie kontakt do przetworzenia — przechodzi tę samą kwalifikację, harmonogram i model wyniku co zamówienie standard.

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.

Pola intencji ponownego zakupu

Pole	Typ	Opis
`order_kind`	enum	`standard` \| `repurchase_intent`.
`contact_not_before`	string	Przewidywana data kontaktu (RFC 3339 UTC).
`priority`	integer	Priorytet w kolejce (wyższy = pilniejszy).
`confidence`	string	Pewność przewidywania jako decimal string `0`–`1`, np. `"0.82"`.
`items[]`	array	Pozycje: `external_variant_id`, `quantity`, `price`, `currency`.
`contact_permission`	object	Podstawa kontaktu: `basis`, `reference`.

Operacje

POST /orders

Tworzy lub upsertuje zamówienie albo intencję ponownego zakupu (wg order_kind). Scope orders:write. Odpowiedź zawiera processing_state (start: received).

curl -X POST https://api.callbotagent.ai/api/v1/commerce/orders \
  -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: order-RB-5510-01" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "RB-5510", "order_kind": "repurchase_intent",
    "external_customer_id": "CUSTOMER-8821",
    "contact_not_before": "2026-07-14T08:00:00Z", "priority": 5, "confidence": "0.82",
    "items": [{ "external_variant_id": "SKU-ROUTER-01-BLK", "quantity": 1, "price": "349.00", "currency": "PLN" }],
    "contact_permission": { "basis": "prior_purchase", "reference": "order-4821" }
  }'
# 201 Created → { "external_order_id": "RB-5510", "processing_state": "received" }

const body = {
  external_order_id: "RB-5510", order_kind: "repurchase_intent",
  external_customer_id: "CUSTOMER-8821",
  contact_not_before: "2026-07-14T08:00:00Z", priority: 5, confidence: "0.82",
  items: [{ external_variant_id: "SKU-ROUTER-01-BLK", quantity: 1, price: "349.00", currency: "PLN" }],
  contact_permission: { basis: "prior_purchase", reference: "order-4821" },
};
const res = await fetch("https://api.callbotagent.ai/api/v1/commerce/orders", {
  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": "order-RB-5510-01",
    "Content-Type": "application/json",
  }, body: JSON.stringify(body),
});
const data = await res.json(); // { external_order_id: "RB-5510", processing_state: "received" }

$body = [
  "external_order_id" => "RB-5510", "order_kind" => "repurchase_intent",
  "external_customer_id" => "CUSTOMER-8821",
  "contact_not_before" => "2026-07-14T08:00:00Z", "priority" => 5, "confidence" => "0.82",
  "items" => [["external_variant_id" => "SKU-ROUTER-01-BLK", "quantity" => 1, "price" => "349.00", "currency" => "PLN"]],
  "contact_permission" => ["basis" => "prior_purchase", "reference" => "order-4821"],
];
$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/orders");
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: order-RB-5510-01",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($body),
]);
$data = json_decode(curl_exec($ch), true); // { external_order_id: "RB-5510", ... }

GET /orders/{externalOrderId}

Zwraca kanoniczne zamówienie wraz z aktualnym processing_state. Scope orders:read.

PATCH /orders/{externalOrderId}

Wersjonowana aktualizacja (optimistic concurrency przez source version); zmiana pozycji/kwot uruchamia ponowną kwalifikację. Nieaktualna wersja → 409 stale_source_version.

POST /orders/{externalOrderId}/cancel

Anulowanie odporne na wyścig (CAS-safe): dla completed/cancelled zwraca stan bez zmian.

GET /orders/{externalOrderId}/result GET /orders/{externalOrderId}/calls

Wynik (final_order_snapshot) i próby kontaktu — pełny opis w ./results.md; powiadomienia o zmianach: ./webhooks.md.