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 common request params.

• 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
  }
}'

• Thông tin trong mảng đơn hàng:

Key	Type	Description
info	object	Thông tin cơ bản của đơn hàng
channel	object	Các dữ liệu liên quan kênh bán hàng
shippingAddress	object	Địa chỉ nhận hàng của khách
carrier	object	Thông tin dịch vụ vận chuyển
products	array	Mảng sản phẩm trong đơn hàng
payment	object	Thông tin thanh toán

info

• Thông tin cơ bản của đơn hàng

Key	Type	Description
depotId	int	ID kho hàng lấy từ danh sách kho hàng
type	int	Loại đơn hàng, mặc định: Giao hàng tận nhà
saleId	int	ID nhân viên bán hàng lấy từ danh sách nhân viên
createdById	int	ID người tạo đơn hàng lấy từ danh sách nhân viên
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)
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

Key	Type	Description
appOrderId	string $^{{\color{red}*}}$	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

Key	Type	Description
name	string $^{{\color{red}*}}$	Họ và tên
mobile	string $^{{\color{red}*}}$	Số điện thoại
email	string	Email
address	string	Địa chỉ
cityId	int	ID Tỉnh/thành phố lấy từ danh sách địa chỉ
districtId	int	ID Quận/huyện lấy từ danh sách địa chỉ (bắt buộc khi là địa chỉ 3 cấp)
wardId	int	ID Phường/xã lấy từ danh sách đị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ó).

Key	Type	Description
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
serviceId	int	ID dịch vụ vận chuyển required khi sendCarrierType = 1. Lấy từ tính phí vận chuyển
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
accountId	int	ID tài khoản kết nối, 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

Key	Type	Description
id	int $^{{\color{red}*}}$	ID sản phẩm trên Nhanh.vn
price	double $^{{\color{red}*}}$	Giá bán
quantity	double $^{{\color{red}*}}$	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

Key	Type	Description
depositAmount	int	Số tiền đặt cọc
depositAccountId	int	Tài khoản nhận tiền đặt cọc lấy từ danh sách tài khoản kế toán
transferAmount	int	Số tiền chuyển khoản
transferAccountId	int	Tài khoản nhận tiền chuyển khoản lấy từ danh sách tài khoản kế toá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

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,
      "data": {
        "id": "(int) ID đơn hàng",
        "trackingUrl": "(string) Lịch trình đơn hàng"
      }
  }

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.