callbotagent.aiDokumentacja
v1 · Contract draft
ENPL
Otwórz panel
Zapowiedź

Utwórz zamówienie / intencję ponownego zakupu

Dokumentacja poglądowa / kontrakt symulowany (draft). Schematy i przykłady odzwierciedlają zaplanowane Commerce API v1 — wartości finalne potwierdzimy przy zamrożeniu kontraktu produkcyjnego.

POST /orders

Opis

Create/upsert order (standard) lub repurchase intent — pełne zamówienie, nie lead. Base URL: https://api.callbotagent.ai/api/v1/commerce.

Wymagany scope

orders:write

Nagłówki

Nagłówek Wartość Wymagany
Content-Type application/json (gdy body) przy body
X-CBA-Key-Id identyfikator klucza (w przykładach: cba_test_••••••••) tak
X-CBA-Timestamp RFC 3339 UTC tak
X-CBA-Nonce unikalny nonce w oknie 300 s tak
X-CBA-Content-SHA256 SHA-256 hex surowego body (e3b0c44… dla pustego) tak
X-CBA-Signature hmac-sha256=<hex> tak
Idempotency-Key klucz idempotencji mutacje: tak

Parametry body

Pole Typ Wymagane Opis
order_kind enum tak standard
external_order_id string tak Stabilny ID zamówienia partnera
external_customer_id string tak Referencja klienta
items[] array tak Pozycje: variant, quantity, price, currency
contact_permission object tak status + dowód zgody (szczególnie repurchase)
source_version string tak Monotoniczna wersja źródła
contact_not_before datetime nie Najwcześniejszy kontakt (RFC 3339)
priority integer nie Priorytet kolejki
confidence string nie Decimal string 0–1

Przykład żądania

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: n_8f3a2c1b" \
  -H "X-CBA-Content-SHA256: <sha256-body>" \
  -H "X-CBA-Signature: hmac-sha256=<hex>" \
  -H "Idempotency-Key: idem-orders-post" \
  -H "Content-Type: application/json" \
  -d '{"external_order_id":"RB-5510","order_kind":"repurchase_intent","external_customer_id":"CUSTOMER-8821","source_version":"2026-07-11T09:00:00Z","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":{"status":"granted","basis":"prior_purchase","reference":"order-4821"}}'

Przykładowa odpowiedź

{
  "external_order_id": "RB-5510",
  "order_kind": "repurchase_intent",
  "processing_state": "received",
  "correlation_id": "corr_7c2f4d10"
}

Możliwe błędy

Status code Znaczenie
401 invalid_signature / expired_timestamp / replay_nonce HMAC / okno replay
403 insufficient_scope brak wymaganego scope
404 resource_not_found zasób niedostępny dla principal
409 idempotency_key_reused / stale_source_version konflikt idempotencji / wersji
422 validation_failed body nie spełnia schematu / invariants
429 rate_limited limity — patrz Retry-After

Powiązane