MÔI TRƯỜNG KIỂM THỬ – SiSuInvoice là nhà cung cấp hóa đơn điện tử GIẢ LẬP: hóa đơn không có giá trị pháp lý, không gửi cơ quan thuế thật.
Tài liệu tích hợp API
API REST / JSON phiên bản v1 tại https://invoice.sisunext.vn/api/v1. Đặc tả máy đọc được: /openapi/v1.json
(OpenAPI 3). Mọi hóa đơn là GIẢ LẬP – dùng để kiểm thử phần mềm kết nối.
1. Bắt đầu nhanh
- Đăng ký tài khoản → tạo đơn vị phát hành theo MST (chọn "Nạp dữ liệu mẫu" để có sẵn tờ khai được chấp nhận và ký hiệu năm nay).
- Trong đơn vị: Khóa API → tạo khóa (chọn phạm vi), chép khóa
siv_…(chỉ hiện một lần). - Đổi khóa lấy token rồi gọi API:
curl -X POST https://invoice.sisunext.vn/api/v1/auth/token -H "Content-Type: application/json" -d "{\"apiKey\":\"siv_...\"}"
curl -X POST https://invoice.sisunext.vn/api/v1/invoices -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d @hoadon.json
Ví dụ hoadon.json (hóa đơn GTGT có mã, ký hiệu 1C26TAA):
{
"clientRef": "BH-000123",
"templateCode": "1",
"series": "C26TAA",
"paymentMethod": "CK",
"buyer": { "name": "Công ty TNHH Khách Hàng", "taxCode": "9900000016", "address": "1 Tràng Tiền, Hà Nội", "email": "[email protected]" },
"lines": [
{ "itemCode": "SP01", "itemName": "Máy in laser", "unit": "Cái", "quantity": 2, "unitPrice": 3500000, "taxRate": "10%" },
{ "kind": "TradeDiscount", "itemName": "Chiết khấu thương mại", "amount": 200000, "taxRate": "10%" }
],
"issue": true,
"sendToBuyer": true
}
Kết quả là InvoiceInfo: status = Issued, number, taxAuthorityCode (34 ký tự, tiền tố SIM),
lookupCode + lookupUrl, tổng theo thuế suất.
2. Xác thực
POST /api/v1/auth/tokenvới{ "apiKey": "siv_…" }→{ accessToken, expiresAt, unitTaxCode, scopes }(mặc định 60 phút).- Gửi
Authorization: Bearer <accessToken>ở mọi yêu cầu. Token hết hạn → 401auth.token-expired: lấy token mới. - Thu hồi khóa có tác dụng ngay với token đã cấp (401
auth.key-revoked). - Phạm vi:
invoices.read(đọc),invoices.write(lập, phát hành, gửi người mua),invoices.errors(04/SS, điều chỉnh, thay thế, hủy),invoices.pos(máy tính tiền). Thiếu phạm vi → 403auth.scope. - Giới hạn: 600 yêu cầu / phút / token (429
rate-limited). Mọi phản hồi cóX-Request-Id– dùng để tra ở trang Nhật ký API.
3. Lập – phát hành – tra cứu
| Thao tác | Gọi |
|---|---|
| Thông tin đơn vị, đồng hồ của đơn vị | GET /unit |
| Ký hiệu (trạng thái, số mới nhất) | GET /series |
| Xem nháp (tính tổng, bản thể hiện HTML, không lưu) | POST /invoices/preview |
| Lập (nháp hoặc phát hành ngay) | POST /invoices |
| Sửa nháp / hóa đơn bị từ chối | PUT /invoices/{id} |
| Phát hành nháp / gửi lại hóa đơn bị từ chối | POST /invoices/{id}/issue |
| Xóa nháp | DELETE /invoices/{id} |
Một hóa đơn (theo id hoặc ref:<clientRef>) | GET /invoices/{id} |
| Danh sách (from, to, status, templateCode, series, number, clientRef, search, pos, page, pageSize) | GET /invoices |
| Tải XML đã ký / PDF / bản chuyển đổi | GET /invoices/{id}/xml|pdf|converted |
| Gửi người mua | POST /invoices/{id}/send |
- Chống trùng:
clientRef(≤ 64 ký tự, duy nhất trong đơn vị). Gửi lại cùng nội dung → trả hóa đơn đã có; nháp thì phát hành tiếp. Khác nội dung → 409invoice.client-ref-conflict. An toàn để thử lại khi mất kết nối. - Trạng thái:
Draft → Sent → Issued(hoặcRejected); về sauAdjusted/Replaced/Cancelled. "Chậm cấp mã" → ởSenttới khi cơ quan thuế (mô phỏng) trả kết quả – theo dõi bằng webhook hoặcGET /invoices/{id}. - Số hóa đơn tăng theo thời gian trong ký hiệu: ngày lập trước ngày của hóa đơn mới nhất đã có số → 409
invoice.date-order. Ngày lập khác ngày ký: phải ký chậm nhất ngày làm việc tiếp theo (409invoice.sign-deadline). - Hóa đơn có mã:
taxAuthorityCode34 ký tự; không mã (ký hiệuK…):Issuedkhi dữ liệu được tiếp nhận (01/TB-KTDL).
4. Xử lý hóa đơn sai (Thông tư 91/2026 Điều 10)
- Sai tên, địa chỉ người mua, số tiền bằng chữ… (không sai MST, tiền, thuế suất, tiền thuế, hàng hóa):
POST /error-noticesvới{ items: [{ invoiceId, nature: "Notify", reason }] }– không lập lại hóa đơn. - Sai MST, hàng, số lượng, đơn giá, thuế suất, tiền:
POST /invoices/{id}/adjusthoặc/replacevới{ invoice: InvoiceRequest, reason, reasonCode, agreementNo, agreementDate }. Điều chỉnh: tăng ghi dương, giảm ghi âm. - Người mua có MST / mã ĐVQHNS: khi sửa sai sót (reasonCode 13, 14) phải có văn bản thỏa thuận (
agreementNo+agreementDate) – thiếu → 422invoice.agreement-required. Đính kèm biên bản:POST /invoices/{id}/attachments(multipart, PDF / ảnh ≤ 5 MB). - Lần sau cùng phương thức: đã điều chỉnh thì các lần sau chỉ điều chỉnh (và ngược lại) – 409
invoice.error-method. Hóa đơn máy tính tiền sai chỉ thay thế (409invoice.pos-replace-only). reasonCode(LDDCTThe): 13 sai sót (mặc định), 14 thay thế hóa đơn máy tính tiền, 4 chiết khấu thương mại, 5 trả lại hàng, 6 trả lại tài sản đăng ký (thay thế), 8 hủy giao dịch thu tiền trước… Lý do ngoài 13 / 14 không chịu ràng buộc phương thức.- Cơ quan thuế yêu cầu rà soát (01/TB-RSĐT) → webhook
invoice.review-requested; trả lời bằng 04/SSnature: "Explain"hoặc điều chỉnh / thay thế. - Hủy: quy định hiện hành không còn thủ tục hủy.
POST /invoices/{id}/cancelchỉ chạy khi đơn vị bật "cho phép hủy" (để thử phần mềm có chức năng hủy), mặc định 409invoice.cancel-not-allowed.
5. Hóa đơn khởi tạo từ máy tính tiền
- Đăng ký hình thức máy tính tiền (tờ khai) → cơ quan thuế (mô phỏng) cấp chuỗi 5 ký tự; ký hiệu loại
M(vd.2C26MAA). POST /pos-invoicesvới{ invoices: [InvoiceRequest…] }(1 – 500). Mỗi hóa đơn trả kết quả riêng; lỗi một hóa đơn không chặn hóa đơn khác.- Mã hóa đơn 23 ký tự
M{mẫu}-{năm}-{5 ký tự}-{11 số}do phần mềm sinh – có ngay, in bill được ngay, không chờ cơ quan thuế. - Dữ liệu chuyển cơ quan thuế cuối ngày (
transferPending = truetới khi chuyển); đơn vị chọn được "ngay" ở Công cụ kiểm thử; gọiPOST /pos-invoices/transferđể chuyển ngay. Mất kết nối vẫn phát hành được, chuyển khi có kết nối.
6. Webhook
- Cấu hình ở trang Webhook của đơn vị: địa chỉ HTTPS + bí mật + sự kiện: invoice.issued, invoice.rejected, invoice.adjusted, invoice.replaced, invoice.cancelled, error-notice.accepted, error-notice.rejected, invoice.review-requested, series.changed.
- POST JSON
{ id, type, at, unitTaxCode, invoiceId, clientRef, status, message }; headerX-SiSuInvoice-Event-Id(giữ nguyên khi giao lại) vàX-SiSuInvoice-Signature: t=<unix>,v1=<hex>= HMAC-SHA256(bí mật, "t.thân"). - Bên nhận trả 2xx trong 10 giây; không thì giao lại sau 30 s × 2^n (tối đa 8 lần). Xử lý lặp phải an toàn (theo
id). GóiSiSuInvoice.ContractscóWebhookSignature.Verify.
7. Mã lỗi
Mọi lỗi trả { code, message, field, retryable, requestId }. Rẽ nhánh theo code; retryable = true → gửi lại cùng clientRef.
| Mã | Ý nghĩa |
|---|---|
auth.invalid-key | Khóa API không đúng. |
auth.key-expired | Khóa API đã hết hạn. |
auth.key-revoked | Khóa API đã bị thu hồi. |
auth.required | Cần đăng nhập: gửi header Authorization: Bearer <token>. |
auth.scope | Khóa API không có quyền cho thao tác này. |
auth.token-expired | Token đã hết hạn – lấy token mới bằng khóa API. |
auth.token-invalid | Token không hợp lệ. |
conflict (tạm) | Xung đột dữ liệu – tải lại rồi thử lại. |
internal (tạm) | Lỗi máy chủ. |
invoice.agreement-required | Người mua là tổ chức / hộ kinh doanh: điều chỉnh, thay thế hóa đơn sai sót phải có văn bản thỏa thuận (agreementNo + agreementDate). |
invoice.cancel-not-allowed | Đơn vị không bật tùy chọn cho phép hủy hóa đơn (quy định hiện hành không còn thủ tục hủy – chỉ để thử phần mềm kết nối). |
invoice.client-ref-conflict | clientRef đã dùng cho một hóa đơn có nội dung khác. |
invoice.date-order | Ngày lập trước ngày của hóa đơn mới nhất đã có số trong ký hiệu. |
invoice.duplicate-number | Trùng số hóa đơn trong ký hiệu. |
invoice.error-method | Hóa đơn đã xử lý sai sót bằng phương thức khác – lần sau phải cùng phương thức. |
invoice.not-found | Không có hóa đơn. |
invoice.pos-replace-only | Hóa đơn khởi tạo từ máy tính tiền có sai sót chỉ xử lý bằng hóa đơn thay thế. |
invoice.sign-deadline | Thời điểm ký khác thời điểm lập: phải ký và gửi cơ quan thuế chậm nhất ngày làm việc tiếp theo kể từ ngày lập. |
invoice.state | Trạng thái hóa đơn không cho phép thao tác này. |
not-found | Không tìm thấy. |
plan.feature | Gói đang dùng không có tính năng này. |
plan.limit | Đã đạt hạn mức của gói đang dùng. |
quota.exceeded | Đơn vị đã hết số lượng hóa đơn của gói / gói đã hết hạn. |
rate-limited (tạm) | Gửi quá nhiều yêu cầu – thử lại sau ít giây. |
series.exists | Ký hiệu đã có. |
series.format | Ký hiệu / mẫu số không đúng cấu trúc. |
series.not-active | Ký hiệu chưa được cơ quan thuế chấp nhận. |
series.not-found | Không có ký hiệu này trong đơn vị. |
series.stopped | Ký hiệu đã ngừng sử dụng. |
series.year | Năm của ký hiệu không khớp năm lập hóa đơn. |
tax.rejected | Cơ quan thuế (mô phỏng) không cấp mã / không tiếp nhận. |
tax.unavailable (tạm) | Không kết nối được cơ quan thuế (mô phỏng) – gửi lại sau. |
unit.locked | Đơn vị phát hành đang bị khóa. |
unit.read-only | Đơn vị phát hành đang ở chế độ chỉ đọc (chưa có bản quyền dùng hợp lệ hoặc đã hết hạn). |
unit.usage-stopped | Cơ quan thuế (mô phỏng) đã ngừng sử dụng hóa đơn điện tử của đơn vị. |
validation.buyer | Thông tin người mua không hợp lệ. |
validation.failed | Dữ liệu không hợp lệ. |
validation.required | Thiếu thông tin bắt buộc. |
validation.tax-rate | Thuế suất không hợp lệ. |
validation.totals | Tổng tiền / tiền thuế không khớp với các dòng. |
8. Kịch bản thử
- Theo đơn vị: trang Công cụ kiểm thử – từ chối, chậm cấp mã, mất kết nối, ký hiệu bị ngừng, hết hạn mức, trùng số; đồng hồ giả lập; chế độ xác định; đặt lại sandbox; nạp dữ liệu mẫu; cơ quan thuế ngừng / tiếp tục sử dụng; yêu cầu rà soát.
- Theo từng yêu cầu (khi đơn vị bật): header
X-SiSuInvoice-Test=reject,reject:lý do,delay:15,offline,series-stopped,quota,duplicate(nhiều giá trị cách dấu phẩy). - Chế độ xác định (CI): cấp mã tức thì, số + mã tra cứu + mã cơ quan thuế cố định theo hạt giống – hai lần chạy giống nhau sau "đặt lại sandbox".
- Mọi thông điệp với cơ quan thuế (100, 102, 103, 108, 114, 200, 202, 203, 204, 206, 216, 300, 301, 302, 303, 400, 401, 999) xem và tải XML ở trang Thông điệp.
9. Quy tắc dữ liệu chính
- Mẫu số 1 chữ số (1 GTGT, 2 bán hàng, 3 tài sản công, 4 dự trữ quốc gia, 5 tem / vé / thẻ, 6 phiếu xuất kho, 7 thương mại điện tử, 8 – 9 tích hợp biên lai);
ký hiệu 6 ký tự:
C/K+ 2 số cuối năm + loại (T, D, L, M, N, B, G, H, X, F) + 2 chữ in hoa (Thông tư 91 Phụ lục I). - Thuế suất:
0%,5%,8%,10%,KCT,KKKNT,KHAC:AB.CD%,KHAC(ghi tiền thuế dòng),CTTC,KTPVDC,KTGTT. Hóa đơn bán hàng (mẫu 2) không ghi thuế suất. - Tính chất dòng (
kind): Goods (1), Promotion (2 – không vào tổng), TradeDiscount (3 – số dương, trừ vào nhóm thuế suất), Note (4), Special (5). - Thuế tính trên tổng thành tiền của từng thuế suất, VND làm tròn đồng; gửi kèm tổng lệch quá 1 đồng →
validation.totals. - Người mua: MST → mã ĐVQHNS (7 số) → số định danh (12 số) → hộ chiếu + quốc tịch; không có gì → "Bán cho người tiêu dùng". Email ≤ 50 ký tự.
- XML theo Quyết định 1233/QĐ-CT phiên bản 2.1.1, chữ ký XAdES (RSA-SHA256) ở
DSCKS/NBan; cơ quan thuế (mô phỏng) ký ởDSCKS/CQT.