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.

• Xem Postman sample.

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
customer	object	Thông tin khách hàng
products	array	Thông tin sản phẩm của hóa đơn
saleId	int	ID nhân viên bán hàng lấy từ danh sách nhân viên
technicalStaffId	int	ID nhân viên kỹ thuật lấy từ danh sách nhân viên
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

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ỉ
districtLocationId	int	ID quận, huyện lấy từ danh sách địa chỉ
wardLocationId	int	ID phường, xã lấy từ danh sách địa chỉ
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
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 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 (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 (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ử.

  • 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.

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.

Failed response

• Xem các mã lỗi chung tại đây.

• 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

{
    "code": 1,
    "data": {
        "id": "(int) ID hóa đơn",
        "totalAmount": "(double) Tổng tiền hóa đơn"
    }
}