Đơn Hàng

Các API về đơn hàng cho phép bạn tạo, xem, lấy thông tin và in nhãn dán đơn hàng.

Lấy Thông Tin Tối Ưu

API này cho phép bạn lấy thông tin Thông Tin Tối Ưu đang được chọn hiện tại.

Endpoint

get/v1/platform/orders/optimization

Request

Headers

Key	Value
Accept	application/json
Token	Access-Token

Ví Dụ

curl --location --request GET 'https://dev.superai.vn/v1/platform/orders/optimization' \
--header 'Accept: application/json' \
--header 'Token: <Access-Token>'

Response

Tham Số Trả Về

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
optimization.option_id	String	Mã Phương Án Tối Ưu. Ví dụ: 1.
optimization.option_name	String	Tên Phương Án Tối Ưu. Ví dụ: Nhà vận chuyển bất kỳ theo phân tích AI (hiệu quả nhất).
optimization.carriers	Array	Mảng Chứa Mã Định Danh Nhà Vận Chuyển. Ví dụ: ['2', '6'].
carriers.id	Integer	ID của Nhà Vận Chuyển. Ví dụ: 2.
carriers.name	String	Tên Nhà Vận Chuyển. Ví dụ: GHN.
carriers.code	String	Mã Định Danh của Nhà Vận Chuyển. Ví dụ: 2.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "optimization": {
            "option_id": "2",
            "option_name": "Một nhà vận chuyển mặc định",
            "carriers": [
                "4"
            ]
        },
        "carriers": [
            {
                "id": 2,
                "name": "GHN",
                "code": "2"
            },
            {
                "id": 4,
                "name": "Viettel Post",
                "code": "4"
            },
            {
                "id": 6,
                "name": "BEST Express",
                "code": "6"
            },
            {
                "id": 7,
                "name": "Ninja Van",
                "code": "7"
            },
            {
                "id": 10,
                "name": "SPX Express",
                "code": "10"
            }
        ]
    }
}

Cập Nhật Thông Tin Tối Ưu

API này cho phép bạn cập nhật Thông Tin Tối Ưu và sử dụng Thông Tin Tối Ưu mới.

Endpoint

post/v1/platform/orders/optimize

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
option_id	Có	String	Mã Phương Án Tối Ưu. Ví dụ: 1. Các giá trị có thể: - Nhà vận chuyển bất kỳ theo phân tích AI (hiệu quả nhất): 1 - Một nhà vận chuyển mặc định: 2 - Nhiều nhà vận chuyển tùy chọn theo phân tích AI: 3 - Nhà vận chuyển có chi phí giao hàng rẻ nhất: 4 - Nhà vận chuyển có tốc độ giao hàng nhanh nhất: 5
carriers	Tùy	String	Mảng Chứa Mã Định Danh Nhà Vận Chuyển. Ví dụ: ['2', '6'].

LƯU Ý

• Chỉ điền carriers khi option_id thuộc một trong các giá trị: 2 hoặc 3.
• Nếu option_id bằng 2 thì mảng carriers chỉ được phép chứa tối đa 1 giá trị. Ví dụ: ['2'].
• Nếu option_id bằng 3 thì mảng carriers chỉ được phép chứa tối thiểu 2 giá trị. Ví dụ: ['2', '6'].

Ví Dụ

curl --location --request POST 'https://dev.superai.vn/v1/platform/orders/optimize' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "option_id": "3",
    "carriers": ["2", "6"]
}'

Response

Tham Số Trả Về

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
option_id	String	Mã Phương Án Tối Ưu. Ví dụ: 1.
carriers	Array	Mảng Chứa Mã Định Danh Nhà Vận Chuyển. Ví dụ: ['2', '6'].

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "diff": {
            "option_id": "3",
            "carriers": [
                "2",
                "6"
            ]
        }
    }
}

Tính Cước Phí

API này cho phép bạn tính trước cước phí của một đơn hàng.

Endpoint

post/v1/platform/orders/price

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
sender_province	Có	String	Tên Tỉnh/Thành Phố của Người Gửi. Ví dụ: Thành phố Hồ Chí Minh.
sender_district	Có	String	Tên Quận/Huyện của Người Gửi. Ví dụ: Huyện Bình Chánh.
receiver_province	Có	String	Tên Tỉnh/Thành Phố của Người Nhận. Ví dụ: Thành phố Hà Nội.
receiver_district	Có	String	Tên Quận/Huyện của Người Nhận. Ví dụ: Quận Tây Hồ.
weight	Có	Integer	- Khối lượng của Đơn Hàng. Ví dụ: 200. - Đơn vị tính gram.
value	Không	Integer	- Trị giá của Đơn Hàng. Ví dụ: 4200000. - Dùng để tính Phí Bảo Hiểm. - Đơn vị tính đồng.

Ví Dụ

curl --location --request POST 'https://dev.superai.vn/v1/platform/orders/price' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "sender_province": "Thành phố Hồ Chí Minh",
    "sender_district": "Huyện Bình Chánh",
    "receiver_province": "Thành phố Hà Nội",
    "receiver_district": "Quận Tây Hồ",
    "weight": 500,
    "value": 12000000
}
'

Response

Tham Số Trả Về

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
carrier_id	Integer	Mã Định Danh Nhà Vận Chuyển. Ví dụ: 2.
carrier_name	String	Tên Nhà Vận Chuyển. Ví dụ: GHN.
shipment_fee	Integer	Cước Phí Giao Hàng. Ví dụ: 20000.
insurance_fee	Integer	Cước Phí Bảo Hiểm. Ví dụ: 42000.
estimated_pickup	String	Thời gian dự kiến Lấy Hàng. Ví dụ: Khoảng 0.2 - 1.0 ngày.
estimated_delivery	String	Thời gian dự kiến Giao Hàng. Ví dụ: Khoảng 2.1 - 2.6 ngày.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "services": [
            {
                "carrier_id": 2,
                "carrier_name": "GHN",
                "shipment_fee": 24000,
                "insurance_fee": 60000,
                "estimated_pickup": "Khoảng 0.2 - 1.0 ngày",
                "estimated_delivery": "Khoảng 2.1 - 2.6 ngày"
            },
            {
                "carrier_id": 4,
                "carrier_name": "Viettel Post",
                "shipment_fee": 25000,
                "insurance_fee": 60000,
                "estimated_pickup": "Khoảng 0.2 - 1.0 ngày",
                "estimated_delivery": "Khoảng 2.5 - 3.0 ngày"
            },
            {
                "carrier_id": 6,
                "carrier_name": "BEST Express",
                "shipment_fee": 23000,
                "insurance_fee": 60000,
                "estimated_pickup": "Khoảng 0.2 - 1.0 ngày",
                "estimated_delivery": "Khoảng 2.6 - 3.1 ngày"
            },
            {
                "carrier_id": 7,
                "carrier_name": "Ninja Van",
                "shipment_fee": 22000,
                "insurance_fee": 60000,
                "estimated_pickup": "Khoảng 0.2 - 1.0 ngày",
                "estimated_delivery": "Khoảng 2.3 - 2.8 ngày"
            },
            {
                "carrier_id": 10,
                "carrier_name": "SPX Express",
                "shipment_fee": 20000,
                "insurance_fee": 60000,
                "estimated_pickup": "Khoảng 0.2 - 1.0 ngày",
                "estimated_delivery": "Khoảng 2.6 - 3.1 ngày"
            }
        ]
    }
}

Tạo Đơn Hàng

API này cho phép bạn tạo một đơn hàng mới.

Endpoint

post/v1/platform/orders/create

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
name	Có	String	Tên của Người Nhận. Ví dụ: Trần Ngọc Nam.
phone	Có	String	Số Điện Thoại của Người Nhận.
address	Có	String	Địa Chỉ của Người Nhận. Ví dụ: 56 Trương Công Định.
province	Có	String	Tên Tỉnh/Thành Phố của Người Nhận. Ví dụ: Thành phố Hồ Chí Minh.
district	Có	String	Tên Quận/Huyện của Người Nhận. Ví dụ: Quận Tân Bình.
commune	Có	String	Tên Phường/Xã của Người Nhận. Ví dụ: Phường 14.
amount	Có	Integer	Số tiền thu hộ. Ví dụ: 200000. Đơn vị tính đồng.
value	Không	Integer	Trị Giá của đơn hàng. Ví dụ: 4200000. Dùng để tính Phí Bảo Hiểm. Đơn vị tính đồng.
weight	Có	Integer	Khối lượng của đơn hàng. Ví dụ: 200. Đơn vị tính gram.
soc	Không	String	Mã Đơn Riêng của Người Gửi. Ví dụ: KR-180703-034.
note	Không	String	Ghi chú thêm về Đơn Hàng của Người Gửi. Ví dụ: Hàng dễ vỡ, lưu ý dùm shop.
service	Có	String	Mã Gói Dịch Vụ. Ví dụ: 1. Các giá trị có thể: - Gói Tốc Hành: 1
config	Có	String	Người Nhận có được quyền xem/thử sản phẩm. Ví dụ: 1. Các giá trị có thể: - Cho Xem Hàng Nhưng Không Cho Thử Hàng: 1 - Cho Thử Hàng: 2 - Không Cho Xem Hàng: 3
payer	Có	String	Người Trả Phí. Ví dụ: 1. Các giá trị có thể: - Người Gửi: 1 - Người Nhận: 2
product_type	Có	String	Cách truyển sản phẩm. Ví dụ: 1. Các giá trị có thể: - Dạng Chuỗi: 1 - Dạng Mảng: 2
product	Không	String	Bắt buộc khi giá trị của product_type là 1. Ví dụ: Quần áo.
products	Không	Array	Bắt buộc khi giá trị của product_type là 2. Các Tham Số: - sku: Mã Sản Phẩm. Ví dụ: P899234. - name: Tên Sản Phẩm. Ví dụ: Áo khoác P4. - price: Giá Sản Phẩm. Ví dụ: 200000. - weight: Khối Lượng. Ví dụ: 200. - quantity: Số Lượng. Ví dụ: 1.
barter	Không	String	Tùy chọn Đổi/Lấy hàng về. Nếu có yêu cầu này, đơn hàng sẽ được hỗ trợ đổi hàng và trả hàng về. Ví dụ: 1.
partner	Không	String	Mã Bí Mật. Dành cho các Đối Tác Thương Mại Điện Tử lớn với SuperAI.

THÔNG TIN

• Nếu bạn muốn gửi đơn sang 1 Nhà Vận Chuyển bất kỳ mà không muốn đi theo Thông Tin Tối Ưu đã cấu hình trước đó thì bổ sung trường carrier với giá trị Mã Định Danh Nhà Vận Chuyển vào Request Payload.
• Ví dụ nếu muốn gửi đơn sang Giao Hàng Nhanh (GHN) thì điền carrier: "2"

Ví Dụ

curl --location --request POST 'https://dev.superai.vn/v1/platform/orders/create' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "name": "Quynh Anh Tran",
    "phone": "0987654321",
    "address": "Quán Nhậu Anh Em Mình, Đường Số 2, ấp Phú Nhơn",
    "province": "Tỉnh Hậu Giang",
    "district": "Châu Thành A",
    "commune": "Xã Tân Phú Thạnh",
    "amount": 160000,
    "value": 160000,
    "weight": 200,
    "payer": "1",
    "config": "1",
    "soc": "PO854252213",
    "note": "được kiểm tra váy áo không thử,không mở hộp đai latex ,mỹ phẩm,phụ kiện- chỉ được kiểm tra bên ngoài",
    "barter": null,
    "product_type": "2",
    "products": [
        {
            "sku": "Short jean co giãn tốt ống rộng wax ZR01 245 - NHẠT WAX - 28",
            "name": "Short jean co giãn tốt ống rộng wax ZR01 245 - NHẠT WAX - 28",
            "price": 245000,
            "weight": 100,
            "quantity": 1
        },
        {
            "sku": "Quần yếm jeans mã Z 295 - NHẠT - 28",
            "name": "Quần yếm jeans mã Z 295 - NHẠT - 28",
            "price": 295000,
            "weight": 100,
            "quantity": 1
        }
    ]
}'

Response

QUAN TRỌNG

• Các giá trị carrier_code, carrier_sortcode có thể có giá trị null do đơn hàng Gửi Đơn Lỗi/Chưa Kịp Gửi sang Nhà Vận Chuyển.
• Nếu gặp trường hợp trên, vui lòng chờ 3 phút rồi sau đó sử dụng API Lấy Thông Tin Đơn Hàng để cập nhật chủ động Mã Vận Đơn và Mã Phân Loại của Nhà Vận Chuyển.

Các Tham Số

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
carrier_id	String	Mã Nhà Vận Chuyển. Ví dụ: 2.
carrier_name	String	Tên Nhà Vận Chuyển. Ví dụ: GHN.
carrier_code	String	Mã Vận Đơn của Nhà Vận Chuyển. Ví dụ: L9TXFP.
carrier_sortcode	String	Mã Phân Loại của Nhà Vận Chuyển. Ví dụ: F-000-H-00-00.
superai_code	String	Mã Đơn Hàng của SuperAI. Ví dụ: HUGS983262NM.810002159.
superai_shortcode	String	Mã Đơn Ngắn của SuperAI. Ví dụ: 810002159. Dùng Mã Này để hiển thị Mã Vạch, không dùng Mã Đơn Đầy Đủ ở trường `superai_code`.
superai_sortcode	String	Mã Phân Loại của SuperAI. Ví dụ: LUC17-C10.
soc	String	Mã Đơn Hàng của Người Gửi. Ví dụ: PO854252213.
amount	Integer	Số Tiền cần Thu Hộ. Ví dụ: 160000.
collection	Integer	Số Tiền Thu Người Nhận. Ví dụ: 160000.
value	Integer	Trị Giá của Đơn Hàng. Ví dụ: 160000.
weight	Integer	Khối Lượng của Đơn Hàng. Ví dụ: 200.
fee	Integer	Cước Phí Giao Hàng. Ví dụ: 24000.
insurance	Integer	Phí Bảo Hiểm. Ví dụ: 0.
status	String	Mã Trạng Thái của Đơn Hàng. Ví dụ: 2.
status_name	String	Tên Trạng Thái của Đơn Hàng. Ví dụ: Chờ Lấy Hàng.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "carrier_id": "2",
        "carrier_name": "GHN",
        "carrier_code": "L9TXFP",
        "carrier_sortcode": "F-000-H-00-00",
        "superai_code": "HUGS983262NM.810002159",
        "superai_shortcode": "810002159",
        "superai_sortcode": "LUC17-C10",
        "soc": "PO854252213",
        "amount": 160000,
        "collection": 160000,
        "value": 160000,
        "weight": 200,
        "fee": 24000,
        "insurance": 0,
        "status": "2",
        "status_name": "Chờ Lấy Hàng"
    }
}

Lấy Thông Tin Đơn Hàng

API này cho phép bạn lấy thông tin chi tiết của một Đơn Hàng.

Endpoint

get/v1/platform/orders/info

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
code	Có	String	Mã Đơn Hàng. Ví dụ: SGNS983262NT.595050186.
type	Không	String	Loại của Mã Đơn Hàng. Giá trị mặc định: 1. Các giá trị có thể: - Mã Đơn Hàng của SuperAI: 1 - Mã Đơn Hàng của Người Gửi: 2.

Ví Dụ

curl --location --request GET 'https://dev.superai.vn/v1/platform/orders/info' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "type": "1",
    "code": "DLKS983262NM.810002154"
}'

Response

Các Tham Số

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
carrier_id	String	Mã Nhà Vận Chuyển.
carrier_name	String	Tên Nhà Vận Chuyển.
carrier_code	String	Mã Vận Đơn của Nhà Vận Chuyển.
superai_shortcode	String	Mã Ngắn của SuperAI.
superai_code	String	Mã Đơn Hàng của SuperAI.
soc	String	Mã Đơn Hàng của Người Gửi.
status	String	Mã Trạng Thái của Đơn Hàng. Ví dụ: 12.
status_name	String	Tên Trạng Thái của Đơn Hàng. Ví dụ: Đã Giao Hàng Toàn Bộ.
collection	Integer	Số Tiền Thu Người Nhận.
value	Integer	Trị Giá Thực Tế của Đơn Hàng.
weight	Integer	Khối Lượng của Đơn Hàng.
fee	Object	Các loại Cước Phí của Đơn Hàng.
fee.shipment	Integer	Phí Giao Hàng.
fee.insurance	Integer	Phí Bảo Hiểm.
fee.return	Integer	Phí Hoàn Hàng.
fee.barter	Integer	Phí Đổi Trả.
fee.address	Integer	Phí Đổi Địa Chỉ.
payer	String	Người Trả Phí.
payer_name	String	Tên Người Trả Phí.
config	String	Cấu Hình xem/thử hàng.
config_name	String	Tên Cấu Hình xem/thử hàng.
receiver	Object	Thông Tin Người Nhận.
created_at	String	Thời Gian Tạo của Đơn Hàng.
updated_at	String	Thời Gian Cập Nhật của Đơn Hàng.
delivered_at	String	Thời Gian Giao Hàng.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "order": {
            "carrier_id": "4",
            "carrier_name": "Viettel Post",
            "carrier_code": "SPSP1002987406",
            "superai_shortcode": "810002154",
            "superai_code": "DLKS983262NM.810002154",
            "soc": "S120173755O8512",
            "status": "0",
            "status_name": "Huỷ",
            "collection": 250000,
            "value": 3860000,
            "weight": 5900,
            "fee": {
                "shipment": 50000,
                "insurance": 19000,
                "return": 0,
                "barter": 0,
                "address": 10000
            },
            "payer": "1",
            "payer_name": "Người Gửi",
            "config": "3",
            "config_name": "Không Cho Xem Hàng",
            "receiver": {
                "name": "Minh Duy",
                "phone": "098****666",
                "address": "440 Trường Chinh",
                "formatted_address": "440 Trường Chinh, Phường Thống Nhất, Thị Xã Buôn Hồ, Tỉnh Đắk Lắk",
                "commune_name": "Phường Thống Nhất",
                "district_name": "Thị Xã Buôn Hồ",
                "province_name": "Tỉnh Đắk Lắk"
            },
            "created_at": "2024-06-06T23:51:08+07:00",
            "updated_at": "2024-06-09T00:30:40+07:00",
            "delivered_at": null
        }
    }
}

Tạo Token In Nhãn Giao Hàng

API này cho phép bạn lấy Token dành cho việc in Nhãn Giao Hàng.

Endpoint

post/v1/platform/orders/token

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
code	Có	Array	Mảng chứa danh sách Mã Đơn Hàng của SuperAI.

Ví dụ

curl --location --request POST 'https://dev.superai.vn/v1/platform/orders/token' \
--header 'Accept: application/ecmascript' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "code": [
        "DLKS983262NM.810002155",
        "DLKS983262NM.810002154"
    ]
}'

Response

Các Tham Số

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
token	String	Token dành cho mục đích In Nhãn Đơn Hàng. Ví dụ: 6cf2ce20-80e9-11eb-8974-cd483a610abd.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "token": "92cb9830-25bc-11ef-bc20-ed448e0c4f9f"
    }
}

In Đơn Hàng

API này cho phép bạn in Nhãn Giao Hàng của một hoặc nhiều Đơn Hàng trực tiếp trên trình duyệt.

Endpoint

get/v1/platform/orders/label

Request

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
token	Có	String	Token dành cho mục đích In Đơn Hàng. Ví dụ: 6cf2ce20-80e9-11eb-8974-cd483a610abd.
size	Có	String	Kích thước Nhãn In Đơn Hàng. Các giá trị có thể: - Khổ giấy S8: S8 - Khổ giấy S9: S9 - Khổ giấy S10: S10 - Khổ giấy S11: S11 - Khổ giấy S12: S12 - Khổ giấy S13: S13 - Khổ giấy S14: S14

Ví Dụ

curl --location --request GET 'https://dev.superai.vn/v1/platform/orders/label?token=92cb9830-25bc-11ef-bc20-ed448e0c4f9f&size=S9'

Response

Ví Dụ

Hủy Đơn Hàng

API này cho phép bạn hủy một Đơn Hàng.

Endpoint

post/v1/platform/orders/cancel

Request

Headers

Key	Value
Accept	application/json
Content-Type	application/json
Token	Access-Token

Các Tham Số

Thuộc_Tính	Bắt_Buộc	Kiểu_DL	Mô_Tả_Chi_Tiết
code	Có	String	Mã Đơn Hàng của SuperAI. Ví dụ: SGNS983262NT.595050186.

Ví Dụ

curl --location --request POST 'https://dev.superai.vn/v1/platform/orders/cancel' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Token: <Access-Token>' \
--data '{
    "code": "TGGS964885NM.713594008"
}'

Response

Các Tham Số

Thuộc_Tính	Kiểu_DL	Mô_Tả_Chi_Tiết
code	String	Mã Đơn Hàng của SuperAI.
soc	String	Mã Đơn Hàng của Người Gửi.
status	String	Mã Trạng Thái của Đơn Hàng.
status_name	String	Tên Trạng Thái của Đơn Hàng.

Ví Dụ

{
    "error": false,
    "message": "",
    "data": {
        "order": {
            "code": "HDGS983262LM.810002124",
            "soc": null,
            "status": "0",
            "status_name": "Huỷ"
        }
    }
}