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

Ý nghĩa từng trường của khối trạng thái hóa đơn mà API tạo, tra cứu, thay thế và webhook đều trả về.

Mọi endpoint hóa đơn trả về cùng một khối JSON. Webhook gửi đúng khối này trong trường invoice.

Khối này trả về từ:

POST /invoices (tạo hóa đơn)
GET /invoices/{id} và GET /invoices?external_id=... (tra cứu)
POST /invoices/{id}/replace (hóa đơn thay thế)
webhook invoice.einvoice_status_changed, trường invoice

{
  "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": "cqt_accepted",
  "einvoice": {
    "number": "00000123",
    "serial": "1C26MLB",
    "template": "1",
    "lookup_code": "A1B2C3D4E5F6",
    "issued_at": "2026-10-22T07:41:40+07:00",
    "view_url": "https://tracuu.vidu.example/invoice/A1B2C3D4E5F6",
    "error": null
  },
  "replaced_by": null,
  "replaces": null
}

Các trường

Trường	Kiểu	Ý nghĩa
`id`	chuỗi UUID	Mã hóa đơn trên NexERP. Dùng cho `GET /invoices/{id}`, `/link` và `/replace`
`external_id`	chuỗi	Mã giao dịch bạn gửi lúc tạo
`status`	chuỗi	Trạng thái hóa đơn trong NexERP. Là `confirmed` ngay sau khi tạo
`sold_at`	ngày `YYYY-MM-DD`	Ngày bán, lấy từ `issued_at` theo giờ Việt Nam
`invoice_date`	ngày `YYYY-MM-DD`	Ngày lập hóa đơn trên hóa đơn điện tử
`einvoice_status`	chuỗi	Trạng thái hóa đơn điện tử. Bảng giá trị ở bài Tra cứu hóa đơn
`einvoice`	đối tượng hoặc `null`	Thông tin hóa đơn điện tử. Là `null` khi chưa có số liệu nào từ nhà cung cấp
`replaced_by`	chuỗi UUID hoặc `null`	`id` của hóa đơn đã thay thế hóa đơn này
`replaces`	chuỗi UUID hoặc `null`	`id` của hóa đơn gốc mà hóa đơn này thay thế

Khối einvoice

Trường	Kiểu	Ý nghĩa
`number`	chuỗi hoặc `null`	Số hóa đơn điện tử, ví dụ `00000123`
`serial`	chuỗi hoặc `null`	Ký hiệu hóa đơn, ví dụ `1C26MLB`
`template`	chuỗi hoặc `null`	Mẫu số hóa đơn của cửa hàng, ví dụ `1`
`lookup_code`	chuỗi hoặc `null`	Mã tra cứu hóa đơn trên trang của nhà cung cấp
`issued_at`	thời điểm ISO 8601 hoặc `null`	Lúc hóa đơn điện tử được phát hành
`view_url`	chuỗi URL hoặc `null`	Link xem hóa đơn đã lưu lúc phát hành
`error`	chuỗi hoặc `null`	Lý do lỗi khi phát hành không thành công

Lưu ý

Trường mới có thể được thêm vào khối này sau. Bỏ qua trường lạ, đừng báo lỗi.
Các trường trong einvoice có thể đến dần: số và ký hiệu có trước, mã tra cứu có sau.