Bạn cần có:
- client_id và client_secret từ tài khoản SePay eInvoice
- Sử dụng môi trường Sandbox để thử nghiệm:
https://einvoice-api-sandbox.sepay.vn - Tất cả API calls phải thực hiện từ server-side — không gọi trực tiếp từ client/browser
Bước 1: Lấy Access Token
Mọi API eInvoice đều yêu cầu xác thực bằng Bearer token. Gọi endpoint /v1/token với Basic Authentication để lấy access_token.
https://einvoice-api.sepay.vn/v1/tokenKHÔNG gọi API này từ browser hay mobile app. client_secret phải được giữ tuyệt mật trên server của bạn.
curl --request POST \--url https://einvoice-api.sepay.vn/v1/token \--header 'Authorization: Basic REPLACE_BASIC_AUTH'
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
}Token có hiệu lực 86400 giây (24 giờ). Nên lưu vào cache và tái sử dụng thay vì gọi lại mỗi request. Khi nhận lỗi 401, tự động lấy token mới.
Bước 2: Lấy danh sách tài khoản nhà cung cấp
Trước khi tạo hóa đơn, bạn cần biết provider_account_id — ID tài khoản nhà cung cấp hóa đơn điện tử đã được cấu hình trong hệ thống. Gọi endpoint /v1/provider-accounts để lấy danh sách.
https://einvoice-api.sepay.vn/v1/provider-accountscurl --request GET \--url 'https://einvoice-api.sepay.vn/v1/provider-accounts?page=1&per_page=20' \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{
"data": {
"paging": {
"per_page": 20,
"total": 1,
"has_more": false,
"current_page": 1,
"page_count": 1
},
"items": [
{
"id": "0aea3134-da40-11f0-aef4-52c7e9b4f41b",
"provider": "matbao",
"active": true,
"tax_authority_approved_date": "2026-04-20"
}
]
}
}Chỉ sử dụng tài khoản có active: true. Nếu bạn có nhiều tài khoản từ nhiều nhà cung cấp khác nhau, hãy gọi API chi tiết tài khoản để xem mẫu hóa đơn và ký hiệu được phép dùng cho từng tài khoản.
Bước 3: Tạo và phát hành hóa đơn
Gọi endpoint /v1/invoices/create với is_draft: false để tạo và phát hành hóa đơn trực tiếp (không qua bước nháp). API xử lý bất đồng bộ và trả về tracking_code để theo dõi kết quả ở bước tiếp theo.
https://einvoice-api.sepay.vn/v1/invoices/createMã mẫu hóa đơn (lấy từ API chi tiết tài khoản)
Ký hiệu hóa đơn (lấy từ API chi tiết tài khoản)
Ngày phát hành (YYYY-MM-DD HH:mm:ss)
Đơn vị tiền tệ:
- VND: Việt Nam Đồng
- USD: Đô la Mỹ
- CAD: Đô la Canada
VNDID tài khoản nhà cung cấp (UUID)
Phương thức thanh toán:
- TM: Tiền mặt (Cash)
- CK: Chuyển khoản (Bank transfer)
- TM/CK: Tiền mặt và chuyển khoản (Cash and bank transfer)
- KHAC: Khác (Other)
true: Xuất nháp (cần phát hành sau, không tính vào hạn ngạch)false: Xuất và phát hành luôn
falseDanh sách hàng hóa/dịch vụ
Ghi chú nội bộ
curl --request POST \--url https://einvoice-api.sepay.vn/v1/invoices/create \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \--header 'content-type: application/json' \--data '{"template_code":"1","invoice_series":"C26TSE","issued_date":"2026-01-26 00:00:00","currency":"VND","provider_account_id":"0aea3134-da40-11f0-aef4-52c7e9b4f41b","payment_method":"TM","is_draft":false,"buyer":{"type":"personal","name":"Công ty TNHH ABC","legal_name":"CÔNG TY CỔ PHẦN ABC","tax_code":"0123456789","address":"123 Đường ABC, Quận 1, TP.HCM","email":"contact@abc.com","phone":"0901234567","buyer_code":"KH-001","national_id":"001234567890"},"items":[{"line_number":1,"line_type":1,"item_code":"SP001","item_name":"Sản phẩm A","unit":"cái","quantity":10,"unit_price":100000,"tax_rate":10,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":4500000}],"notes":"Ghi chú nội bộ"}'
{
"success": true,
"data": {
"tracking_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"tracking_url": "https://einvoice-api.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"message": "Đã tạo yêu cầu xuất bán hóa đơn điện tử"
}
}API trả về tracking_code ngay lập tức, nhưng hóa đơn chưa được phát hành tại thời điểm này. Bạn bắt buộc phải thực hiện Bước 4 để xác nhận kết quả phát hành.
Bước 4: Kiểm tra trạng thái tạo hóa đơn
Gọi endpoint /v1/invoices/create/check/{tracking_code} để kiểm tra kết quả tạo hóa đơn. Khi is_draft: false, bước tạo đã bao gồm ký số và nộp lên cơ quan thuế — endpoint này xác nhận toàn bộ kết quả đó. Thực hiện polling với khoảng cách 2-3 giây, tối đa 10 lần.
https://einvoice-api.sepay.vn/v1/invoices/create/check/{tracking_code}curl --request GET \--url https://einvoice-api.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{
"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": "2025-12-15",
"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"
},
"total_before_tax": 200000,
"tax_amount": 20000,
"total_amount": 220000,
"notes": "Ghi chú hóa đơn",
"source": "api"
}
}
}Nếu status trả về "Failed", kiểm tra trường message để biết nguyên nhân cụ thể (sai thông tin người mua, ký hiệu hóa đơn không hợp lệ, hết hạn mức...). Sau khi sửa dữ liệu, gọi lại API Xuất hóa đơn để tạo hóa đơn mới.
Bước tiếp theo
Sau khi phát hành hóa đơn thành công:
- Xác thực Bearer Token — Chi tiết về xác thực và quản lý token
- Danh sách nhà cung cấp — Xem và chọn tài khoản nhà cung cấp
- Chi tiết nhà cung cấp — Lấy cấu hình mẫu và ký hiệu hóa đơn
- Xuất hóa đơn điện tử — Tham số đầy đủ khi tạo hóa đơn
- Trạng thái xuất hóa đơn — Chi tiết về polling trạng thái
- Phát hành hóa đơn từ nháp — Luồng tạo nháp rồi phát hành
- Chi tiết hóa đơn — Lấy thông tin hóa đơn sau phát hành
- Tải hóa đơn — Tải file PDF/XML của hóa đơn
- Kiểm tra hạn mức — Theo dõi số lượt phát hành còn lại