Upsert katalogu (batch)
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 /products/batch
Opis
Idempotentny upsert maks. 500 produktów z wariantami/kategoriami. Base URL: https://api.callbotagent.ai/api/v1/commerce.
Wymagany scope
catalog: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 |
|---|---|---|---|
products[] |
array | tak | Lista produktów (max 500) |
products[].external_product_id |
string | tak | Stabilny ID produktu partnera |
products[].variants[] |
array | tak | Max 100 wariantów; price+currency wymagane |
products[].source_version |
string | tak | Monotoniczna wersja źródła |
Przykład żądania
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-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-products-batch-post" \
-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","source_version":"2026-07-11T09:00:00Z","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-11T10:00:00Z",
"X-CBA-Nonce": "n_8f3a2c1b",
"X-CBA-Content-SHA256": "<sha256-body>",
"X-CBA-Signature": "hmac-sha256=<hex>",
"Idempotency-Key": "idem-products-batch-post",
"Content-Type": "application/json",
},
body: JSON.stringify({"products":[{"external_product_id":"SKU-ROUTER-01","title":"Router Mesh Home","category":"sieci/routery","status":"active","availability":"in_stock","source_version":"2026-07-11T09:00:00Z","variants":[{"external_variant_id":"SKU-ROUTER-01-BLK","price":"349.00","currency":"PLN","inventory":42,"min_quantity":1,"max_quantity":5}]}]}),
});
const data = await res.json();Przykładowa odpowiedź
{
"accepted": 1,
"rejected": 0,
"results": [
{
"external_product_id": "SKU-ROUTER-01",
"outcome": "upserted"
}
]
}
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 |