Giới thiệu
SePay eInvoice API là lớp trung gian giữa hệ thống của doanh nghiệp và cơ quan thuế (CQT), cho phép tạo và phát hành hóa đơn điện tử tuân thủ Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC của Bộ Tài chính. Thay vì tích hợp riêng lẻ với từng nhà cung cấp hóa đơn điện tử, doanh nghiệp chỉ cần tích hợp một lần duy nhất với SePay để phát hành hóa đơn qua bất kỳ nhà cung cấp nào đã cấu hình.
API cung cấp đầy đủ vòng đời hóa đơn: từ tạo nháp, phát hành lên CQT, kiểm tra trạng thái theo thời gian thực, cho đến tải file PDF/XML và tra cứu hạn mức sử dụng — tất cả thông qua giao diện RESTful HTTP chuẩn.
Xem hóa đơn demoĐối tượng sử dụng
eInvoice API phù hợp cho các tổ chức và cá nhân cần tự động hóa quy trình xuất hóa đơn điện tử:
Tích hợp phát hành hóa đơn điện tử trực tiếp vào quy trình bán hàng, kế toán hoặc quản lý đơn hàng của phần mềm.
Tự động hóa hoàn toàn việc tạo và phát hành hóa đơn theo lô, giảm thiểu thao tác thủ công và sai sót.
Kết nối trực tiếp với CQT để phát hành và đồng bộ trạng thái hóa đơn, hỗ trợ đối soát và lưu trữ theo quy định.
Tự động xuất hóa đơn cho từng đơn hàng hoàn thành, đáp ứng yêu cầu xuất hóa đơn theo giao dịch.
Xây dựng tính năng hóa đơn điện tử cho khách hàng doanh nghiệp mà không cần đàm phán trực tiếp với từng nhà cung cấp.
Tính năng chính
Tạo hóa đơn nháp hoặc phát hành trực tiếp qua POST v1/invoices/create, hỗ trợ nhiều mẫu và ký hiệu hóa đơn.
Gửi hóa đơn đến CQT qua nhà cung cấp hóa đơn điện tử đã cấu hình bằng POST v1/invoices/issue.
Kiểm tra kết quả xử lý create/issue theo thời gian thực thông qua API /check/{tracking_code}.
Lấy chi tiết hóa đơn đã phát hành kèm URL tải file PDF, XML theo chuẩn CQT.
Theo dõi số lượt phát hành còn lại qua GET v1/usage để lên kế hoạch sử dụng dịch vụ.
Xem danh sách và cấu hình chi tiết của các tài khoản nhà cung cấp hóa đơn điện tử đã đăng ký.
Luồng xử lý
Luồng xử lý eInvoice gồm các bước tuần tự từ xác thực, kiểm tra tài khoản đến tạo và phát hành hóa đơn:
-
Lấy access token — Gọi
POST v1/tokenđể lấyaccess_tokendùng cho tất cả các API tiếp theo. -
Danh sách tài khoản nhà cung cấp — Gọi
GET v1/provider-accountsđể xem các tài khoản hóa đơn điện tử khả dụng và trạng thái từng tài khoản. -
Chi tiết tài khoản — Gọi
GET v1/provider-accounts/{id}để lấy cấu hình chi tiết: mẫu hóa đơn, ký hiệu, trạng thái hoạt động. -
Tạo hóa đơn (Create) — Gửi dữ liệu hóa đơn qua
POST v1/invoices/create. API trả vềtracking_codeđể theo dõi quá trình xử lý. -
Kiểm tra trạng thái tạo hóa đơn — Gọi
GET v1/invoices/create/check/{tracking_code}để xác nhận hóa đơn được tạo thành công hay thất bại. -
Phát hành hóa đơn (Issue) — Gửi yêu cầu phát hành qua
POST v1/invoices/issue. API trả vềtracking_coderiêng cho bước phát hành. -
Kiểm tra trạng thái phát hành — Gọi
GET v1/invoices/issue/check/{tracking_code}để xác nhận kết quả phát hành lên CQT. -
Lấy chi tiết hóa đơn — Sau khi phát hành thành công, gọi
GET v1/invoices/{reference_code}để nhận thông tin đầy đủ và URL tải file PDF, XML. -
Kiểm tra hạn ngạch — Gọi
GET v1/usageđể theo dõi số lượt phát hành còn lại. -
Danh sách hóa đơn — Gọi
GET v1/invoicesđể lấy danh sách hóa đơn có phân trang phục vụ đối soát và quản lý.
Các bước Create và Issue được xử lý bất đồng bộ. Sau khi gọi mỗi bước, bạn phải gọi API /check tương ứng để xác nhận trạng thái trước khi chuyển sang bước tiếp theo.
Môi trường
| Môi trường | Base URL |
|---|---|
| Production | https://einvoice-api.sepay.vn |
| Sandbox | https://einvoice-api-sandbox.sepay.vn |
Xác thực bằng Bearer token trong header: Authorization: Bearer <ACCESS_TOKEN>
Nếu bạn mới bắt đầu, hãy sử dụng môi trường Sandbox để thử nghiệm trước khi chuyển sang Production.
Bước tiếp theo
Để bắt đầu tích hợp eInvoice API, thực hiện theo thứ tự sau:
- Xác thực API hóa đơn điện tử (Bearer Token) — Lấy Bearer token để xác thực các API tiếp theo
- Danh sách nhà cung cấp hóa đơn điện tử — Xem các tài khoản nhà cung cấp hóa đơn điện tử khả dụng
- Xuất hóa đơn điện tử — Bắt đầu tạo hóa đơn đầu tiên