API theo dõi trạng thái xuất hóa đơn

Dùng chung cho cả ba luồng xuất hóa đơn

Endpoint này theo dõi tracking_code của xuất hóa đơn điện tử, xuất hóa đơn điều chỉnh và xuất hóa đơn thay thế - cả ba đi chung một hàng đợi xử lý nên chỉ cần một endpoint tra trạng thái.

Trường document_type trong data.invoice cho biết kết quả là hóa đơn loại nào.

API Endpoint

GET

https://einvoice-api.sepay.vn/v1/invoices/create/check/{tracking_code}

API Request

tracking_codestringrequired

Mã tracking trả về khi gọi API xuất hóa đơn

API Response

Response thành công (200)

{
  "success": true,
  "data": {
    "reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "status": "Success",
    "message": "Xuất hóa đơn điện tử thành công",
    "invoice": {
      "reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
      "invoice_number": "0",
      "issued_date": "2026-01-26",
      "pdf_url": "https://beta-portalv2.mifi.vn/DownloadPDFCA.aspx?kk=1434747710&keyinv=...",
      "xml_url": null,
      "status": "draft",
      "buyer": {
        "name": "Công ty ABC",
        "tax_code": "0101234567",
        "address": "123 Đường A, Quận B, Hà Nội",
        "email": "buyer@example.com",
        "phone": "0900000000"
      },
      "seller_store": {
        "xid": "8f14e45f-ceea-4b6d-9c1a-2b3c4d5e6f70",
        "code": "CN01",
        "name": "Chi nhánh 1"
      },
      "total_before_tax": 200000,
      "tax_amount": 20000,
      "total_amount": 220000,
      "notes": "Ghi chú hóa đơn",
      "source": "api"
    }
  }
}

successboolean

dataobject

Xử lý lỗi

400Bad Request

Thiếu hoặc sai tracking_code.

401Unauthorized

Thiếu hoặc sai Bearer token.

404Not Found

Không tìm thấy yêu cầu tương ứng với tracking_code.

Lưu ý

Sử dụng tracking_code trả về từ API Xuất hóa đơn điện tử.
Khi status là Success, đối tượng invoice sẽ chứa thông tin chi tiết hóa đơn bao gồm pdf_url để tải file PDF.
Nếu status là Failed, kiểm tra trường message để biết nguyên nhân lỗi và xử lý phù hợp.
Yêu cầu gặp lỗi tạm thời được thử lại tự động nên có thể ở trạng thái Pending tới 2 giờ, không phải kết thúc trong vài giây. Dùng retry.next_retry_at trong response để giãn nhịp gọi, và chỉ dừng khi status chuyển sang Success hoặc Failed.
Nếu message là "Hệ thống chưa xác nhận được kết quả phát hành với nhà cung cấp hóa đơn", trạng thái hóa đơn chưa xác định. Không gửi lại yêu cầu - hãy liên hệ SePay để kiểm tra, tránh phát hành trùng hóa đơn.
Lịch retry, cách chẩn đoán và các bước kiểm tra trước khi gửi lại: xem Xử lý lỗi.

Code mẫu

curl --request GET \
  --url https://einvoice-api.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Bước tiếp theo

Tùy vào kết quả trạng thái và loại hóa đơn đã tạo:

Nếu status là Success và hóa đơn nháp (is_draft=true):

Phát hành hóa đơn điện tử - Sử dụng reference_code để phát hành chính thức

Nếu status là Success và hóa đơn chính thức (is_draft=false):

Tải hóa đơn - Tải file PDF hoặc XML của hóa đơn
Chi tiết hóa đơn - Xem thông tin chi tiết hóa đơn đã phát hành
Danh sách hóa đơn - Quản lý và tra cứu các hóa đơn đã tạo

Nếu status là Failed:

Kiểm tra message để biết nguyên nhân lỗi và tạo lại hóa đơn với thông tin đã sửa hoặc liên hệ SePay để được hỗ trợ