Xuất hóa đơn điện tử cho hộ kinh doanh, doanh nghiệp | SePay eInvoice API

SePay eInvoice API là gì?

SePay eInvoice API giúp hộ kinh doanh và doanh nghiệp xuất 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. Qua một giao diện API RESTful duy nhất, hệ thống của bạn có thể tạo hóa đơn, phát hành lên cơ quan thuế (CQT) và quản lý toàn bộ vòng đời hóa đơn một cách tự động.

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ử:

Hộ kinh doanh & doanh nghiệp

Xuất hóa đơn điện tử cho từng giao dịch bán hàng, đáp ứng yêu cầu hóa đơn theo Nghị định 123/2020/NĐ-CP.

Nền tảng SaaS & ERP

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.

Doanh nghiệp xuất hóa đơn số lượng lớn

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.

Phần mềm kế toán

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.

Sàn thương mại điện tử

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.

Developer xây dựng giải pháp

Tích hợp tính năng phát hành hóa đơn điện tử vào sản phẩm phục vụ khách hàng doanh nghiệp.

Tính năng chính

Xuất hóa đơn điện tử

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.

Phát hành lên cơ quan thuế

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.

Theo dõi trạng thái bất đồng bộ

Kiểm tra kết quả xử lý create/issue theo thời gian thực thông qua API /check/{tracking_code}.

Tra cứu và tải hóa đơn

Lấy chi tiết hóa đơn đã phát hành kèm URL tải file PDF, XML theo chuẩn CQT.

Kiểm tra hạn mức sử dụng

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ụ.

Quản lý tài khoản nhà cung cấp

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 xuất hóa đơn điện tử

Rendering diagram...

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ấy access_token dù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_code riê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ý.

Xử lý bất đồng bộ

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 thử nghiệm trên Sandbox trước khi chuyển sang Production. Cách lấy token Sandbox, gọi API và dữ liệu cách ly có trong Sandbox SePay eInvoice API.

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