Gửi giao dịch bơm

Phần mềm trụ bơm gửi từng giao dịch hoặc cả lô; cửa hàng xuất hóa đơn trên NexERP.

Phần mềm trụ bơm chỉ gửi dữ liệu bơm. Cửa hàng xuất hóa đơn từ dữ liệu đó trên NexERP.

Hai endpoint, cùng phạm vi invoices.write:

Endpoint	Chức năng
`POST /pump-logs`	Gửi một giao dịch
`POST /pump-logs/batch`	Gửi một lô, tối đa 100 giao dịch

Cách hoạt động

NexERP ghi nhận giao dịch rồi trả về ngay. Request không chờ lập hóa đơn.
Giao dịch vào hàng chờ của cửa hàng. Nhân viên bấm xuất hóa đơn, nhập mã số thuế khi khách cần.
Hết thời gian giữ mà chưa ai xuất, NexERP tự xuất cho người tiêu dùng. Doanh nghiệp tự đặt thời gian giữ, 0 đến 60 phút, mặc định 30 phút. Không giữ qua ngày.
Gửi lại cùng id_log không tạo giao dịch thứ hai.

Gửi một giao dịch

POST https://api-demo.nexerp.vn/api/open/v1/pump-logs

Header	Giá trị
`X-Api-Key`	Khóa API
`Content-Type`	`application/json`

Thân request là một giao dịch. Ý nghĩa từng trường ở bài Các trường giao dịch bơm.

{
  "id_log": "CH01-V03-20261028-000123",
  "store_code": "CH01",
  "fuel_code": "RON95",
  "nozzle_code": "V03",
  "unit_price": 21610,
  "liters": "4.627",
  "amount": 100000,
  "pumped_at": "2026-10-28T10:45:00+07:00"
}

curl -s -X POST "$BASE/pump-logs" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "id_log": "CH01-V03-20261028-000123",
    "store_code": "CH01",
    "fuel_code": "RON95",
    "nozzle_code": "V03",
    "unit_price": 21610,
    "liters": "4.627",
    "amount": 100000,
    "pumped_at": "2026-10-28T10:45:00+07:00"
  }'

Mã HTTP	Khi nào	Thân
202	Giao dịch mới được ghi nhận	Khối giao dịch bơm
200	Gửi lại y hệt một giao dịch đã có	Khối của giao dịch cũ
409	`id_log` đã dùng với nội dung khác	Khung lỗi, mã `log.id_conflict`
4xx khác	Dữ liệu sai, khóa sai, cửa hàng không được phép	Khung lỗi, xem Mã lỗi

Gửi một lô

POST https://api-demo.nexerp.vn/api/open/v1/pump-logs/batch

Thân request có một trường logs: mảng các giao dịch, mỗi phần tử giống hệt thân của POST /pump-logs.

{
  "logs": [
    { "id_log": "CH01-V03-20261028-000123", "store_code": "CH01", "fuel_code": "RON95", "nozzle_code": "V03",
      "unit_price": 21610, "liters": "4.627", "amount": 100000, "pumped_at": "2026-10-28T10:45:00+07:00" },
    { "id_log": "CH01-V01-20261028-000124", "store_code": "CH01", "fuel_code": "DO005S", "nozzle_code": "V01",
      "unit_price": 19850, "liters": "10.076", "amount": 200000, "pumped_at": "2026-10-28T10:46:12+07:00" }
  ]
}

Phản hồi 200, kết quả từng phần tử theo đúng thứ tự gửi:

{
  "received": 2,
  "accepted": 1,
  "duplicate": 0,
  "rejected": 1,
  "results": [
    { "id_log": "CH01-V03-20261028-000123", "status": "accepted", "id": "5d0f1c3a-8e2b-4b7a-9c61-0a4f2e7d9b10" },
    { "id_log": "CH01-V01-20261028-000124", "status": "rejected",
      "error": { "code": "log.fuel_code_unknown", "message": "Mã nhiên liệu «DO005S» chưa được khai trong bảng nhiên liệu của quyền tích hợp — doanh nghiệp cần khai trên NexERP trước.", "details": { "fuel_code": "DO005S" } } }
  ]
}

Trường	Kiểu	Ý nghĩa
`received`	số nguyên	Số phần tử trong lô
`accepted`	số nguyên	Số giao dịch mới được ghi nhận
`duplicate`	số nguyên	Số giao dịch gửi lại y hệt, đã có từ trước
`rejected`	số nguyên	Số phần tử bị từ chối
`results[].id_log`	chuỗi hoặc `null`	`id_log` của phần tử. `null` khi phần tử thiếu trường này
`results[].status`	chuỗi	`accepted`, `duplicate` hoặc `rejected`
`results[].id`	chuỗi UUID	Mã NexERP của giao dịch. Không có khi `rejected`
`results[].error`	đối tượng	Chỉ có khi `rejected`: `code`, `message`, `details` như khung lỗi

Quy tắc của lô:

Mỗi phần tử được kiểm và ghi riêng. Phần tử lỗi không làm mất phần tử khác.
Hai phần tử trùng id_log trong cùng lô: phần tử sau bị từ chối với mã log.duplicate_in_batch.
Cả request bị từ chối khi: khóa sai, logs rỗng hoặc không phải mảng (422 request.invalid), hơn 100 phần tử (413 request.too_many_logs).
Chỉ gửi lại các phần tử rejected sau khi sửa.

Lưu ý

Lô chỉ giảm số request, không làm hóa đơn ra nhanh hơn. Mỗi cửa hàng phát hành khoảng một hóa đơn mỗi 20 giây.
Gửi đều theo nhịp vài giây một lô nhỏ. Đừng dồn lô lớn sau khi mất mạng lâu.
Một lô tính là một request trong giới hạn tần suất.