> For the complete documentation index, see [llms.txt](https://apidocs.nhanh.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.nhanh.vn/v3/bill/addretail.md).
# Thêm hóa đơn bán lẻ
* API dùng để tạo hóa đơn bán lẻ, tối đa 100 sản phẩm / requests.
* Chỉ hỗ trợ chiết khấu theo sản phẩm, không hỗ trợ chiết khấu tổng đơn và không tính toán chiết khấu tự động.
* Không hỗ trợ điền mã coupon để giảm giá sản sản phẩm.
* Không hỗ trợ sản phẩm quà tặng, nếu hóa đơn có quà tặng coi như sản phẩm riêng để giá 0 đồng.
* Không check theo cài đặt bắt buộc nhập thông tin khách hàng | nhân viên bán hàng.
## Request
* Xem [common request params](/v3/readme.md#request-params).
* Xem [Postman sample](https://www.postman.com/nhanh-vn/pos-open-nhanh-vn/request/81g47kb/bill-add).
```curl
curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/bill/addretail?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
"depotId": 31010,
"customer" : {
"id": "",
"name": "Test khách API V3",
"mobile": "0987654321",
"email": "",
"address": "136/6 Kiêu Kỵ, Gia Lâm, Hà Nội",
"facebookLink": "",
"cityLocationId": 254,
"districtLocationId": 331,
"wardLocationId": 1246,
"birthday": "",
"gender": 0,
"groupId": 0,
"businessName": "",
"businessAddress": "",
"description": "",
"taxCode": "",
"tagIds": []
},
"saleId": 0,
"technicalStaffId": 0,
"description": "test combo API V3",
"tagIds": [],
"products": [
{
"id": 1231279582,
"vat": -1,
"quantity": 1,
"priceVatMode": 1,
"price": 500000,
"discount":{
"type": "percent",
"value": 10
},
"description": "",
"extendedWarrantyId": 0,
"extendedWarrantyMonths": "",
"extendedWarrantyMoney": 0,
"imeis": ["IMEI 1', "IMEI 2"],
"unitId": "",
"batchId": ""
}
],
"payment": {
"customerAmount": 450000,
"debtDueDate": "",
"cash": {
"value": 0,
"accountId": 0
},
"credit": {
"value": 0,
"accountId": 0,
"code": ""
},
"transfer": {
"value": 440000,
"accountId": 263475
},
"installment": {
"id": 0,
"code": "",
"value": 0
},
"usedPoints": 0
},
"invoice": {
"createDraft": 1
}
}'
```
* Thông tin trong hóa đơn:
| Key | Type | Description |
| ---------------- | -------------------------- | ------------------------------------------------------------------------ |
| depotId | int $$^{{\color{red}\*}}$$ | ID kho hàng lấy từ [danh sách kho hàng](/v3/business/depot.md) |
| customer | object | [Thông tin khách hàng](#customer) |
| products | array | [Thông tin sản phẩm của hóa đơn](#products) |
| saleId | int | ID nhân viên bán hàng lấy từ [danh sách nhân viên](/v3/business/user.md) |
| technicalStaffId | int | ID nhân viên kỹ thuật lấy từ [danh sách nhân viên](/v3/business/user.md) |
| description | string | Ghi chú hóa đơn |
| tagIds | array | List ID nhãn muốn gắn cho hóa đơn |
| payment | object | [Thông tin thanh toán](#payment) |
### customer
* Thông tin khách hàng
| Key | Type | Description |
| ------------------ | ------ | -------------------------------------------------------------------- |
| id | int | ID khách hàng |
| name | string | Tên khách hàng |
| mobile | string | Số điện thoại khách hàng |
| email | string | Email khách hàng |
| address | string | Địa chỉ khách hàng |
| cityLocationId | int | ID thành phố lấy từ [danh sách địa chỉ](/v3/shipping/location.md) |
| districtLocationId | int | ID quận, huyện lấy từ [danh sách địa chỉ](/v3/shipping/location.md) |
| wardLocationId | int | ID phường, xã lấy từ [danh sách địa chỉ](/v3/shipping/location.md) |
| facebookLink | string | Link Facebook |
| birthday | string | Ngày sinh (Y-m-d) |
| gender | int | Giới tính
1 = Nam
2 = Nữ
3 = Không xác định
|
| groupId | int | Nhóm khách hàng |
| businessName | string | Tên công ty khách hàng (Nếu khách là người đại diện cho công ty) |
| businessAddress | string | Địa chỉ công ty khách hàng (Nếu khách là người đại diện cho công ty) |
| taxCode | string | Mã số thuế |
| description | string | Ghi chú khách hàng |
| tagIds | array | Mảng ID nhãn gắn cho khách hàng |
### products
* Thông tin sản phẩm
| Key | Type | Description |
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | int $$^{{\color{red}\*}}$$ | ID sản phẩm |
| quantity | double $$^{{\color{red}\*}}$$ | Số lượng sản phẩm |
| priceVatMode | int | 1: Giá đã bao gồm VAT, 2: Giá chưa bao gồm VAT (mặc định) (Xem bảng mô tả [priceVatMode](/v3/modelconstant.md#price-vat-mode)) |
| price | double | Giá bán sản phẩm |
| discount | object | Chiết khấu sản phẩm
- type: Loại chiết khấu (percent: %, cash: Tiền mặt)
- value: Giá trị chiết khấu
|
| 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](/v3/modelconstant.md#product-vat). 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 |
| imeis | array | Mảng IMEI sản phẩm (bắt buộc nhập nếu sản phẩm loại IMEI) |
| unitId | int | [ID đơn vị tính](/v3/product/unit.md) (bắt buộc nếu sản phẩm loại nhiều đơn vị tính) |
| batchId | int | [ID lô sản phẩm](/v3/product/batch.md) (bắt buộc nếu sản phẩm bán theo lô) |
| extendedWarrantyId | int | ID gói bảo hành mở rộng |
| extendedWarrantyMonths | int | Số tháng bảo hành của gói bảo hành mở rộng |
| extendedWarrantyMoney | double | Số tiền bảo hành mở rộng |
| description | string | Ghi chú sản phẩm |
### payment
* Thông tin thanh toán
| Key | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| usedPoints | int | Số điểm sử dụng cho hóa đơn |
| customerAmount | double | Tiền khách đưa (Áp dụng trường hợp khách dùng tiền mặt và không sử dụng kế toán trên Nhanh) |
| cash | object | Thanh toán bằng hình thức tiền mặt
- accountId: Tài khoản tiền mặt lấy từ danh sách tài khoản kế toán (nếu có dùng kế toán)
- value: Giá trị tiền mặt
|
| transfer | object | Thanh toán bằng hình thức chuyển khoản
- accountId: Tài khoản chuyển khoản lấy từ danh sách tài khoản kế toán (nếu có dùng kế toán)
- value: Giá trị chuyển khoản
|
| credit | object | Thanh toán bằng hình thức quẹt thẻ
- accountId: Tài khoản quẹt thẻ lấy từ danh sách tài khoản kế toán (nếu có dùng kế toán)
- value: Giá trị quẹt thẻ
- code: Mã giao dịch
|
| installment | object | Thanh toán bằng hình thức trả góp
- id: ID dịch vụ trả góp
- value: Giá trị trả góp
- code: Mã hợp đồng trả góp
|
| debtDueDate | string | Ngày hẹn thanh toán công nợ (Y-m-d) |
### invoice
* Hóa đơn điện tử: Chỉ truyền một trong hai tham số.
* Để 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ử](https://nhanh.vn/invoice/setting/index).
* User cấp quyền cho app phải có quyền tạo hóa đơn điện tử nháp hoặc phát hành hóa đơn điện tử, thì mới có thể thêm field **invoice** nếu không sẽ bị báo lỗi. Xem thêm mã lỗi ở [bên dưới](#failed-response).
| Key | Type | Description |
| ----------- | ---- | ---------------------------- |
| createDraft | int | 1: Tạo hóa đơn điện tử Nháp |
| publish | int | 1: Phát hành hóa đơn điện tử |
## Response
* Xem cấu trúc chung [tại đây](/v3/readme.md#response).
### Failed response
* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).
* Danh sách mã lỗi:
| Value | Description |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| ERR\_INVOICE\_NO\_SETTING | Chưa cấu hình pháp nhân xuất hóa đơn điện tử |
| ERR\_INVOICE\_PRODUCT\_NO\_DECLARED\_VAT | Khi bật cài đặt "Chặn tạo hóa đơn điện tử nếu sản phẩm chưa điền VAT" |
| ERR\_INVOICE\_PRODUCT\_NO\_MATCH | Khi bật cài đặt "Chặn tạo hóa đơn điện tử có sản phẩm chưa khai báo tên sản phẩm xuất hóa đơn" |
| ERR\_INVOICE\_BLOCK\_TAG | Khi bật cài đặt "Không tạo hóa đơn điện tử khi hóa đơn (Bán lẻ, bán sỉ) có chứa nhãn" |
| ERR\_INVOICE\_BLOCK\_PRODUCT | Khi bật cài đặt "Không tạo hóa đơn điện tử khi hóa đơn (Đơn hàng, bán lẻ, bán sỉ) có chứa sản phẩm" |
### Successful response
```json
{
"code": 1,
"data": {
"id": "(int) ID hóa đơn",
"totalAmount": "(double) Tổng tiền hóa đơn"
}
}
```