Ticaret API'si

ConnectWiz üstüne kendi vitrininizi, mobil uygulamanızı veya ödeme akışınızı kurun. Bu API, iş yeri kataloğunu okur ve panelin, asistanın, sohbet widget'ının ve akışlarınızın kullandığı aynı sipariş defterine yazar — böylece bir kez sitenizden bir kez telefonla alışveriş yapmış müşterinin iki değil tek bir geçmişi olur.

Anahtar almak

Panelde Ayarlar → Geliştirici → API anahtarları'nı açın (Ekim 2026'ya dek anahtarlar Ayarlar → Katalog altındaydı; orası artık yalnız buraya yönlendirir). Bir ad verin, ihtiyacınız olan kapsamları işaretleyin ve oluşturun.

Jeton bir kez gösterilir. Yalnız özeti saklanır, yani tekrar gösterilmesinin bir yolu yoktur — WooCommerce'in kendi REST anahtarlarıyla aynı pazarlık. Listede kısa bir ipucu (ilk karakterler) kalır; böylece hangi anahtarın hangi ortamda olduğunu, gizli bilgiyi elinizde tutmadan ayırt edebilirsiniz.

Widget anahtarını kullanmayın

Widget anahtarı herkese açıktır: sohbeti çalıştıran her sitenin sayfa kaynağında durur. Ticaret anahtarı bir sunucu kimlik bilgisidir. Tarayıcıdan, mobil uygulama paketinden ve deponuzdan uzak tutun.

Kapsamlar

Kapsam	Anahtara ne verir
catalogue:read	ne satıldığını, fiyat ve stokla birlikte okumak
orders:read	adı verilen tek bir müşterinin siparişlerini okumak
orders:write	adı verilen bir müşteri için sipariş oluşturmak
tools:run	çalışma alanının AI araçlarını çalıştırmak — bkz. AI araçları API'si

Yalnız gerekeni verin. Fiyat gösteren bir vitrine birincisi yeter; birine ihtiyaç duyduğu için üçünü birden alan bir anahtar, sızmış bir okuma jetonunun bir yazma olayına dönüşme biçimidir.

Kimlik doğrulama

Jetonu bearer olarak gönderin:

Authorization: Bearer cwz_…

Retler, hata ararken ayırt edebilesiniz diye bilerek farklıdır:

Durum	error	Anlamı
401	missing_token	Authorization başlığı yok
401	unknown_token	Burada o jetonu bilen bir şey yok
403	revoked_token	Gerçek bir anahtar, ama panelden iptal edilmiş
403	missing_scope:<kapsam>	Gerçek bir anahtar, ama o kapsamı yok

Kataloğu okumak

GET /api/commerce/catalogue?q=kimono&limit=50

{
  "data": [
    {
      "id": "01a0…",
      "sku": "KMN-1",
      "name": "Kimono",
      "price": "1200.00",
      "currency": "TRY",
      "kind": "product",
      "available": true
    }
  ]
}

Yalnız aktif ve fiyatlanmış kalemler döner: gösterebileceğiniz ama ücret alamayacağınız bir kalem, müşterinin almaya çalışıp reddedileceği kalemdir.

available iki değil ÜÇ durumludur

true ve false beklediğiniz anlama gelir. Yokluğu, dükkânın stok saymadığı anlamına gelir — bu "tükendi" değildir. Eksik bir available'ı "stokta yok" diye göstermek, iş yerinin seve seve yapacağı satışları reddetmek olur.

Müşteriyi adlandırmak

Her sipariş fiili kimin aldığını bilmek zorundadır. Şunlardan birini verin:

• customer_id — elinizde olan bir ConnectWiz kişi kimliği;
• customer_email ve/veya customer_phone — mevcut kişilerle eşleştirilir.

Sipariş yazarken, hiç görmediğimiz bir e-posta veya telefon yeni bir müşteri açar, başarısız olmaz. Yeni bir alıcının ilk alışverişi, kırılan alışveriş olmamalıdır.

Sipariş oluşturmak

POST /api/commerce/orders
Content-Type: application/json

{
  "customer_email": "[email protected]",
  "customer_name": "Ada Lovelace",
  "items": [{ "item": "KMN-1", "quantity": 2 }],
  "confirm": true
}

item, bir katalog kimliği veya SKU'dur. confirm varsayılan olarak true'dur; önce sepet yazıp ödemeden sonra kesinleştiriyorsanız false gönderin.

Fiyat gönderemezsiniz

Fiyat, ad, iskonto veya vergi oranı için bir parametre yoktur. Hepsi sipariş anında kataloğunuzdan okunur ve satıra anlık görüntü olarak yazılır — böylece müşterinin kabul ettiği şey, yarın ürünü yeniden fiyatlasanız bile ona okunan şey olur.

Bu bilinçlidir ve bizi değil sizi korur: ödeme akışınızdaki bir hata ya da anahtarınızı çalan biri, kendi defterinize bir sayı yazamaz.

Retler 409 ve bir kodla döner:

error	Anlamı
unknown_item:<anahtar>	Katalogda yok ya da artık aktif değil
unpriced_item:<ad>	Henüz kimse fiyatlamamış
mixed_currencies	Bir sipariş, tek para birimi — sizin adınıza seçmeye hakkımız olan bir kur yok
bad_quantity	Sıfır, negatif ya da sayı değil
empty_order	Satır yok

Bir müşterinin siparişlerini okumak

GET /api/commerce/[email protected]

Bir sipariş, hiçbiri diğerinden okunamayan üç bağımsız şey taşır:

• status — belgenin nerede olduğu (draft, confirmed, cancelled);
• delivery — malın nerede olduğu (unfulfilled, processing, shipped, delivered, returned), tracking_number ve carrier ile;
• para, ki tahsilat defterinde yaşar ve asla siparişin bir alanı değildir — bir koli teslim edilip ödenmemiş, ya da ödenip gönderilmemiş olabilir.

"İş yerindeki bütün siparişler" diye bir çağrı bilerek yoktur. O bir rapordur, personel girişinin arkasına aittir, ve onu üretebilen bir anahtar sızmış tek bir jetonu bütün defterinize çevirirdi.

Hız sınırları

Ticaret uçları standart API kısıtını paylaşır. 429'u hemen yeniden denemek için değil, geri çekilmek için bir işaret sayın.