Dùng endpoint này để ghi nhận một giao dịch bán trong Subiz, ví dụ khi có đơn đặt trong cửa hàng hoặc CRM của bạn. Xem Định dạng đơn hàng để biết mọi trường.
Trước khi bắt đầu
- Lấy Bearer access token và ID tài khoản.
- Lấy ID user Subiz của khách hàng. Mọi đơn hàng đều cần khách hàng. Dùng Tìm hoặc tạo theo định danh kênh hoặc Tạo khách hàng trước nếu cần.
Body yêu cầu
| Trường | Kiểu | Mô tả |
|---|---|---|
user.id |
string | Bắt buộc. ID của một khách hàng đã có. |
items |
array | Các dòng của đơn. Mỗi dòng có quantity và một product với name, sku và price. |
source_id |
string | Nên có. ID đơn hàng của riêng bạn. Xem Tránh trùng lặp. |
currency |
string | Đơn vị tiền tệ của các số tiền, như VND. Rỗng nghĩa là tiền tệ gốc của tài khoản. |
shipping |
object | Địa chỉ giao hàng và nominal_fee. |
status |
string | Tùy chọn. open (mặc định), unconfirmed, closed hoặc canceled. |
number |
string | Tùy chọn. Mã đơn hàng. Không được trùng với đơn khác. |
note, private_note |
string | Ghi chú tùy chọn. |
discount_type, discount_amount, discount_percentage |
Chiết khấu cấp đơn tùy chọn. |
Các dòng giữ nguyên dữ liệu sản phẩm bạn gửi, kể cả price. Hãy gửi đúng giá đã bán; Subiz không tra cứu lại giá.
Nếu một dòng có product.source_id nhưng không có product.id, Subiz liên kết nó với sản phẩm trong danh mục có source ID đó và dùng dữ liệu trong danh mục. Nếu chưa có sản phẩm như vậy, Subiz tạo một sản phẩm mang tên là source ID, không có giá.
Trường do Subiz đặt
Không gửi các trường sau; Subiz tự đặt hoặc tính:
id,created,created_by,updated.subtotal,total_tax,totalvàtotalcủa từng dòng, được tính từ mặt hàng, chiết khấu, phí giao hàng và khoản điều chỉnh.payment_madevàpayment_status, được tính từ các khoản thanh toán đã ghi nhận trên đơn. Đơn mới ở trạng tháiunpaid.user.attributes: nếu bạn bỏ trốngfullnamehoặcphonescủa khách hàng, Subiz sao chép từ hồ sơ khách hàng.pipeline_stage: nếu bạn không gửi pipeline, đơn bắt đầu ở giai đoạn đầu tiên của pipeline bán hàng mặc định.
Tránh trùng lặp
Đặt source_id là ID của đơn trong hệ thống của bạn. Nếu đã có đơn cùng source_id, Subiz thay thế đơn đó bằng các trường bạn gửi thay vì tạo đơn mới. Điều này giúp thử lại an toàn. Luôn gửi đơn hàng đầy đủ.
Nếu không có source_id, mỗi yêu cầu tạo một đơn mới. Đừng thử lại mù quáng sau khi hết thời gian chờ; hãy kiểm tra bằng Lấy danh sách đơn hàng trước.
Phản hồi
Yêu cầu thành công trả HTTP 200 cùng đơn đã lưu, gồm id và các tổng tiền đã tính. Một số trường:
{
"id": "order_example",
"account_id": "account_example",
"source_id": "crm-1001",
"status": "open",
"payment_status": "unpaid",
"currency": "VND",
"user": {
"id": "user_example"
},
"subtotal": 240000,
"total": 270000,
"created": 1763107200000
}
Lưu id để đọc hoặc cập nhật đơn sau này.
Lỗi
| Vấn đề | Kết quả |
|---|---|
Thiếu user.id |
Lỗi nêu tên user bị thiếu. |
| Khách hàng không tồn tại | Lỗi không tìm thấy user. |
status không thuộc bốn giá trị ở trên |
Lỗi dữ liệu không hợp lệ cho status. |
number đã được dùng |
Yêu cầu thất bại. Dùng mã khác hoặc bỏ trống. |
Xem Xử lý lỗi để biết định dạng lỗi.
Yêu cầu HTTP
Thay YOUR_ACCID, YOUR_USER_ID, YOUR_SOURCE_ORDER_ID và YOUR_ACCESS_TOKEN bằng giá trị của bạn.
POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"source_id": "YOUR_SOURCE_ORDER_ID",
"user": {
"id": "YOUR_USER_ID"
},
"currency": "VND",
"items": [
{
"quantity": 2,
"product": {
"name": "Ceramic mug",
"sku": "MUG-01",
"price": 120000
}
}
],
"shipping": {
"address": {
"fullname": "Alex Example",
"phone": "+84900000000",
"address": "12 Example Street",
"region": "Ho Chi Minh City",
"country_code": "VN"
},
"nominal_fee": 30000
}
}