Tạo hóa đơn

Gửi một giao dịch bán để NexERP lập hóa đơn bán và xếp hàng phát hành hóa đơn điện tử.

Gọi API tạo hóa đơn ngay khi giao dịch bán xong. NexERP trả về ngay, phần phát hành hóa đơn điện tử chạy sau.

Endpoint: POST /invoices, phạm vi invoices.write.

Request

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

Trên môi trường thật, thay phần địa chỉ gốc bằng địa chỉ NexERP cấp: POST <địa chỉ gốc thật>/invoices.

Header

Giá trị

X-Api-Key

Khóa API

Content-Type

application/json

Thân request là một hóa đơn JSON. Ý nghĩa và quy tắc từng trường ở bài Các trường hóa đơn.

Bán xăng, khách lẻ

Thuế suất KKKNT, khách không lấy hóa đơn đứng tên:

{
  "external_id": "CN5-P03-V2-20261022-000123",
  "store_code": "CN5",
  "issued_at": "2026-10-22T07:41:05+07:00",
  "payment_method": "TM",
  "buyer": { "name": null, "tax_code": null, "address": null, "citizen_id": null, "phone": null, "email": null },
  "lines": [
    {
      "item_code": "E10RON95M3",
      "name": "Xăng E10 Ron 95 Mức 3",
      "unit": "Lít",
      "unit_price": 26720,
      "quantity": "3.742515",
      "amount": 100000,
      "tax_rate": "KKKNT"
    }
  ],
  "fuel": { "pump_no": "03", "nozzle_no": "2", "meter_start": "1234567.890", "meter_end": "1234571.632" },
  "note": null
}
curl -s -X POST "$BASE/invoices" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_id": "CN5-P03-V2-20261022-000123",
    "store_code": "CN5",
    "issued_at": "2026-10-22T07:41:05+07:00",
    "payment_method": "TM",
    "lines": [
      { "item_code": "E10RON95M3", "name": "Xăng E10 Ron 95 Mức 3", "unit": "Lít",
        "unit_price": 26720, "quantity": "3.742515", "amount": 100000, "tax_rate": "KKKNT" }
    ]
  }'

Bán theo số tiền

Dòng KKKNT không có quantity: NexERP tự tính số lượng bằng amount / unit_price, 6 chữ số lẻ, làm tròn lên từ 5. Bán theo tiền ("đổ 100.000 đồng") nên gửi cách này.

{
  "external_id": "CN5-P03-V2-20261022-000124",
  "store_code": "CN5",
  "issued_at": "2026-10-22T07:45:10+07:00",
  "payment_method": "CK",
  "lines": [
    { "name": "Dầu DO 0,05S-II", "unit": "Lít", "unit_price": 20450, "amount": 200000, "tax_rate": "KKKNT" }
  ]
}

Hàng chịu thuế, người mua là doanh nghiệp

Thuế suất 10 %, đơn giá là giá đã gồm thuế:

{
  "external_id": "CN5-SHOP-20261022-000007",
  "store_code": "CN5",
  "issued_at": "2026-10-22T09:12:00+07:00",
  "payment_method": "TM/CK",
  "buyer": {
    "name": "Công ty TNHH Vận tải Ví Dụ",
    "tax_code": "0312345678",
    "address": "12 Đường số 3, Quận 7, TP.HCM",
    "email": "ketoan@vidu.example"
  },
  "lines": [
    { "name": "Nước suối 500ml", "unit": "Thùng", "unit_price": 110000, "quantity": "2", "amount": 220000, "tax_rate": "10" }
  ]
}

Phản hồi

Mã HTTP

Khi nào

Thân

202

Hóa đơn mới được tạo

Khối trạng thái hóa đơn

200

Gửi lại y hệt một giao dịch đã tạo

Khối trạng thái của hóa đơn cũ

409

external_id đã dùng với nội dung khác

Khung lỗi, mã invoice.external_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

Ví dụ phản hồi 202:

{
  "id": "0b3c5a2e-6f43-4f0e-9a52-6e2f6d6a7c11",
  "external_id": "CN5-P03-V2-20261022-000123",
  "status": "confirmed",
  "sold_at": "2026-10-22",
  "invoice_date": "2026-10-22",
  "einvoice_status": "queued",
  "einvoice": null,
  "replaced_by": null,
  "replaces": null
}

Ý nghĩa từng trường ở bài Khối trạng thái hóa đơn.

Lưu ý