E-Invoice setup — phát hành hóa đơn điện tử

Hóa đơn điện tử (e-invoice) là pháp lý artifact gửi cho bộ thuế để tuân thủ luật Việt Nam. DentIQ tích hợp với 4 nhà cung cấp chính để phát hành tự động.

Luồng e-invoice: preview hóa đơn → phát hành → provider phê duyệt → lưu PDF/XML → gửi BN

Nhà cung cấp e-invoice được hỗ trợ

Nhà cung cấp	Phí/hoá đơn (khoảng)	Setup time	Ghi chú
VNPT_INVOICE	~350 ₫	2–3 ngày	Phổ biến, ổn định
MISA_MEINVOICE	~350 ₫	1–2 ngày	Tích hợp hệ Misa tốt
VIETTEL_SINVOICE	~400 ₫	3–5 ngày	Tín hiệu Viettel, duyệt lâu
FAKE_EINVOICE	—	Tức thì	Sandbox / training / demo; không phát hành pháp lý

Quan trọng (CI-07)

E-invoice là pháp lý artifact chỉ — không bao giờ mutate (đổi) payment, cash, doanh số (revenue), hoặc doctor earnings. Phát hành, hủy, hay điều chỉnh e-invoice không làm payment tăng/giảm, không tạo tiền mặt, không tính lương. Nó là "giấy tờ pháp lý gắn vào payment" mà thôi.

VAT trên hóa đơn điện tử

Kể từ khi DentIQ hỗ trợ giá đã bao gồm thuế (inclusive VAT), hóa đơn điện tử hiển thị ba dòng tách biệt:

Dòng trên hóa đơn	Ý nghĩa	Ví dụ (giá niêm yết 2.000.000 ₫, VAT 5%)
Doanh thu thuần (net)	Giá chưa thuế = giá niêm yết ÷ (1 + thuế suất)	1.904.762 ₫
Thuế GTGT (VAT)	Phần thuế tách ra từ giá đã gồm thuế	95.238 ₫
Tổng thanh toán	= Giá niêm yết đã gồm thuế (số bệnh nhân trả thực tế)	2.000.000 ₫

Lưu ý quan trọng về cách cộng

Tổng = giá niêm yết đã gồm thuế — không cộng thêm VAT một lần nữa. Ví dụ: dịch vụ niêm yết 2.000.000 ₫ đã gồm VAT 5% → hóa đơn ghi "Tổng = 2.000.000 ₫", không phải 2.000.000 + 95.238. Dịch vụ y tế (KCT — miễn thuế) không có dòng VAT.

Bước 1: Cấu hình nhà cung cấp

Vào Settings

Chủ phòng khám → Thiết lập (Settings) → "E-Invoice" (hoặc "Hóa đơn điện tử").

Chọn nhà cung cấp

Nhấn "Chọn nhà cung cấp" → dropdown chọn VNPT_INVOICE / MISA_MEINVOICE / VIETTEL_SINVOICE (FAKE_EINVOICE chỉ ở môi trường non-production).
Mỗi nhà cung cấp có form input credential khác nhau (ví dụ: username, password, secret key, app ID).
Nhập đầy đủ theo form.

Chọn môi trường

Sandbox — test trước, không gửi bộ thuế. Dùng để kiểm tra format.
Production — sử dụng thực, gửi bộ thuế. Cần confirm "Tôi xác nhận đây là môi trường thực tế".

Test kết nối

Nhấn "Test kết nối" → DentIQ sẽ gửi test request tới provider. Nếu thành công → proceed, nếu fail → fix credential.

Bước 2: Cấu hình seller info

Thông tin người bán (phòng khám) xuất hiện trên mỗi hóa đơn:

Tên phòng khám, địa chỉ, điện thoại.
Mã số thuế (MST).
Email liên hệ.

Nếu có nhiều chi nhánh, có thể override thông tin per branch (tên chi nhánh, MST chi nhánh, email chi nhánh).

Bước 3: Phát hành hóa đơn

Preview-first workflow

DentIQ sử dụng preview-first — không auto-issue:

Kế toán mở Payment detail → nhấn "Xem trước hóa đơn" (cần quyền `einvoice.manage`).
Drawer mở: thông tin mua hàng (tên BN, MST, email, địa chỉ) có thể edit.
DentIQ render PROFORMA PDF nội bộ (bản xem trước, có watermark "BẢN XEM TRƯỚC" — không gửi provider).
Bạn xem PDF, kiểm tra tên/địa chỉ/số tiền.

Phát hành chính thức

Nếu đúng → nhấn "Phát hành hóa đơn".
Confirm dialog: cảnh báo "Phát hành với provider XXX. Hành động này không thể hoàn tác."
Confirm → hệ thống gửi request tới provider (qua worker background job).
Provider phê duyệt → hóa đơn nhận số (ví dụ: 01234567890), status = ISSUED.
PDF + XML tự động lưu trữ trong DentIQ (S3).
BN nhận link / PDF qua Zalo/email (nếu cấu hình).

Ảnh minh hoạ

Preview drawer: edit buyer info, show PROFORMA PDF, issue button

Trạng thái e-invoice

Trạng thái	Ý nghĩa	Hành động tiếp
DRAFT	Bản nháp, chưa phát hành	Xem trước, edit, phát hành
READY_TO_ISSUE	Sẵn sàng, chờ worker xử lý	Chờ hệ thống phát (auto)
ISSUING	Đang gửi provider (quá trình)	Chờ kết quả
ISSUED	Phát hành thành công, có số HĐ	Download PDF/XML, gửi BN
FAILED	Provider reject hoặc lỗi kết nối	Thử lại hoặc hủy + tạo mới
CANCELED	Đã hủy (nếu phát hiện sai)	Tạo hóa đơn mới nếu cần

Khi phát hành thất bại

Nếu provider lỗi (mạng, credential, format):

Status = FAILED, có error message từ provider.
DentIQ tự động retry (5 giây, 15 giây, 60 giây; max 3 lần).
Kế toán có thể nhấn "Thử lại ngay" để bỏ qua backoff timer.
Nếu fail 3 lần → chặn, phải hủy + tạo mới.

Điều chỉnh / Thay thế hóa đơn

Nếu phát hiện sai sau khi issue:

Sai tên / MST / địa chỉ BN → "Thay thế" (REPLACE): tạo hóa đơn mới, hóa đơn cũ mark REPLACED.
Sai tiền → "Điều chỉnh" (ADJUST): tạo hóa đơn chênh lệch (âm/dương), hóa đơn gốc mark ADJUSTED.
Cách làm: mở e-invoice detail → click "Thay thế" hoặc "Điều chỉnh" → lập hóa đơn mới → phát hành.

Hủy payment khi e-invoice issued

Nếu BN muốn hoàn tiền nhưng hóa đơn đã issued:

Hệ thống chặn: "Hóa đơn đã phát hành. Vui lòng xử lý e-invoice trước."
Kế toán vào e-invoice detail → chọn "Thay thế" / "Điều chỉnh" hoặc "Hủy hóa đơn".
Sau đó mới được hủy payment.

Quyền và cấp truy cập

Vai trò	Quyền cần	Có thể làm
Kế toán	`einvoice.manage` + `einvoice.read`	Preview, phát hành, hủy, download PDF
Quản lý phòng khám	`einvoice.manage`	Cấu hình provider, cấu hình seller info
Lễ tân	`einvoice.read`	Xem hóa đơn, download PDF (đọc)

Branch override & legal numbering

Nếu có nhiều chi nhánh:

Provider có thể setup per-branch (credential, seller info).
Mỗi chi nhánh có dãy số hóa đơn riêng (legal requirement Việt Nam).
KHÔNG dùng DocumentNumberingType (của DentIQ) cho e-invoice — e-invoice có numbering system riêng từ provider.

Công khai & mã tra cứu

BN nhận:

Link PDF hóa đơn (qua Zalo/email).
Mã tra cứu công khai trên website bộ thuế (tuỳ provider hỗ trợ).
Không lộ chi tiết nhạy cảm (khám gì, chẩn đoán gì) — chỉ show tên dịch vụ và giá.