Trên production, SePay CLI chỉ xem hóa đơn: einvoice invoice list và einvoice invoice get (Xem hóa đơn trên production). Các lệnh einvoice khác chỉ chạy trên sandbox, với dữ liệu giả lập; trên production, dùng API Hóa đơn điện tử hoặc my.sepay.vn.
Dùng nhóm lệnh einvoice (viết tắt inv) của SePay CLI để thử tạo và phát hành hóa đơn điện tử trên sandbox. Hóa đơn tạo hay phát hành ở đây không gửi tới cơ quan thuế.
invoice create gửi dữ liệu hóa đơn cho SePay; hóa đơn là nháp khi is_draft: true. invoice issue phát hành hóa đơn nháp; trên production, đó là lúc hóa đơn được gửi lên cơ quan thuế.
Bạn cần đăng nhập, công ty đã bật Test mode và sepay einvoice account list có ít nhất một tài khoản nhà cung cấp. invoice issue chỉ chạy trên sandbox và hỏi xác nhận; không có terminal thì thêm --yes.
Thứ tự lệnh (tạo với is_draft: false thì bỏ hai bước issue):
account get → invoice create → create-status → invoice issue → issue-status → invoice get
einvoice auth và einvoice quota
CLI tự lấy credential sandbox khi cần và không in ra. Kiểm tra credential đã sẵn sàng chưa và khi nào hết hạn:
$ sepay einvoice authenv: sandboxPRODUCT ENV AUTH EXPIRESeinvoice sandbox bearer 2026-11-02T16:10:17Z--refresh lấy bộ credential mới; --insecure-storage lưu credential trong tệp 0600 thay vì keychain.
Xem số hóa đơn còn lại:
$ sepay einvoice quotaenv: sandboxQUOTA REMAINING TAX APPROVED999 -TAX APPROVED là ngày cơ quan thuế chấp thuận, - khi chưa có. einvoice quota chỉ chạy trên sandbox; số hóa đơn còn lại trên production xem bằng sepay quota --env production (dòng einvoice).
einvoice account
Liệt kê tài khoản nhà cung cấp hóa đơn điện tử:
$ sepay einvoice account listenv: sandboxID PROVIDER ACTIVEc6448697-xxxx-xxxx-xxxx-a6006ab65aca matbao yespage 1/1 · 1 of 1Xem một tài khoản và các mẫu hóa đơn của nó:
$ sepay einvoice account get c6448697-xxxx-xxxx-xxxx-a6006ab65acaenv: sandboxID: c6448697-xxxx-xxxx-xxxx-a6006ab65acaProvider: matbaoActive: yesTax approved: - TEMPLATE SERIES LABEL1 C26TSE 1 - C26TSE - Hóa đơn giá trị gia tăng2 C26TSE 2 - C26TSE - Hóa đơn bán hàngID của tài khoản là provider_account_id; cột TEMPLATE và SERIES là template_code và invoice_series trong dữ liệu hóa đơn.
invoice create
Gửi dữ liệu hóa đơn cho SePay. Lệnh trả ngay tracking code; kết quả có sau vài giây, xem bằng create-status.
Tham số
| Tham số | Mô tả |
|---|---|
<payload> | Dữ liệu hóa đơn: @đường-dẫn (tệp), - (stdin) hoặc chuỗi JSON |
Dữ liệu là body của API xuất hóa đơn (Xuất hóa đơn điện tử: ý nghĩa từng trường, dòng hàng, thuế suất, mã lỗi).
Ví dụ
hoa-don.json (hóa đơn nháp):
{"provider_account_id": "<id>","template_code": "2","invoice_series": "C26TSE","issued_date": "<hôm nay, YYYY-MM-DD HH:MM:SS>","currency": "VND","buyer": {"name": "Công ty ABC","tax_code": "0101234567","address": "123 Đường A, Quận B, Hà Nội","email": "ketoan@congtyabc.vn"},"items": [{"line_number": 1,"line_type": 1,"item_code": "SP001","item_name": "Sản phẩm A","unit": "cái","quantity": 1,"unit_price": 50000}],"is_draft": true}
$ sepay einvoice invoice create @hoa-don.json✓ submitted (tracking 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40)poll: sepay einvoice invoice create-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Ghi chú
- Tracking code cũng là
reference_codecủa hóa đơn. Với--json, mã nằm ở trườngtracking_code. issued_datephải là ngày hôm nay (giờ Việt Nam, định dạngYYYY-MM-DD HH:MM:SS). Ngày khác bị từ chối vớiISSUED_DATE_INVALID, nên thay giá trị mẫu trước khi chạy.is_draftlà boolean, không phải chuỗi; thiếu hoặc sai kiểu thì lệnh dừng với exit code 2.
Trên sandbox, hóa đơn không gửi tới cơ quan thuế. Trên production, hóa đơn đã phát hành không hủy hay rút lại được, chỉ thay thế hoặc điều chỉnh được.
invoice create-status
Xem trạng thái lần tạo hóa đơn.
$ sepay einvoice invoice create-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Ref: 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Status: SuccessStatus | Ý nghĩa | Exit |
|---|---|---|
Pending | SePay và nhà cung cấp đang xử lý; kiểm tra lại sau 2 đến 3 giây | 0 |
Success | Hóa đơn đã được tạo | 0 |
Failed | Nhà cung cấp từ chối; dòng Reason: ghi lý do | 1 |
Lệnh xem trạng thái một lần rồi thoát, không tự chờ. Hóa đơn đã có số thì kết quả in thêm Number: và Total:. Vì Pending và Success cùng exit 0, script đọc trường status của --json:
tracking=$(sepay einvoice invoice create @hoa-don.json --json | jq -r '.tracking_code // empty')[ -n "$tracking" ] || exit 1 # lỗi đã in ra stderrfor i in $(seq 1 10); do# Exit khác 0: Failed (lý do ở trường message) hoặc lỗi khác (đã in ra stderr)if ! out=$(sepay einvoice invoice create-status "$tracking" --json); then[ -n "$out" ] && echo "$out" >&2exit 1fiif [ "$(echo "$out" | jq -r '.status')" = "Success" ]; thenecho "Đã tạo hóa đơn $tracking"; exit 0fisleep 3 # Pendingdoneecho "Hết thời gian chờ; kiểm tra lại: sepay einvoice invoice create-status $tracking" >&2exit 1
invoice issue và invoice issue-status
Phát hành hóa đơn nháp đã tạo ở invoice create.
Phát hành hóa đơn nháp:
$ sepay einvoice invoice issue 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Xem trạng thái phát hành:
$ sepay einvoice invoice issue-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40invoice issue nhận reference_code của hóa đơn nháp (tracking code lúc tạo) và in tracking code của lần phát hành, trùng với reference_code đó. issue-status có cùng kết quả và exit code với create-status; khi Success, Number: là số hóa đơn chính thức. Dùng lại vòng chờ của create-status cho issue <reference_code> --yes và issue-status.
invoice issue luôn hỏi xác nhận. Không chạy issue hai lần cho cùng một hóa đơn nháp: lần thứ hai vẫn được nhận, sau đó nhà cung cấp chuyển hóa đơn sang Failed (ExistsFkey).
invoice get và invoice list
Xem một hóa đơn đã phát hành:
$ sepay einvoice invoice get 522746a3-xxxx-xxxx-xxxx-940387b5e986env: sandboxRef: 522746a3-xxxx-xxxx-xxxx-940387b5e986Number: 326602Series: C26TSEStatus: issuedIssued: 2026-10-17Payment: TM/CKBuyer: Cong ty Nghiem Thu (MST 0101234567)Subtotal: 300.000Tax: 30.000Total: 330.000PDF: https://...Liệt kê hóa đơn tạo qua API:
$ sepay einvoice invoice list --source api --per-page 50invoice get nhận reference_code, in các trường của hóa đơn, tiếp theo là bảng dòng hàng (ITEM, QTY, UNIT PRICE, TAX%, AMOUNT), kèm link tệp PDF, XML (pdf_url, xml_url) khi nhà cung cấp đã tạo tệp.
Flag của invoice list | Kiểu | Mô tả |
|---|---|---|
--source | string | manual (tạo trên my.sepay.vn) | api (tạo qua API và CLI) |
--page, --per-page | int | Phân trang; tối đa 100 |
Xem hóa đơn trên production
invoice list và invoice get chạy cả trên production. Hai lệnh chỉ đọc nên không hỏi xác nhận, và default_env: production cũng tính. CLI đọc hóa đơn bằng phiên đăng nhập của bạn:
$ sepay einvoice invoice list --env production --per-page 50 -o json$ sepay einvoice invoice get <reference_code> --env production -o json- Token cần scope
einvoice:read; thiếu thì lệnh dừng với exit code 5 và báotoken lacks the required scope, run: sepay auth refresh --scopes einvoice:read. - Tài khoản cần quyền Hóa đơn điện tử trong công ty; thiếu thì exit code 8,
your account lacks permission for this action; ask an admin of your company. - Tiền là số nguyên (
total_before_tax,tax_amount,total_amount); tổng server gửinullthì đọc là0.buyerluôn cóname, có thể cótax_code,address,email. -o jsoncủalistlà một mảng, không kèm thông tin trang. Đọc hết các trang nhưpg order list, khóa làreference_code.
Tạo, phát hành, thay thế, điều chỉnh hóa đơn trên production chưa có trong CLI.
Mã lỗi
| Thông báo hoặc mã | Exit / error_code | Nguyên nhân |
|---|---|---|
Exit code 2 khi invoice create | 2 / usage_error | is_draft thiếu hoặc là chuỗi, hoặc JSON sai cú pháp |
Failed (create-status, issue-status) | 1 / không có; status: Failed trên stdout | Nhà cung cấp từ chối; lý do ở Reason: hoặc message. Mã lỗi API: Xuất hóa đơn điện tử |
no invoice with that reference code | 1 / EINVOICE_DOCUMENT_NOT_FOUND | reference_code không tồn tại, thường do gõ nhầm hoặc nhầm môi trường (invoice list liệt kê hóa đơn hiện có) |
this company has no e-invoice provider account | 1 / EINVOICE_ACCOUNT_NOT_FOUND | Công ty chưa có tài khoản nhà cung cấp; einvoice account list không có dòng nào |
einvoice_provision_failed, einvoice_token_failed | 1 | SePay chưa tạo xong môi trường hóa đơn sandbox hoặc chưa cấp được credential; chạy lại, lặp lại thì báo SePay |