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

Referencja API (indeks)

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

Kompletna lista operacji publicznego Commerce API v1. Base URL: https://api.callbotagent.ai/api/v1/commerce. Strony metod są zsynchronizowane z plikiem OpenAPI (wersja 2026.07.11-draft.1).

Zasoby koncepcyjne

Discovery

Metoda i ścieżka Opis Scope Strona
GET /capabilities Wersja kontraktu, limity, obsługiwane order kinds, eventy i feature flags. commerce:read Capabilities
GET /configuration/effective Sanitized effective config, readiness i blockers (bez sekretów ownera). configuration:read Effective configuration

Katalog

Metoda i ścieżka Opis Scope Strona
POST /products/batch Idempotentny upsert maks. 500 produktów z wariantami/kategoriami. catalog:write Upsert katalogu (batch)
GET /products Cursor list / search / filter. catalog:read Lista produktów
GET /products/{externalProductId} Detail produktu z wariantami. catalog:read Szczegóły produktu
DELETE /products/{externalProductId} Tombstone/archive — nigdy hard delete. Może wywołać requalification aktywnych orderów. catalog:write Archiwizuj produkt

Klienci

Metoda i ścieżka Opis Scope Strona
PUT /customers/{externalCustomerId} Profil, locale BCP 47 i dowodem zgody. customers:write Upsert klienta
GET /customers/{externalCustomerId} Sanitized detail (bez zbędnego PII). customers:read Szczegóły klienta
POST /customers/{externalCustomerId}/anonymize Idempotentny erasure / anonymization workflow (GDPR). customers:erase Anonimizacja klienta

Zamówienia

Metoda i ścieżka Opis Scope Strona
POST /orders Create/upsert order (standard) lub repurchase intent — pełne zamówienie, nie lead. orders:write Utwórz zamówienie / intencję ponownego zakupu
GET /orders/{externalOrderId} Canonical order + processing_state. orders:read Szczegóły zamówienia
PATCH /orders/{externalOrderId} Versioned update; po kwalifikacji może uruchomić requalification (CAS). orders:write Aktualizuj zamówienie
POST /orders/{externalOrderId}/cancel CAS-safe cancellation. orders:write Anuluj zamówienie

Wyniki

Metoda i ścieżka Opis Scope Strona
GET /orders/{externalOrderId}/result Final result projection: processing_state, disposition, business_outcome, snapshot. results:read Wynik zamówienia
GET /orders/{externalOrderId}/calls Cursor list attempts + reports/transcript policy. results:read Historia prób rozmów

Reguły

Metoda i ścieżka Opis Scope Strona
PUT /sales-rules/{externalRuleId} replacement/upsell/cross-sell/quantity/price constraint. rules:write Upsert reguły sprzedaży
GET /sales-rules Cursor list reguł sprzedaży. rules:read Lista reguł
GET /sales-rules/{externalRuleId} Detail reguły. rules:read Szczegóły reguły
DELETE /sales-rules/{externalRuleId} Archive rule (nie hard delete). rules:write Archiwizuj regułę

Webhooki

Metoda i ścieżka Opis Scope Strona
GET /webhook-subscription URL masked, events, health — bez sekretu. webhooks:read Odczyt subskrypcji webhook
PUT /webhook-subscription HTTPS URL, event allowlist, active flag. webhooks:write Upsert subskrypcji webhook
POST /webhook-subscription/secret/rotate Reveal-once secret + overlap rotation window. webhooks:write Rotacja sekretu webhook
POST /webhook-subscription/test Ten sam outbox/delivery path, flaga test=true. webhooks:write Test webhook delivery
GET /webhook-deliveries Cursor log z masked/sanitized request/response. webhooks:read Log dostaw webhook
POST /webhook-deliveries/{deliveryId}/replay Nowa attempt tego samego immutable event. webhooks:write Replay dostawy webhook

Konwencje

  • JSON snake_case; money = decimal string + ISO 4217; phone E.164; locale BCP 47.
  • Listy: opaque cursor, limit default 50 / max 200.
  • Mutacje: Idempotency-Key + opcjonalnie source_version (409 przy stale).
  • Błędy: application/problem+json — Błędy.
  • Auth: HMAC.