# 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](https://nhanh.vn/setting/order/index#connect-carrier) 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](https://apidocs.nhanh.vn/v3/shipping/fee), 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-nhanh-account): 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-shop-account): 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](https://apidocs.nhanh.vn/v3/webhooks/order).
## Request
* Xem [common request params](https://apidocs.nhanh.vn/v3/readme#request-params).
* Xem [Postman sample](https://www.postman.com/nhanh-vn/pos-open-nhanh-vn/request/81g47kb/order-add).
```curl
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
}
},
"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:
| Key | Type | Description |
| --------------- | ------ | ------------------------------------------------ |
| info | object | [Thông tin cơ bản của đơn hàng](#info) |
| channel | object | [Các dữ liệu liên quan kênh bán hàng](#channel) |
| shippingAddress | object | [Địa chỉ nhận hàng của khách](#shipping-address) |
| carrier | object | [Thông tin dịch vụ vận chuyển](#carrier) |
| products | array | [Mảng sản phẩm trong đơn hàng](#products) |
| payment | object | [Thông tin thanh toán](#payment) |
### 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](https://apidocs.nhanh.vn/v3/business/depot) |
| type | int | [Loại đơn hàng](https://apidocs.nhanh.vn/v3/modelconstant#order-type), 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](https://apidocs.nhanh.vn/v3/business/user) |
| createdById | int | ID người tạo đơn hàng lấy từ [danh sách nhân viên](https://apidocs.nhanh.vn/v3/business/user) |
| 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](https://apidocs.nhanh.vn/v3/order/tags) |
### 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ỉ](https://apidocs.nhanh.vn/v3/shipping/location) |
| districtId | int | ID Quận/huyện lấy từ [danh sách địa chỉ](https://apidocs.nhanh.vn/v3/shipping/location) (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ỉ](https://apidocs.nhanh.vn/v3/shipping/location) |
| 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-nhanh-account) |
| 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-shop-account) |
| 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-shop-account). |
| 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](https://apidocs.nhanh.vn/v3/shipping/fee#carrier-shop-account) |
| 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ừ [tính phí vận chuyển](https://apidocs.nhanh.vn/v3/shipping/fee)) ) |
| isPartDelivery | int | 1: Đơn hàng có giao hàng một phần (mặc định null) |
| isDeclaredValue | 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
|
### 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 |
| imei | string | Số IMEI sản phẩm |
| vat | double | VAT sản phẩm (mặc định nếu không truyền thì sẽ lấy theo % VAT khai báo ở thông tin 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](https://apidocs.nhanh.vn/v3/accounting/account) |
| 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](https://apidocs.nhanh.vn/v3/accounting/account) |
| couponCode | string | Mã giảm giá |
| 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](https://apidocs.nhanh.vn/v3/readme#response).
### Failed response
* Xem các mã lỗi chung [tại đây](https://apidocs.nhanh.vn/v3/readme#failed-response).
### Successful response
```json
{
"code": 1,
"data": {
"id": "(int) ID đơn hàng",
"trackingUrl": "(string) Lịch trình đơn hàng"
}
}
```