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

  1. Đă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).
  2. 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).
  3. Đổ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/token vớ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 → 401 auth.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 → 403 auth.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ácGọ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ốiPUT /invoices/{id}
Phát hành nháp / gửi lại hóa đơn bị từ chốiPOST /invoices/{id}/issue
Xóa nhápDELETE /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 đổiGET /invoices/{id}/xml|pdf|converted
Gửi người muaPOST /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 → 409 invoice.client-ref-conflict. An toàn để thử lại khi mất kết nối.
  • Trạng thái: Draft → Sent → Issued (hoặc Rejected); về sau Adjusted / Replaced / Cancelled. "Chậm cấp mã" → ở Sent tới khi cơ quan thuế (mô phỏng) trả kết quả – theo dõi bằng webhook hoặc GET /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 (409 invoice.sign-deadline).
  • Hóa đơn có mã: taxAuthorityCode 34 ký tự; không mã (ký hiệu K…): Issued khi 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-notices vớ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}/adjust hoặc /replace vớ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 → 422 invoice.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ế (409 invoice.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/SS nature: "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}/cancel chỉ 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 409 invoice.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-invoices vớ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 = true tới khi chuyển); đơn vị chọn được "ngay" ở Công cụ kiểm thử; gọi POST /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 }; header X-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ói SiSuInvoice.Contracts có 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-keyKhóa API không đúng.
auth.key-expiredKhóa API đã hết hạn.
auth.key-revokedKhóa API đã bị thu hồi.
auth.requiredCần đăng nhập: gửi header Authorization: Bearer <token>.
auth.scopeKhóa API không có quyền cho thao tác này.
auth.token-expiredToken đã hết hạn – lấy token mới bằng khóa API.
auth.token-invalidToken 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-requiredNgườ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-conflictclientRef đã dùng cho một hóa đơn có nội dung khác.
invoice.date-orderNgày lập trước ngày của hóa đơn mới nhất đã có số trong ký hiệu.
invoice.duplicate-numberTrùng số hóa đơn trong ký hiệu.
invoice.error-methodHó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-foundKhông có hóa đơn.
invoice.pos-replace-onlyHó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-deadlineThờ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.stateTrạng thái hóa đơn không cho phép thao tác này.
not-foundKhông tìm thấy.
plan.featureGó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.existsKý hiệu đã có.
series.formatKý hiệu / mẫu số không đúng cấu trúc.
series.not-activeKý hiệu chưa được cơ quan thuế chấp nhận.
series.not-foundKhông có ký hiệu này trong đơn vị.
series.stoppedKý hiệu đã ngừng sử dụng.
series.yearNăm của ký hiệu không khớp năm lập hóa đơn.
tax.rejectedCơ 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-stoppedCơ quan thuế (mô phỏng) đã ngừng sử dụng hóa đơn điện tử của đơn vị.
validation.buyerThông tin người mua không hợp lệ.
validation.failedDữ liệu không hợp lệ.
validation.requiredThiếu thông tin bắt buộc.
validation.tax-rateThuế suất không hợp lệ.
validation.totalsTổ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.
Đã có lỗi không mong muốn. Tải lại 🗙