Thêm đơn hàng
API này dùng để tạo đơn hàng mới.
Nếu đơn có gắn kho hàng (depotId) sẽ áp dụng các logic tính số Tạm giữ và Đang chuyển như đơn tạo từ trang quản trị của Nhanh.vn. Ví dụ một sản phẩm trên hệ thống đang tồn 10, tạm giữ 1, sau khi API có bắn về thêm một đơn hàng trạng thái Mới, số lượng = 1, có gắn depotId, thì hệ thống sẽ tự động tính toán lại số Tạm giữ = 2.
Chú ý: Cài đặt vận chuyển trên Nhanh.vn hỗ trợ 2 hình thức kết nối với các hãng vận chuyển, bạn cần hiểu rõ doanh nghiệp đang dùng hình thức kết nối nào để gọi API tính phí vận chuyển, và lấy các thông tin cần thiết dùng cho API tạo đơn hàng.
Kết nối có sẵn của Nhanh.vn: Mọi kế nối đi qua tài khoảng bảng giá chung của Nhanh.
Kết nối tài khoản riêng của shop: Doanh nghiệp dùng tài khoản vận chuyển đã đăng ký với các hãng vận chuyển.
Mỗi khi trạng thái đơn hàng có sự thay đổi, app của bạn sẽ nhận được 1 webhooks cập nhật trạng thái đơn hàng từ Nhanh.vn.
Request
Xem Postman sample.
curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/order/add?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
"info": {
"type": 1,
"depotId": 31010,
"saleId": 2054197,
"description": "Giao hàng trong giờ hành chính",
"tagIds": [266, 265]
},
"channel": {
"appOrderId": "7JnexpUBr12082025_1",
"sourceName": "NGUỒN NEW 1"
},
"shippingAddress": {
"name": "Nguyễn Văn Cường",
"mobile": "0928937476",
"cityId": 254,
"districtId": 321,
"wardId": 1116,
"address": "170 La Thành",
"locationVersion": "v1"
},
"carrier": {
"sendCarrierType": 2,
"id": 5,
"serviceCode": "2",
"accountId": 26,
"shopId": 808957,
"customerShipFee": 30000
},
"products": [
{
"id": 1231264453,
"price": 189000,
"discount": 9000,
"quantity": 1
},
{
"id": 1231253490,
"price": 109000,
"vat": 8,
"quantity": 1,
"gifts": [
{
"id": 1231279483,
"quantity": 1,
"price": 20000
}
]
}
],
"payment": {
"depositAmount": 50000,
"depositAccountId": 266363,
"transferAmount": 100000,
"transferAccountId": 263475
}
}'Thông tin trong mảng đơn hàng:
info
Thông tin cơ bản của đơn hàng
depotId
int
ID kho hàng
type
int
Loại đơn hàng (mặc định loại giao hàng)
saleId
int
ID nhân viên bán hàng
description
string
Ghi chú đơn hàng
privateDescription
string
Ghi chú chăm sóc khách hàng
status
int
Trạng thái đơn hàng
tagIds
array
Mảng ID nhãn đơn hàng
channel
Các dữ liệu liên quan kênh bán hàng
appOrderId
string
ID đơn hàng trên app của bạn. NhanhAPI sẽ chặn trùng theo appId + appOrderId.
sourceName
string
Tên nguồn đơn hàng
affiliate
array
Gắn thông tin liên kết code: Mã giới thiệu value: Tiền chiết khấu bonus: Tiền hoa hồng
marketing
array
Gắn link đo đếm marketing utmCampaign: utm_campaign utmSource: utm_source utmMedium: utm_medium
shipping address
Địa chỉ nhận hàng của khách
name
string
Họ và tên
mobile
string
Số điện thoại
string
address
string
Địa chỉ
locationVersion
string
v1: Địa chỉ 3 cấp (Tỉnh / Thành phố, Quận / Huyện, Phường / Xã) v2: Địa chỉ 2 cấp (Tỉnh / Thành phố, Phường / Xã)
carrier
Thông tin dịch vụ vận chuyển. Chú ý trên Nhanh có 2 hình thức kết nối vận chuyển:
Dùng kết nối có sẵn của Nhanh.vn: Bạn cần truyền sendCarrierType = 1 và id, serviceId.
Dùng kết nối tài khoản riêng của Shop: Bạn cần truyền sendCarrierType = 2 và serviceCode, accountId, shopId (nếu có).
id
int
ID hãng vận chuyển
sendCarrierType
int
Biến đánh dấu gửi đơn dùng bảng giá vận chuyển 1: Dùng kết nối có sẵn của Nhanh.vn 2: Dùng kết nối tài khoản riêng của shop
serviceCode
string
Mã dịch vụ hãng vận chuyển, required khi sendCarrierType = 2. Lấy từ /api/shipping/fee
shopId
int
ID cửa hàng trên hệ thống hãng vận chuyển, khi sendCarrierType = 2, tùy hãng vận chuyển sẽ có thêm thông tin shopId. Lấy từ /api/shipping/fee
allowTest
int
Cho khách xem hàng: 1: Cho xem hàng, không cho thử 2: Cho phép thử 3: Không cho xem hàng 4: Cho xem, không lấy thu ship
deliveryDate
string
Ngày giao hàng của đơn hàng này, định dạng yyyy-mm-dd
customerShipFee
int
Phí ship báo khách (Bạn có thể điền 0 nếu báo với khách hàng là miễn phí vận chuyển, hoặc điền các giá trị cố định như 20K, 30K, hoặc lấy theo tổng Phí vận chuyển shipFee + phí thu tiền hộ codFee + phí bảo hiểm declaredFee lấy từ /api/shipping/fee) )
isPartDelivery
int
1: Đơn hàng có giao hàng một phần (mặc định null)
autoSend
int
Biến đánh dấu gửi luôn đơn hàng sang hãng vận chuyển (Dùng trong tình huống bạn có hệ thống xác nhận đơn hàng từ trước, chỉ dùng Nhanh để hỗ trợ vận chuyển). Set value = 1: Gửi luôn đơn hàng sang hãng vận chuyển. Nếu gửi thành công hệ thống sẽ trả về mã vận đơn carrierCode. Chú ý khi có tham số này, hệ thống sẽ phải kết nối sang hãng vận chuyển, nên thời gian phản hồi có thể bị chậm hơn bình thường tùy thuộc vào phản hồi của các hãng vận chuyển
products
Mảng sản phẩm trong đơn hàng
id
int
ID sản phẩm trên Nhanh.vn
price
double
Giá bán
quantity
double
Số lượng
imei
string
Số IMEI sản phẩm
vat
double
VAT sản phẩm
discount
double
Chiết khấu theo tổng số lượng sản phẩm
description
string
Mô tả riêng của từng sản phẩm trong đơn hàng
gifts
array
Quà tặng của sản phẩm trong đơn hàng [ {"id": "id sản phẩm 1 trên Nhanh", "quantity": "Số lượng", "price": "Giá sản phẩm quà tặng"}, {"id": "id sản phẩm 2 trên Nhanh", "quantity": "Số lượng", "price": "Giá sản phẩm quà tặng"} ]
payment
Thông tin thanh toán
depositAmount
int
Số tiền đặt cọc
depositAccountId
int
Tài khoản nhận tiền đặt cọc
transferAmount
int
Số tiền chuyển khoản
transferAccountId
int
Tài khoản nhận tiền chuyển khoản
couponCode
string
Mã giảm giá
usedPoints
int
Số điểm tiêu
method
string
COD: Thanh toán tại nhà Store: Thanh toán tại cửa hàng Gateway: Thanh toán qua cổng thanh toán Online: Thanh toán Online
code
string
Mã giao dịch thanh toán
gateway
string
Tên cổng thanh toán
Response
Xem cấu trúc chung tại đây.
Failed response
Xem các mã lỗi chung tại đây.
Successful response
{
"code": 1,
"errorCode": null,
"messages": [],
"data": {
"id": "(int) ID đơn hàng",
"businessId": "(int) ID doanh nghiệp",
"shippingAddress": {
"name": "(string) Họ và tên",
"mobile": "(string) Số điện thoại"
},
"totalAmount": "(int) Tổng tiền đơn hàng"
}
}Last updated