# 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](https://apidocs.nhanh.vn/v3/readme#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": 0,
            "quantity": 1,
            "price": 500000,
            "discount":{
                "type": "percent",
                "value": 10
            },
            "description": "",
            "extendedWarrantyId": 0,
            "extendedWarrantyMonths": "",
            "extendedWarrantyMoney": 0,
            "imei": "",
            "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](https://apidocs.nhanh.vn/v3/business/depot)           |
| 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](https://apidocs.nhanh.vn/v3/business/user) |
| technicalStaffId | int                        | ID nhân viên kỹ thuật lấy từ [danh sách nhân viên](https://apidocs.nhanh.vn/v3/business/user) |
| 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ỉ](https://apidocs.nhanh.vn/v3/shipping/location)   |
| districtLocationId | int    | ID quận, huyện lấy từ [danh sách địa chỉ](https://apidocs.nhanh.vn/v3/shipping/location) |
| wardLocationId     | int    | ID phường, xã lấy từ [danh sách địa chỉ](https://apidocs.nhanh.vn/v3/shipping/location)  |
| facebookLink       | string | Link Facebook                                                                            |
| birthday           | string | Ngày sinh (Y-m-d)                                                                        |
| gender             | int    | <p>Giới tính<br>1 = Nam<br>2 = Nữ<br>3 = Không xác định</p>                              |
| 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                                                                                                 |
| price                  | double                        | Giá bán sản phẩm                                                                                                  |
| discount               | object                        | <p>Chiết khấu sản phẩm<br>- type: Loại chiết khấu (percent: %, cash: Tiền mặt)<br>- value: Giá trị chiết khấu</p> |
| vat                    | double                        | VAT sản phẩm (tính theo %)                                                                                        |
| imei                   | string                        | 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](https://apidocs.nhanh.vn/v3/product/unit) (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](https://apidocs.nhanh.vn/v3/product/batch) (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 | <p>Thanh toán bằng hình thức tiền mặt<br>- accountId: Tài khoản tiền mặt lấy từ <a href="../accounting/account">danh sách tài khoản kế toán</a> (nếu có dùng kế toán)<br>- value: Giá trị tiền mặt</p>                         |
| transfer       | object | <p>Thanh toán bằng hình thức chuyển khoản<br>- accountId: Tài khoản chuyển khoản lấy từ <a href="../accounting/account">danh sách tài khoản kế toán</a> (nếu có dùng kế toán)<br>- value: Giá trị chuyển khoản</p>             |
| credit         | object | <p>Thanh toán bằng hình thức quẹt thẻ<br>- accountId: Tài khoản quẹt thẻ lấy từ <a href="../accounting/account">danh sách tài khoản kế toán</a> (nếu có dùng kế toán)<br>- value: Giá trị quẹt thẻ<br>- code: Mã giao dịch</p> |
| installment    | object | <p>Thanh toán bằng hình thức trả góp<br>- id: ID dịch vụ trả góp<br>- value: Giá trị trả góp<br>- code: Mã hợp đồng trả góp</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](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).
* 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"
    }
}
```