AI Sipariş API'si

Müşteri sohbette ürünleri seçtikten sonra AI, onaylaması için bir sipariş taslağı oluşturur; müşteri onayladıktan sonra sisteminizden bir ödeme bekleyen sipariş oluşturmasını isteriz ve döndürdüğünüz ödeme bağlantısını müşteriye iletiriz. Siparişleri saklamayız ve ödeme tutarlarına aracılık etmeyiz.

Yönetim panelindeki “Bot ayarları” bölümünde sipariş oluşturma API'sini girin (boş bırakırsanız AI sipariş oluşturamaz); ayrıca giriş sayfası adresini de girebilirsiniz: oturum açmamış bir müşteri sipariş vermek istediğinde sohbet penceresinde “Giriş yap” düğmesi görünür.

Ön koşullar:

• Yalnızca oturum açmış müşteriler sipariş oluşturabilir; user_id, sizin verdiğiniz user_token içinden gelir (bkz. Oturum açmış müşterileri tanımlama).
• Ürünler Open API üzerinden senkronize edilmelidir (bkz. Bilgi tabanı ve ürünler); varyantları olan ürünlerde variants[].sku bulunmalıdır; sipariş oluştururken sku değerini olduğu gibi size iletiriz.

Müşteri nasıl onaylar:

• Web sohbet penceresi: AI taslağı hazırladıktan sonra bir sipariş kartı gösterir; sipariş ancak müşteri “Siparişi onayla”ya tıkladığında oluşturulur ve oluşturulduktan sonra kartta “Ödemeye git” düğmesi görünür.
• WeChat Mini Program gibi yalnızca metin gönderebilen kanallar: AI sipariş özetini müşteriye gönderir; sipariş ancak müşteri “Onayla” yanıtını verdikten sonra oluşturulur ve ardından ödeme girişi gönderilir (aşağıda mp_path bölümüne bakın).

İstek

Aynı adres, mode değerine göre fiyat teklifi ve sipariş oluşturma için kullanılır. İmzalama ve imza doğrulama yöntemi Sipariş sorgulama API'si ile aynıdır; zaman aşımı 10 saniyedir.

POST {你的下单接口}
Content-Type: application/json
X-AICS-Timestamp: 1761120000
X-AICS-Signature: v1=<hex>

{
  "mode": "quote",
  "request_id": "chk_3f2a9c...",
  "user_id": "u_123",
  "conversation_id": "b3c1...",
  "channel": "widget",
  "language": "en",
  "country": "US",
  "items": [{"product_id": "w1", "sku": "w1-black", "qty": 1}]
}

Yanıt

Fiyat teklifi başarılı:

{
  "status": "quoted",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "discounts": [{"label": "新客券", "amount": "20.00"}],
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Sipariş oluşturma başarılı:

{
  "status": "created",
  "order_no": "T2026102300001",
  "pay_url": "https://shop.example.com/pay?orderno=T2026102300001",
  "mp_path": "pages/order/pay?orderno=T2026102300001",
  "expires_at": "2026-10-23T12:30:00Z",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Sipariş oluşturulamıyor:

{"status": "rejected", "code": "OUT_OF_STOCK", "message": "这款黑色暂时缺货"}

• Tüm tutarlar string olarak gönderilir. total ve currency zorunludur; diğerleri isteğe bağlıdır. discounts en fazla 5 kayıt gösterir.
• pay_url web ödeme bağlantısıdır ve https olmalıdır; “Entegrasyon” sayfasında alan adı beyaz listesi yapılandırılmışsa, beyaz listedeki bir alan adında veya alt alan adında olmalıdır; aksi halde gösterilmez.
• mp_path, Mini Program içindeki ödeme sayfası yoludur; WeChat kanalında müşteriye Mini Program kartı olarak gönderilir (kapak görseli ilk ürünün görselidir); mp_path yoksa pay_url gönderilir. İkisinden en az biri bulunmalıdır.
• expires_at ödeme son tarihidir ve kartta gösterilir.
• code için olası değerler: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message doğrudan müşteriye gösterilir; lütfen müşterinin anlayacağı bir ifade kullanın.
• Fiyat teklifi vermek istemiyorsanız quote için {"status": "unsupported"} döndürebilirsiniz; kart, ürün kataloğundaki fiyatlara göre tahmini bir tutar gösterir ve “Nihai tutar ödeme sayfasına göre belirlenir” notunu ekler.
• create 200 dışında bir yanıt döndürürse veya yanıt biçimi hatalıysa sipariş onayı korunur ve müşteri yeniden tıklayabilir; lütfen aynı request_id ile ikinci bir sipariş oluşturulmadığından emin olun.

Sınırlamalar: Sipariş onayı 30 dakika boyunca geçerlidir; aynı sohbette yeni bir taslak oluşturmak eski taslağı geçersiz kılar; bir siparişte en fazla 10 farklı ürün ve her üründen en fazla 20 adet olabilir; aynı sohbette 24 saat içinde en fazla 5 sipariş oluşturulabilir.