Các trường giao dịch bơm

Kiểu, quy tắc và ví dụ của từng trường trong một giao dịch bơm gửi lên NexERP.

Bài này giải thích thân request của POST /pump-logs và từng phần tử logs của POST /pump-logs/batch. Trường không có trong bảng bị từ chối với mã 422. Ký tự điều khiển trong các mã cũng bị từ chối.

Giao dịch

Trường	Kiểu	Bắt buộc	Mô tả
`id_log`	chuỗi	có	Mã giao dịch của phần mềm trụ bơm. 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ụ: `"CH01-V03-20261028-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ự. Ví dụ: `"CH01"`
`fuel_code`	chuỗi	có	Mã nhiên liệu, 1 đến 64 ký tự. Phải có trong danh mục doanh nghiệp đã khai. Ví dụ: `"RON95"`
`nozzle_code`	chuỗi	có	Mã vòi bơm, 1 đến 64 ký tự. Ví dụ: `"V03"`
`unit_price`	số nguyên	có	Đơn giá niêm yết, đồng/lít, lớn hơn 0. Ví dụ: `21610`
`liters`	chuỗi thập phân	có	Số lít trụ bơm đo, lớn hơn 0, tối đa 6 chữ số lẻ, dấu chấm thập phân. Ví dụ: `"4.627"`
`amount`	số nguyên	có	Tổng tiền khách trả, đồng, lớn hơn 0 và tối đa 999.999.999.999. Ví dụ: `100000`
`pumped_at`	chuỗi thời điểm ISO 8601	có	Thời điểm bơm xong, phải có múi giờ. Ví dụ: `"2026-10-28T10:45:00+07:00"`

Tổng tiền và số lít

Tổng tiền là gốc. Hóa đơn ghi đúng amount.
Số lượng trên hóa đơn bằng amount / unit_price, 6 chữ số lẻ, làm tròn lên từ 5. liters chỉ lưu lại để đối chiếu.
liters phải gửi dạng chuỗi. Gửi số JSON bị từ chối với mã log.liters_must_be_string.
liters × unit_price lệch amount quá 1 % bị từ chối với mã log.amount_mismatch. Lỗi này thường do gửi đảo trường.

Mã nhiên liệu

Doanh nghiệp khai danh mục nhiên liệu trên NexERP: mã nhiên liệu, tên hàng ghi trên hóa đơn, đơn vị tính và thuế suất. Bạn chỉ gửi mã.

Mã chưa khai bị từ chối với mã log.fuel_code_unknown. Báo doanh nghiệp khai thêm rồi gửi lại.
Thuế suất do doanh nghiệp chọn theo quy định hiện hành. Bạn không gửi thuế suất.

Thời điểm bơm

pumped_at ở tương lai quá 5 phút bị từ chối với mã log.pumped_at_in_future. Kiểm tra đồng hồ máy trụ bơm.
pumped_at cũ hơn số ngày cho phép (mặc định 3 ngày) bị từ chối với mã log.too_old.
Ngày bán trên hóa đơn là ngày của pumped_at theo giờ Việt Nam.

Đồng bộ giờ

Thiết bị trụ bơm không có đồng hồ thì lấy giờ máy chủ NexERP bằng GET /time. Cần khóa API, không cần phạm vi.

GET https://api-demo.nexerp.vn/api/open/v1/time

{
  "server_time": "2026-10-29T14:05:12.345000+07:00",
  "unix_ms": 1793257512345,
  "timezone": "Asia/Ho_Chi_Minh"
}

Trường	Kiểu	Ý nghĩa
`server_time`	chuỗi thời điểm ISO 8601	Giờ máy chủ theo giờ Việt Nam, có múi giờ `+07:00`. Đúng định dạng `pumped_at` nhận
`unix_ms`	số nguyên	Cùng thời điểm, mili-giây kể từ 1970-01-01 UTC
`timezone`	chuỗi	Múi giờ của `server_time`: `Asia/Ho_Chi_Minh`

Gọi GET /time lúc khởi động và định kỳ, ví dụ mỗi giờ. Lưu độ lệch giữa unix_ms và bộ đếm của thiết bị, rồi cộng độ lệch đó khi ghi pumped_at. Không cần gọi trước mỗi giao dịch.

Lưu ý

id_log dùng chung với external_id của POST /invoices. Một mã đã dùng ở đường này thì không dùng lại ở đường kia.
Gửi lại vì mất phản hồi thì gửi đúng nội dung cũ. Xem Chống tạo trùng.