Các trường hóa đơn

Kiểu, quy tắc và ví dụ của từng trường trong thân request tạo hóa đơn, dòng hàng, người mua và trụ bơm.

Bài này giải thích thân request của POST /invoices và POST /invoices/{id}/replace. Trường không có trong các bảng dưới bị từ chối với mã 422.

Hóa đơn

Trường	Kiểu	Bắt buộc	Mô tả
`external_id`	chuỗi	có	Mã giao dịch của bạn. 1 đến 100 ký tự, chỉ gồm `A-Z a-z 0-9 . _ : -`. Duy nhất theo doanh nghiệp và ứng dụng của bạn. Ví dụ: `"CN5-P03-V2-20261022-000123"`
`store_code`	chuỗi	khi có nhiều cửa hàng	Mã cửa hàng NexERP đã gán, tối đa 64 ký tự. Doanh nghiệp chỉ có một cửa hàng thì được bỏ trống. Ví dụ: `"CN5"`
`issued_at`	chuỗi thời điểm ISO 8601	có	Thời điểm bán, phải có múi giờ. Ví dụ: `"2026-10-22T07:41:05+07:00"`
`payment_method`	chuỗi	có	Hình thức thanh toán: `TM` tiền mặt, `CK` chuyển khoản, `TM/CK` tiền mặt hoặc chuyển khoản. Giá trị khác bị từ chối. Ví dụ: `"TM"`
`buyer`	đối tượng	không	Người mua, xem bảng Người mua bên dưới
`lines`	mảng đối tượng	có	Các dòng hàng, từ 1 đến 30 dòng
`fuel`	đối tượng	không	Thông tin trụ bơm, xem bảng Trụ bơm bên dưới
`note`	chuỗi	không	Ghi chú, tối đa 500 ký tự. Ví dụ: `"Khách quen"`
`reason`	chuỗi	chỉ khi thay thế	Lý do lập hóa đơn thay thế, tối đa 500 ký tự. Chỉ dùng ở `POST /invoices/{id}/replace`. Ví dụ: `"Nhập sai số lượng"`

Trường	Kiểu	Bắt buộc	Mô tả
`name`	chuỗi	có	Tên hàng, tối đa 500 ký tự. Ví dụ: `"Xăng E10 Ron 95 Mức 3"`
`item_code`	chuỗi	không	Mã hàng của bạn, tối đa 64 ký tự. Chỉ lưu lại, NexERP không tra sản phẩm theo mã này. Ví dụ: `"E10RON95M3"`
`unit`	chuỗi	không	Đơn vị tính, tối đa 20 ký tự. Ví dụ: `"Lít"`
`unit_price`	số nguyên	có	Đơn giá niêm yết đúng như khách thấy, đồng, lớn hơn 0. Ví dụ: `26720`
`quantity`	chuỗi thập phân	tùy thuế suất	Số lượng, tối đa 6 chữ số lẻ, dấu chấm thập phân. Ví dụ: `"3.742515"`
`amount`	số nguyên	có	Thành tiền khách trả, đồng, lớn hơn 0 và tối đa 999.999.999.999. Ví dụ: `100000`
`tax_rate`	chuỗi	có	Thuế suất: `"10"`, `"8"`, `"5"`, `"0"`, `"KCT"` (không chịu thuế), `"KKKNT"` (không kê khai, tính nộp thuế). Ví dụ: `"KKKNT"`

Khi nào bắt buộc quantity và cách làm tròn xem ở bài Thành tiền và số lượng.

Trường	Kiểu	Mô tả	Giới hạn
`name`	chuỗi	Tên người mua hoặc tên doanh nghiệp	255 ký tự
`tax_code`	chuỗi	Mã số thuế: 10, 12 hoặc 13 chữ số	20 ký tự
`address`	chuỗi	Địa chỉ người mua	500 ký tự
`citizen_id`	chuỗi	Số căn cước của cá nhân đứng tên hóa đơn	20 ký tự
`phone`	chuỗi	Số điện thoại, dùng để gửi hóa đơn cho khách	20 ký tự
`email`	chuỗi	Email nhận hóa đơn	255 ký tự

Mọi trường của buyer đều không bắt buộc. Cách NexERP chọn người mua ghi trên hóa đơn xem ở bài Người mua.

fuel là đối tượng tự do. NexERP lưu nguyên để đối soát, chưa đưa lên hóa đơn điện tử. Nên dùng các khóa sau:

Khóa	Kiểu	Mô tả
`pump_no`	chuỗi	Số trụ bơm. Ví dụ: `"03"`
`nozzle_no`	chuỗi	Số vòi bơm. Ví dụ: `"2"`
`meter_start`	chuỗi thập phân	Chỉ số công tơ lúc bắt đầu bơm. Ví dụ: `"1234567.890"`
`meter_end`	chuỗi thập phân	Chỉ số công tơ lúc bơm xong. Ví dụ: `"1234571.632"`

unit_price và amount là số nguyên JSON. Gửi dạng chuỗi ("26720") hoặc số thực (26720.0) đều bị từ chối.
quantity luôn là chuỗi. Số JSON hay bị đọc thành số thực nhị phân và sai ở chữ số cuối.
Lỗi dữ liệu trả 422 request.invalid, kèm error.details.errors chỉ ra trường sai.