# 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"
}
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apidocs.nhanh.vn/v3/bill/addretail.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.