واجهة API لإنشاء الطلبات عبر AI

بعد تأكيد العميل للطلب في المحادثة، نستدعي واجهة API الخاصة بك لإنشاء طلب بانتظار الدفع، ثم نسلّم رابط الدفع إلى العميل.

بعد أن يختار العميل المنتجات في المحادثة، يصوغ AI مسودة طلب ليعرضها على العميل للتأكيد؛ وبعد تأكيد العميل نطلب من نظامك إنشاء طلب بانتظار الدفع، ثم نعرض على العميل رابط الدفع الذي تُعيده. نحن لا نحفظ الطلبات ولا نتعامل مع أموال الدفع.

في لوحة التحكم ضمن «إعدادات الروبوت»، املأ واجهة إنشاء الطلبات (إذا تُركت فارغة فلن يستطيع AI إنشاء طلب)، ويمكنك أيضًا ملء عنوان صفحة تسجيل الدخول: عندما يرغب عميل غير مسجّل في إنشاء طلب، يظهر زر «تسجيل الدخول» في نافذة الدردشة.

الشروط المسبقة:

يمكن للعملاء المسجّلين فقط إنشاء طلبات، ويأتي user_id من user_token الذي تُصدره أنت (راجع التعرّف على العملاء المسجّلين).
يجب مزامنة المنتجات عبر API المفتوح (راجع قاعدة المعرفة والمنتجات)؛ أما المنتجات التي لها متغيّرات فيجب أن تتضمّن variants[].sku، وعند إنشاء الطلب نمرّر sku إليك كما هو.

كيف يؤكّد العميل:

نافذة الدردشة على الويب: بعد صياغة AI تظهر بطاقة الطلب، ولا يُنشأ الطلب إلا بعد أن يضغط العميل «تأكيد الطلب»، وبعد إنشائه يظهر زر «الانتقال إلى الدفع» على البطاقة.
قنوات لا تدعم سوى النص مثل برنامج WeChat المصغّر: يُرسل AI ملخّص الطلب إلى العميل، ولا يُنشأ الطلب إلا بعد أن يردّ العميل بـ «تأكيد»، وبعد إنشائه نرسل مدخل الدفع (راجع mp_path أدناه).

الطلب

نفس العنوان، ويُستخدم mode للتمييز بين عرض السعر وإنشاء الطلب. طريقة التوقيع والتحقق من التوقيع هي نفسها المستخدمة في واجهة استعلام الطلبات، ومهلة الانتظار 10 ثوانٍ.

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}]
}

الحقل	الوصف
`mode`	`quote`: حساب السعر فقط (الخصومات، رسوم الشحن، الضريبة)، دون إنشاء طلب أو حجز مخزون؛ `create`: إنشاء طلب بانتظار الدفع
`request_id`	تُستخدم القيمة نفسها لعرض السعر وإنشاء الطلب لتأكيد الطلب نفسه. عندما يستقبل `create` قيمة `request_id` مكرّرة يجب أن يُعيد الطلب نفسه، فنحن نعتمد عليها لمنع إنشاء طلبات مكرّرة عند إعادة المحاولة أو النقر المتكرر من العميل
`user_id`	العميل المسجّل، ولا يمكن إنشاء طلب إلا لهذا العميل
`channel`	`widget` / `wechat_mp` / `api`
`language`، `country`	لغة العميل والدولة التي يقع فيها عنوان IP، وقد تكون `null`، ويمكن استخدامهما لاختيار عملة التسوية وحساب الضريبة
`items[].product_id` / `sku`	قيمة `external_id` للمنتج و`sku` الخاص بالمتغيّر؛ ويكون `sku` مساويًا `null` للمنتجات التي ليس لها متغيّرات

الاستجابة

نجاح عرض السعر:

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

نجاح إنشاء الطلب:

{
  "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"
}

تعذّر إنشاء الطلب:

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

تُرسل جميع المبالغ كسلاسل نصية. الحقلان total وcurrency إلزاميان، ويمكن حذف الباقي؛ ويُعرض من discounts 5 عناصر كحد أقصى.
pay_url هو رابط الدفع على الويب ويجب أن يكون https؛ وإذا تم إعداد قائمة نطاقات مسموح بها في صفحة «التكامل»، فيجب أن يقع أيضًا على أحد نطاقات القائمة أو أحد نطاقاتها الفرعية، وإلا فلن يُعرض.
mp_path هو مسار صفحة الدفع داخل البرنامج المصغّر، ويُرسل في قناة WeChat إلى العميل كبطاقة برنامج مصغّر (تُستخدم صورة أول منتج كغلاف)؛ وعند غياب mp_path نرسل pay_url. يجب توفّر أحدهما على الأقل.
expires_at هو الموعد النهائي للدفع، وسيظهر على البطاقة.
القيم المتاحة لـ code: OUT_OF_STOCK، SKU_UNAVAILABLE، REGION_UNAVAILABLE، NOT_LOGGED_IN، LIMIT، OTHER. يُعرض message مباشرة للعميل، لذا استخدم عبارة يفهمها العميل.
إذا لم ترغب في تنفيذ عرض السعر، يمكنك إرجاع {"status": "unsupported"} لـ quote، وستقدّر البطاقة السعر وفق أسعار كتالوج المنتجات، مع الإشارة إلى «المبلغ النهائي حسب صفحة الدفع».
إذا أعاد create رمزًا غير 200 أو كانت الصيغة غير صحيحة، فيبقى تأكيد الطلب محفوظًا ويمكن للعميل الضغط مرة أخرى؛ يُرجى التأكد من أن request_id المكرّر لن يُنشئ طلبًا ثانيًا.

القيود: يكون تأكيد الطلب صالحًا لمدة 30 دقيقة، وصياغة تأكيد جديد في المحادثة نفسها تُلغي القديم؛ يمكن أن يضم الطلب الواحد 10 أنواع منتجات كحد أقصى، و20 قطعة لكل نوع كحد أقصى؛ ويمكن إنشاء 5 طلبات كحد أقصى في المحادثة نفسها خلال 24 ساعة.

هل كانت هذه الصفحة مفيدة؟

آخر تحديث: 31 أكتوبر 2026