SubizTài liệu API
Đơn hàng

API 4.0

Định dạng đơn hàng

Hiểu đối tượng đơn hàng: mặt hàng, khách hàng, giao hàng, số tiền và trạng thái.

Order ghi lại những gì khách hàng đã mua: mặt hàng, giá, thông tin giao hàng, thanh toán và trạng thái. Trang này mô tả đối tượng đơn hàng và các đối tượng lồng bên trong. Mọi ID và giá trị bên dưới chỉ mang tính minh họa.

Để làm việc với đơn hàng, xem Tạo đơn hàng, Lấy danh sách đơn hàng, Lấy thông tin đơn hàng và Cập nhật đơn hàng.

Đơn hàng

Một số trường của Order:

{
  "id": "order_example",
  "account_id": "account_example",
  "number": "1001",
  "status": "open",
  "payment_status": "unpaid",
  "currency": "VND",
  "user": {
    "id": "user_example"
  },
  "items": [
    {
      "id": "item_example",
      "quantity": 2,
      "product": {
        "id": "product_example",
        "name": "Ceramic mug",
        "sku": "MUG-01",
        "price": 120000
      },
      "total": 240000
    }
  ],
  "shipping": {
    "address": {
      "fullname": "Alex Example",
      "phone": "+84900000000",
      "address": "12 Example Street",
      "district": "District 1",
      "region": "Ho Chi Minh City",
      "country_code": "VN"
    },
    "nominal_fee": 30000
  },
  "subtotal": 240000,
  "total": 270000,
  "payment_made": 0,
  "note": "Please deliver after 5 pm.",
  "related_conversations": [
    "conversation_example"
  ],
  "created": 1763107200000,
  "updated": 1763107200000
}
Trường Kiểu Mô tả
id string ID đơn hàng Subiz.
number string Mã đơn hàng dễ đọc.
user object Khách hàng đặt đơn. Xem Định dạng khách hàng và thuộc tính.
items array Sản phẩm trong đơn. Xem Mặt hàng trong đơn.
shipping object Địa chỉ và phí giao hàng. Xem Giao hàng.
currency string Đơn vị tiền tệ của mọi số tiền trong đơn. Rỗng nghĩa là tiền tệ gốc của tài khoản.
status string Trạng thái đơn. Xem Trạng thái. Đơn mới mặc định là open.
payment_status string unpaid hoặc paid. Được tính từ các khoản thanh toán đã ghi nhận trên đơn.
note string Ghi chú hiển thị trên đơn.
private_note string Ghi chú nội bộ cho agent.
related_conversations array ID các hội thoại liên kết với đơn này.
source_id string ID của đơn trong hệ thống nguồn của bạn, nếu có.
fields object Trường bổ sung dạng cặp khóa–giá trị kiểu chuỗi.
is_draft boolean true với đơn nháp.
created, updated integer Dấu thời gian Unix tính bằng mili giây.

Trường rỗng bị lược bỏ, và đối tượng có nhiều trường hơn ví dụ.

Mặt hàng trong đơn

Mỗi phần tử trong items là một dòng của đơn:

{
  "id": "item_example",
  "quantity": 2,
  "product": {
    "id": "product_example",
    "name": "Ceramic mug",
    "sku": "MUG-01",
    "price": 120000
  },
  "discount_type": "percentage",
  "discount_percentage": 1000,
  "total": 216000
}
Trường Kiểu Mô tả
quantity integer Số lượng.
product object Bản sao sản phẩm tại thời điểm đặt đơn, gồm cả price.
name, sku string Tên và SKU của mặt hàng, với mặt hàng không liên kết sản phẩm.
discount_type string amount hoặc percentage.
discount_amount number Chiết khấu cho dòng này, khi discount_type là amount.
discount_percentage integer Chiết khấu cho dòng này, khi discount_type là percentage. Nhân 100: 1000 nghĩa là 10%.
total number Thành tiền của dòng: số lượng × giá, trừ chiết khấu dòng. Do Subiz tính.
note string Ghi chú cho dòng này.

Sản phẩm bên trong mặt hàng là một bản sao. Thay đổi sản phẩm sau đó không làm thay đổi các đơn đã có. Mặt hàng không có product không được tính vào tổng tiền của đơn.

Giao hàng

shipping chứa thông tin giao hàng:

{
  "address": {
    "fullname": "Alex Example",
    "phone": "+84900000000",
    "street": "12 Example Street",
    "ward": "Ben Nghe",
    "district": "District 1",
    "region": "Ho Chi Minh City",
    "country_code": "VN"
  },
  "nominal_fee": 30000,
  "note": "Call before delivery.",
  "weight": 500
}
Trường Kiểu Mô tả
address object Tên, số điện thoại và địa chỉ người nhận. region là tỉnh hoặc thành phố.
nominal_fee number Phí giao hàng tính vào tổng tiền của đơn.
note string Hướng dẫn giao hàng.
weight integer Khối lượng kiện hàng tính bằng gam.
length, width, height integer Kích thước kiện hàng tính bằng centimet.
shipping_code string Mã vận đơn của đơn vị vận chuyển.

Số tiền

Mọi số tiền là số theo currency của đơn. Subiz tính subtotal, total_tax và total từ mặt hàng, chiết khấu, phí giao hàng và khoản điều chỉnh.

Trường Mô tả
subtotal Tổng thành tiền các dòng, sau chiết khấu dòng.
total_tax Tổng thuế.
discount_type, discount_amount, discount_percentage Chiết khấu cấp đơn, áp dụng sau thuế. Phần trăm được nhân 100.
adjustment Khoản cộng thêm vào tổng tiền.
total Số tiền khách hàng phải trả.
payment_made Số tiền đã thanh toán đến hiện tại.

Dùng chiết khấu dòng cho chiết khấu trước thuế, và chiết khấu cấp đơn cho chiết khấu sau thuế.

Thuế suất dùng thang khác: Tax với percentage: 2000 nghĩa là 20%.

Các trường bắt đầu bằng fpv_, như fpv_total, là bản sao số tiền dạng số dấu phẩy cố định do Subiz tính. Hãy đọc các trường số tiền thông thường, và không gửi trường fpv_.

Trạng thái

status mô tả vị trí của đơn trong quy trình bán hàng:

Giá trị Ý nghĩa
open Đơn mới.
unconfirmed Chưa được doanh nghiệp và khách hàng thống nhất.
closed Đơn đã chốt (thành công).
canceled Đơn đã hủy (thất bại). cancellation_note và cancellation_code giải thích lý do.

payment_status và shipping_status được theo dõi riêng. Đơn có thể closed mà vẫn unpaid.

Đọc đơn hàng an toàn

  • Kiểm tra currency trước khi so sánh hoặc cộng số tiền giữa các đơn.
  • Lường trước giá trị mặc định bị lược bỏ. Chuỗi rỗng, 0 và false bị lược khỏi JSON. Thiếu payment_made nghĩa là chưa thanh toán gì.
  • Dùng user.id để liên kết đơn với khách hàng, và related_conversations để tìm hội thoại.
  • Bỏ qua trường và giá trị chưa biết. Bỏ qua các trường và giá trị trạng thái mà tích hợp của bạn không nhận ra.