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.
Khi truyền chiết khấu theo đơn hàng, sau khi đơn hàng được lưu thì chiết khấu đơn hàng sẽ được chia theo tỉ lệ cho các sản phẩm có trong đơn hàng.
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,
"createdById": 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": 2,
"serviceCode": "PHS",
"accountId": 26,
"shopId": 808957,
"customerShipFee": 30000,
"isDeclaredFee": 1,
"declaredValue": 1000000,
"extraServices": {
"isDocument": 1,
"handDelivery": 1
},
"orderPackage": {
"weight": 800,
"length": 50,
"width": 35,
"height": 10,
"merge": 0
}
},
"products": [
{
"id": 1231281071,
"price": 189000,
"discount": 9000,
"imeis": ["IMEI số 1", "IMEI số 2"],
"quantity": 2
},
{
"id": 1231253490,
"price": 109000,
"vat": 8,
"quantity": 1,
"gifts": [
{
"id": 1231279483,
"quantity": 1,
"price": 20000
}
]
}
],
"payment": {
"depositAmount": 50000,
"depositAccountId": 266363,
"transferAmount": 100000,
"transferAccountId": 263475
},
"invoice": {
"tax": {
"type": 2,
"code": "0108824877",
"name": "CÔNG TY CỔ PHẦN NHANH.VN",
"address": "Tầng 2 phòng 206 Tòa nhà GP Invest, Số 170 đường La Thành, Phường Ô Chợ Dừa, Thành phố Hà Nội, Việt Nam",
"citizenIdNumber": null,
"passportNumber": null
},
"contact": {
"name": "Nguyễn Văn Anh",
"mobile": "0987654321",
"email": "email_1@gmail.com",
"email2": "email_2@gmail.com"
}
}
}'Thông tin trong mảng đơn hàng:
info
Thông tin cơ bản của đơ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 dơn hàng. Các trạng thái được phép cập nhật: Mới, Chờ xác nhận, Đang xác nhận, Đã xác nhận (Lấy từ Order Status)
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
object
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
object
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. Bạn cần truyền thêm id kho hàng (info.depotId) khi dùng loại này.
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ừ tính phí vận chuyển
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ừ tính phí vận chuyển
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
deliveryTime
string
Giờ phút giây giao hàng của đơn hàng này, định dạng H:i:s hoặc H:i
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ừ tính phí vận chuyển) )
isPartDelivery
int
1: Đơn hàng có giao hàng một phần (mặc định null)
isDeclaredFee
int
Khai giá (1: Có, 0: Không)
declaredValue
int
Giá trị khai giá
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
extraServices
object
Mảng dịch vụ cộng thêm (chỉ áp dụng với kết nối tài khoản riêng của shop: sendCarrierType = 2) - BEST: + Đổi trả hàng: isReturnGoods = 1 - Viettel: + Loại thư từ: isDocument = 1 + Phát tận tay: handDelivery = 1
orderPackage
object
Kích thước gói hàng weight: Khối lượng gói hàng (gram) length: Chiều dài (cm) width: Chiều rộng (crm) height: Chiều cao (crm) merge: Gộp kiện (Truyền 1 nếu muốn gộp kiệ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
imeis
array
Mảng IMEI sản phẩm
vat
double
% VAT. VD: 5, 8, 10 (chỉ gửi số, không gửi kèm ký tự %). Chú ý: Các giá trị đặc biệt như 0%, Không chịu thuế, Không kê khai nộp thuế xem const tại đây. Mặc định nếu bạn không truyền tham số này, hệ thống sẽ lấy theo thông tin khai báo ở Danh sách sản phẩm
priceVatMode
int
Loại giá bán (mặc định nếu không truyền thì sẽ lấy theo khai báo ở thông tin sản phẩm): 1: Giá bán đã bao gồm VAT 2: Giá bán chưa bao gồm VAT
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"} ]
Ví dụ về loại giá bán:
Giá bán đã bao gồm VAT: priceVatMode = 1, price = 100000, vat = 10% thì Tổng tiền thanh toán sẽ là 100.000
Giá bán chưa bao gồm VAT: priceVatMode = 2, price = 100000, vat = 10% thì Tổng tiền thanh toán sẽ là 110.000
payment
Thông tin thanh toán
depositAmount
int
Số tiền đặt cọc
transferAmount
int
Số tiền chuyển khoản
couponCode
string
Mã giảm giá - Nếu mã couponCode được tạo từ Nhanh thì hệ thống sẽ tự động tăng số lần đã sử dụng hoặc đổi trạng thái khi đơn hàng được lưu thành công. - Các lỗi liên quan tới couponCode tham khảo bên dưới.
usedPoints
int
Số điểm tiêu
discountAmount
int
Giá trị chiết khấu (Khi áp dụng chiết khấu theo cả đơn hàng thì truyền giá trị này, còn khi đã áp dụng chiết khấu theo sản phẩm thì không cần truyền)
discountType
string
Loại chiết khấu cash: Tiền percent: Phần trăm
invoice
Thông tin xuất hóa đơn điện tử
Để sử dụng được tạo hóa đơn điện tử:
Doanh nghiệp cần mua hóa đơn của Nhanh và cài đặt ở Kênh bán > Hóa đơn điện tử.
tax
object
Thông tin xuất hóa đơn - type: 1: Hộ kinh doanh, 2: Công ty, 3: Cá nhân - code: Mã số thuế Hộ kinh doanh / Công ty - name: Tên Hộ kinh doanh / Công ty / Cá nhân - address: Địa chỉ Hộ kinh doanh / Công ty / Cá nhân - citizenIdNumber: Số căn cước công dân (dùng cho loại cá nhân) - passportNumber: Số hộ chiếu (dùng cho loại cá nhân)
contact
object
Thông tin người nhận hóa đơn - name: Tên người nhận hóa đơn - mobile: Số điện thoại người nhận hóa đơn - email: Email người nhận hóa đơn - email2: Email người cùng nhận hóa đơ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
Lỗi thường gặp
Không áp dụng được mã coupon
Tình huống: Bạn gửi sang mã coupon, nhưng không thấy đơn hàng cập nhật giá trị chiết khấu từ coupon, hoặc bản gửi sang cả chiết khấu và coupon, nhưng đơn hàng chỉ nhận chiết khấu, không cộng thêm giá trị từ coupon.
Nguyên nhân: trường coupon chỉ có tác dụng ghi nhận đơn hàng đó được áp dụng coupon nào, Nhanh OpenAPI không dùng mã coupon đó để tính toán là giá trị chiết khấu. Mọi logic về chiết khấu, app của bạn cần tự tính toán, có thể cộng dồn nhiều loại chiết khấu khác, sau đó cho hết vào field
payment.discountAmount.
Last updated