Giới thiệu

TCONNECT E-Invoice Hub là cổng hóa đơn điện tử (HĐĐT) của TCONNECT giúp nền tảng thương mại (Merchant Platform) tích hợp một lần rồi phát hành hóa đơn qua nhiều nhà cung cấp — thay vì phải tích hợp riêng lẻ với từng đơn vị. Nhờ đó, doanh nghiệp giảm chi phí, rút ngắn thời gian phát triển và chuẩn hóa việc kết nối.

Cùng hệ sinh thái Open API của TCONNECT (chung cơ chế với Open API thanh toán), TCONNECT E-Invoice Hub cung cấp một bộ API chuẩn hóa để phát hành, ký số, tra cứu và quản lý HĐĐT.

Tài liệu này hướng dẫn nhà phát triển kết nối ứng dụng (Client/Backend) tới dịch vụ HĐĐT thông qua TCONNECT E-Invoice Hub.

Dành cho AI/Agent

👉 Tải đặc tả API đầy đủ (single-file cho Vibe code / AI Agent)

Hóa đơn điện tử & các nhà cung cấp

Hóa đơn điện tử là hình thức hóa đơn được khởi tạo, ký số và lưu trữ hoàn toàn điện tử, kết nối trực tiếp Cơ quan Thuế để đảm bảo hợp lệ và minh bạch.

TCONNECT E-Invoice Hub đứng trước và định tuyến tới nhiều nhà cung cấp HĐĐT (provider). Đối tác chỉ tích hợp một lần với TCONNECT là có thể phát hành qua bất kỳ provider nào đã kết nối:

Provider (đối tác)	provider slug	Ghi chú
1Invoice	1Invoice	Nhà cung cấp HĐĐT cho SME
1Invoice (one-invoice)	one-invoice	Kênh kết nối one-invoice
FPT	fpt	FPT.eInvoice
MISA	misa	MISA meInvoice (ký tự động)
Viettel	viettel	Viettel S-Invoice

Merchant chỉ làm việc với TCONNECT; tên nhà cung cấp chỉ xuất hiện ở tham số provider trong đường dẫn endpoint để định tuyến.

Hai mô hình tích hợp

Mô hình	Dành cho	Đặc điểm
A — Web App Client	Web SPA / Merchant Portal	Dùng SDK JS, thao tác qua giao diện (Modal/Form), lưu phiên tại trình duyệt.
B — Server-to-Server	SaaS / POS / ERP / AI Agent / Worker	Tích hợp Backend↔Backend qua REST API, lưu cấu hình tại DB/Vault, tự động 24/7 không phụ thuộc UI.

Bảo mật

Credential/nhà cung cấp không giữ ở trình duyệt. Backend đóng vai trò Security Boundary: mã hóa mật khẩu at-rest (AES-256), cache token phiên ~50 phút theo cặp (MST, user), và không để token nhà cung cấp lọt ra Client UI.

Đường dẫn API

Môi trường	Base URL
Staging	https://stag-invoice-hub.1invoice.vn
Production	https://invoice-hub.1invoice.vn

Lưu ý

Chỉ thực hiện test trên môi trường Staging, không test trên môi trường Production.

Quy ước chung

• Khi gọi API, chỉ định rõ nhà cung cấp qua đường dẫn: <base_url>/<provider>/<endpoint>. Một số API dùng chung gọi trực tiếp <base_url>/core-api/<endpoint> (provider là query param).
• Header bắt buộc: X-Tax-Code: <MST người bán>, Content-Type: application/json, và Authorization: Bearer <token> (trừ sign-in).
• Idempotency: mỗi hóa đơn dùng inv.sid duy nhất (ví dụ {MST}-{mã đơn}). Trùng sid → lỗi 88 (DuplicateInvoiceRefID).
• Quy ước đặt tên field trong request body:
  • a.x: field x của object a
  • a.n[]: field n là một mảng trong object a
  • a.n[].x: field x trong mỗi phần tử của mảng n
  • a[n]: phần tử thứ n+1 của object a
  • a[n].x: field x trong phần tử thứ n+1 của object a

Luồng khách tự xuất hóa đơn qua QR trên bill

Ngoài luồng thu ngân xuất hóa đơn ngay tại quầy, TCONNECT E-Invoice Hub hỗ trợ luồng khách tự khai và tự xuất HĐĐT sau khi rời quán bằng mã QR in trên hóa đơn tính tiền (bill). Backend đóng vai trò proxy an toàn xin URL từ Hub và không được chặn việc in bill tại quầy.

Các bước:

1. Thu ngân đóng đơn hàng (không tick "Xuất HĐĐT" ngay).
2. Backend gọi Hub xin link tự xuất: POST /core-api/customer-invoice-requests/url với header X-Tax-Code: <MST người bán> và body 7 tham số: token, invoiceId (= sid), address, amount, billNo, providerName, taxCode.
3. Hub trả 201 Created { uuid }. Backend dựng URL landing: https://landing.1invoice.vn/xuat-hoa-don?uuid={uuid} và in khối QR xuất hóa đơn trên bill kèm dòng "Thời hạn khai báo: 3 giờ".
4. Khách quét QR trên bill → mở trang landing → tự điền Tên công ty, MST, địa chỉ, email nhận HĐ.
5. Hệ thống phát hành HĐĐT trực tiếp dưới MST của Merchant.

Nguyên tắc non-blocking

Endpoint xin URL luôn trả HTTP 200. Nếu Hub lỗi/timeout, backend ghi log và trả { url: null, error: "<mô tả>" }, POS in bill thường (không có QR) — tuyệt đối không chặn bán hàng. Đơn đã phát hành HĐ trước đó thì in khối tra cứu HĐĐT thay cho khối tự xuất.

Chống trùng

Cả luồng "xuất tại quầy" và "khách tự xuất qua QR" dùng chung một sid ({MST}-{mã đơn}) → Hub đảm bảo idempotency: chỉ tờ hóa đơn tới trước được phát hành, yêu cầu tới sau nhận lỗi 88.