Tổng quan SePay eInvoice API

Giới thiệu

• eInvoice API giúp doanh nghiệp tạo, phát hành và tra cứu hóa đơn điện tử qua HTTP.
• Hỗ trợ hai môi trường: Sandbox cho thử nghiệm và Production cho vận hành.

Môi trường & Base URL

Production: https://einvoice-api.sepay.vn
Sandbox: https://einvoice-api-sandbox.sepay.vn

Xác thực

Header: Authorization: Bearer <ACCESS_TOKEN>

Luồng tổng quát

• Mô tả luồng xử lý eInvoice:

• Luồng xử lý eInvoice bao gồm các bước chính từ xác thực, kiểm tra tài khoản/ hạn ngạch đến tạo, phát hành và tra cứu hóa đơn:

1. Lấy access token Ứng dụng của merchant gọi API để lấy access_token. Token này được sử dụng cho tất cả các API eInvoice tiếp theo.

2. Danh sách tài khoản Merchant truy vấn danh sách tài khoản nhà cung cấp (GET v1/provider-accounts) để biết các tài khoản eInvoice khả dụng cùng trạng thái của từng tài khoản.

3. Chi tiết tài khoản Khi đã chọn được tài khoản, merchant gọi GET v1/provider-accounts/{id} để lấy cấu hình chi tiết (mẫu/ký hiệu hóa đơn, trạng thái hoạt động).

4. Tạo hóa đơn (Create) Merchant gửi dữ liệu hóa đơn lên hệ thống (POST v1/invoices/create). API trả về tracking_code để theo dõi trạng thái xử lý xuất hóa đơn.

5. Kiểm tra trạng thái tạo hóa đơn Merchant sử dụng tracking_code gọi /create/check để kiểm tra trạng thái xuất hóa đơn (thành công hoặc thất bại).

6. Phát hành hóa đơn (Issue) Sau khi hóa đơn được tạo thành công, merchant gửi yêu cầu phát hành (POST v1/invoices/issue). API trả về tracking_code cho bước phát hành.

7. Kiểm tra trạng thái phát hành Merchant gọi /issue/check với tracking_code để xác nhận kết quả phát hành hóa đơn.

8. Lấy chi tiết hóa đơn Khi hóa đơn đã phát hành thành công, merchant có thể truy vấn GET v1/invoices/{reference_code} để nhận thông tin và file hóa đơn (PDF, XML,…).

9. Kiểm tra hạn ngạch Merchant có thể gọi GET v1/usage để theo dõi số lượt phát hành/xuất hóa đơn còn lại nhằm tối ưu kế hoạch sử dụng dịch vụ.

10. Danh sách hóa đơn Merchant có thể gọi GET v1/invoices để lấy danh sách các hóa đơn đã tạo/phát hành kèm phân trang phục vụ quản lý và đối soát.

Endpoint chính

Cấu trúc phản hồi chung

{
  "success": true,
  "data": "object"
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Thông điệp lỗi"
  }
}

Mã lỗi chung

Bước tiếp theo

Để bắt đầu sử dụng eInvoice API, bạn cần thực hiện theo thứ tự sau:

1. Tạo Access Token - Lấy Bearer token để xác thực các API tiếp theo
2. Danh sách tài khoản - Xem các tài khoản nhà cung cấp hóa đơn điện tử khả dụng
3. Xuất hóa đơn điện tử - Bắt đầu tạo hóa đơn đầu tiên