API đặt hàng AI

Sau khi khách chọn sản phẩm trong cuộc trò chuyện, AI soạn một đơn hàng để khách xác nhận; sau khi khách xác nhận, chúng tôi đề nghị hệ thống của bạn tạo một đơn hàng chờ thanh toán, rồi gửi liên kết thanh toán bạn trả về cho khách. Chúng tôi không lưu đơn hàng và không xử lý tiền hàng.

Trong phần quản trị «Cài đặt bot», điền API đặt hàng (nếu không điền, AI không thể đặt hàng); có thể điền thêm địa chỉ trang đăng nhập: khi khách chưa đăng nhập muốn đặt hàng, nút «Đăng nhập» sẽ xuất hiện trong cửa sổ trò chuyện.

Điều kiện tiên quyết:

• Chỉ khách đã đăng nhập mới có thể đặt hàng, user_id đến từ user_token do bạn phát hành (xem Nhận diện khách đã đăng nhập).
• Sản phẩm phải được đồng bộ qua API mở (xem Cơ sở tri thức và sản phẩm); sản phẩm có phân loại phải có variants[].sku, khi đặt hàng chúng tôi truyền nguyên sku cho bạn.

Khách xác nhận như thế nào:

• Cửa sổ trò chuyện trên web: sau khi AI soạn, thẻ đơn hàng sẽ hiển thị; khách nhấn «Xác nhận đặt hàng» thì mới tạo đơn, sau khi tạo trên thẻ xuất hiện nút «Đi thanh toán».
• Các kênh chỉ gửi được văn bản như WeChat Mini Program: AI gửi tóm tắt đơn hàng cho khách, khách trả lời «Xác nhận» thì mới tạo đơn, sau khi tạo sẽ gửi lối vào thanh toán (xem mp_path bên dưới).

Yêu cầu

Cùng một địa chỉ, phân biệt báo giá và tạo đơn theo mode. Phương thức ký và xác minh chữ ký giống với API tra cứu đơn hàng, thời gian chờ 10 giây.

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

Phản hồi

Báo giá thành công:

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

Tạo đơn thành công:

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

Không thể đặt hàng:

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

• Số tiền đều dùng chuỗi. total và currency là bắt buộc, các trường còn lại có thể bỏ qua; discounts hiển thị tối đa 5 mục.
• pay_url là liên kết thanh toán trên web, phải là https; khi trang «Tích hợp» đã cấu hình danh sách miền được phép, liên kết cũng phải thuộc miền trong danh sách hoặc miền con của miền đó, nếu không sẽ không được hiển thị.
• mp_path là đường dẫn trang thanh toán trong Mini Program, trong kênh WeChat sẽ được gửi cho khách dưới dạng thẻ Mini Program (ảnh bìa dùng ảnh của sản phẩm đầu tiên); nếu không có mp_path thì gửi pay_url. Phải có ít nhất một trong hai.
• expires_at là thời hạn thanh toán, sẽ hiển thị trên thẻ.
• code có các giá trị tùy chọn: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message sẽ được hiển thị trực tiếp cho khách, vui lòng dùng câu từ mà khách hiểu được.
• Nếu không muốn thực hiện báo giá, có thể trả về {"status": "unsupported"} cho quote; thẻ sẽ ước tính theo giá trong danh mục sản phẩm và ghi chú «Số tiền cuối cùng căn cứ theo trang thanh toán».
• Khi create trả về mã không phải 200 hoặc sai định dạng, xác nhận đơn hàng vẫn được giữ, khách có thể nhấn lại một lần nữa; vui lòng đảm bảo request_id trùng lặp không tạo ra đơn hàng thứ hai.

Giới hạn: Xác nhận đơn hàng có hiệu lực trong 30 phút; trong cùng một cuộc trò chuyện, việc soạn xác nhận mới sẽ làm xác nhận cũ hết hiệu lực; một đơn có tối đa 10 loại sản phẩm, mỗi loại tối đa 20 món; trong cùng một cuộc trò chuyện, tối đa tạo 5 đơn trong 24 giờ.