Hóa đơn thay thế

Lập hóa đơn thay thế cho hóa đơn đã phát hành mà sai, kèm lý do và external_id mới.

Hóa đơn đã phát hành mà sai chỉ sửa được bằng hóa đơn thay thế. Khi hóa đơn thay thế phát hành xong, hóa đơn gốc chuyển sang replaced.

Endpoint: POST /invoices/{id}/replace, phạm vi invoices.write.

Request

POST https://api-demo.nexerp.vn/api/open/v1/invoices/{id}/replace

Trên môi trường thật, thay phần địa chỉ gốc bằng địa chỉ NexERP cấp. Header: X-Api-Key, Content-Type: application/json.

Tham số	Nằm ở	Kiểu	Ý nghĩa
`id`	đường dẫn	chuỗi UUID	`id` của hóa đơn gốc cần thay thế

Nội dung gửi

Giống Tạo hóa đơn, thêm hai điểm:

reason: bắt buộc, tối đa 500 ký tự, không được toàn khoảng trắng.
external_id: dùng mã mới, khác mã của hóa đơn gốc.

Trường note bị bỏ qua, lý do thay thế nằm ở reason.

{
  "external_id": "CN5-P03-V2-20261022-000123-R1",
  "store_code": "CN5",
  "issued_at": "2026-10-22T07:41:05+07:00",
  "payment_method": "TM",
  "reason": "Nhập sai số lượng, đã điều chỉnh lại",
  "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" }
  ]
}

curl -s -X POST "$BASE/invoices/0b3c5a2e-6f43-4f0e-9a52-6e2f6d6a7c11/replace" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_id": "CN5-P03-V2-20261022-000123-R1",
    "store_code": "CN5",
    "issued_at": "2026-10-22T07:41:05+07:00",
    "payment_method": "TM",
    "reason": "Nhập sai số lượng, đã điều chỉnh lại",
    "lines": [
      { "name": "Xăng E10 Ron 95 Mức 3", "unit": "Lít", "unit_price": 26720,
        "quantity": "3.742515", "amount": 100000, "tax_rate": "KKKNT" }
    ]
  }'

Phản hồi 202 là Khối trạng thái hóa đơn của hóa đơn thay thế, có replaces trỏ về hóa đơn gốc.

Điều kiện

Điều kiện	Vi phạm thì nhận
Hóa đơn gốc do chính ứng dụng của bạn tạo	404
Quyền tích hợp có `journal_mode = none` (xem `GET /me`), và hóa đơn gốc chưa ghi sổ	422 `invoice.replace_journal_unsupported`
Hóa đơn gốc đang `issued` hoặc `cqt_accepted`	409 `invoice.replace_not_allowed`
Cùng cửa hàng với hóa đơn gốc	422 `invoice.replace_store_mismatch`

Hóa đơn gốc chưa phát hành, đã hủy hoặc đã bị thay thế đều nhận 409 invoice.replace_not_allowed.

Lưu ý

Một lần thay thế trước đó thất bại thì các lần thay thế tiếp bị chặn (409) cho tới khi kế toán hủy bản thất bại trên NexERP. Liên hệ doanh nghiệp.
Cả hóa đơn gốc và hóa đơn thay thế đều gửi webhook.
Gửi lại cùng external_id và cùng nội dung thì nhận 200 và bản thay thế cũ. Khác nội dung thì nhận 409 invoice.external_id_conflict.