Vietnam E-Invoice XML Normalizer

Quick summary (English)

Normalizes Vietnamese VAT e-invoice XML files (the legally mandated data format under Decree 123/2020/NĐ-CP and Circular 78/2021/TT-BTC — issued by any provider: Viettel, VNPT, MISA, BKAV, Softdream, Thái Sơn...) into one unified JSON schema, ready for bookkeeping AI Agents.

Input: invoices (array, required) — each item has xmlContent (raw XML text) or xmlUrl (link to an XML file), plus optional sourceLabel. hideBuyerPersonalInfo (boolean, default true) — hides the buyer's name/address when the buyer has no tax code (a sign the buyer is an individual, not a business). includeRawData (boolean, default true) — also returns every raw tag/value pair found in the file, for cross-checking against the normalized fields.

This Actor does not scrape the web and does not look up anyone else's invoice. It only reads XML files you already legally possess.

Data responsibility: invoices may contain the buyer's personal data. You are responsible for having a lawful basis under Vietnam's Personal Data Protection Law (91/2025/QH15). The Actor runs on Apify infrastructure outside Vietnam; inputs and outputs stay in your own Apify account. donerightlabs does not access your runs unless you share them. Best suited to business-to-business invoices; remove individual buyers' details before sending if you do not need them.

Pricing: see the Pricing tab on this page.

Full documentation below is in Vietnamese (the target user base for this Actor). The Input/Output schema tabs on this page are language-neutral and machine-readable.

---

Vietnam E-Invoice XML Normalizer làm gì?

Đọc file XML hoá đơn điện tử VAT Việt Nam — định dạng dữ liệu gốc, có giá trị pháp lý, bắt buộc theo Nghị định 123/2020/NĐ-CP và Thông tư 78/2021/TT-BTC — từ bất kỳ nhà cung cấp hoá đơn điện tử nào (Viettel, VNPT, MISA, BKAV, Softdream, Thái Sơn...), và chuẩn hoá về 1 định dạng JSON thống nhất: thông tin chung, người bán, người mua, danh sách hàng hoá/dịch vụ, tổng thanh toán.

File PDF/ảnh hoá đơn chỉ là bản trình bày để đọc bằng mắt — file XML mới là dữ liệu gốc, đọc trực tiếp từ XML luôn chính xác 100% (không đoán chữ như OCR).

Vì sao nên dùng?

• Tự động hoá sổ sách: đưa thẳng hoá đơn từ nhiều nhà cung cấp khác nhau vào 1 AI Agent kế toán duy nhất, không cần biết mỗi nhà cung cấp đóng gói XML khác nhau ra sao.
• Không cần phần mềm kế toán trọn gói: phù hợp cho ai cần lấy dữ liệu hoá đơn qua API/AI Agent mà không muốn/không thể mua cả bộ phần mềm kế toán đóng.
• An toàn dữ liệu cá nhân: Actor chỉ xử lý file bạn đã tự sở hữu hợp pháp, không tra cứu hộ hoá đơn của người khác. Mặc định tự ẩn tên/địa chỉ (cả trong dữ liệu thô) khi người mua là cá nhân lẻ — không có mã số thuế, mã số thuế là số định danh cá nhân 12 số, hoặc hoá đơn có số CCCD/hộ chiếu — có thể tắt nếu bạn cần đầy đủ cho sổ sách của chính mình.
• Chạy trên Apify: gọi qua API, lên lịch chạy định kỳ, hoặc gọi trực tiếp qua MCP từ AI Agent.

Cách sử dụng

1. Chuẩn bị file XML hoá đơn điện tử bạn đã có sẵn (không phải PDF/ảnh) — thường được nhà cung cấp gửi kèm qua email, hoặc tải trực tiếp từ trang tra cứu chính thức hoadondientu.gdt.gov.vn.
2. Mở tab Input, thêm từng hoá đơn vào mục invoices — dán nội dung XML vào xmlContent hoặc dán link tải file vào xmlUrl.
3. Chọn có muốn ẩn thông tin cá nhân người mua lẻ hay không (mặc định: ẩn).
4. Bấm Start — kết quả JSON đã chuẩn hoá xuất hiện trong tab Dataset sau vài giây.
5. Tải kết quả dạng JSON/CSV/Excel, hoặc gọi Actor trực tiếp qua API/MCP để AI Agent tự lấy dữ liệu ngay khi cần.

Input

Trường	Kiểu	Mô tả
invoices	array (bắt buộc)	Danh sách hoá đơn cần xử lý, mỗi mục có xmlContent hoặc xmlUrl, và sourceLabel tuỳ chọn để tự đặt nhãn
hideBuyerPersonalInfo	boolean (mặc định true)	Ẩn thông tin người mua khi là cá nhân lẻ: không có mã số thuế, MST là số định danh cá nhân 12 số, hoặc có số CCCD/hộ chiếu
includeRawData	boolean (mặc định true)	Kèm toàn bộ trường đọc thô từ file gốc để tự đối chiếu

Output

{
  "trang_thai_phan_tich": "day_du",
  "thong_tin_chung": {
    "so_hoa_don": "1234",
    "ky_hieu_hoa_don": "C25TAA",
    "ngay_lap": "2026-09-05",
    "don_vi_tien_te": "VND"
  },
  "nguoi_ban": { "ten": "...", "mst": "...", "dia_chi": "..." },
  "nguoi_mua": { "ten": null, "mst": null, "dia_chi": null, "da_an_thong_tin_ca_nhan": true, "ly_do_an": "khong_co_mst" },
  "danh_sach_hang_hoa": [
    { "ten_hang_hoa_dich_vu": "...", "so_luong": "1", "don_gia": "1000000", "thanh_tien_truoc_thue": "1000000", "thue_suat": "10%" }
  ],
  "tong_thanh_toan": { "tong_tien_chua_thue": "1000000", "tong_tien_thue": "100000", "tong_tien_thanh_toan_so": "1100000" }
}

Bạn có thể tải dataset dưới nhiều định dạng như JSON, HTML, CSV hoặc Excel.

Bảng trường dữ liệu

Trường	Ý nghĩa
trang_thai_phan_tich	day_du (đọc đủ mọi khối chuẩn), thieu_mot_so_truong (thiếu 1 vài khối, xem canh_bao), khong_nhan_dien_duoc_cau_truc, hoặc loi
canh_bao	Danh sách cảnh báo cụ thể khi có khối dữ liệu không đọc được
thong_tin_chung	Số hoá đơn, ký hiệu, ngày lập, đơn vị tiền tệ...
nguoi_ban / nguoi_mua	Tên, mã số thuế, địa chỉ. Với nguoi_mua: da_an_thong_tin_ca_nhan cho biết đã ẩn thông tin cá nhân hay chưa, ly_do_an là lý do (khong_co_mst, mst_la_so_dinh_danh_ca_nhan, co_so_dinh_danh_ca_nhan)
danh_sach_hang_hoa	Từng dòng hàng hoá/dịch vụ: tên, đơn vị tính, số lượng, đơn giá, thành tiền, thuế suất
tong_thanh_toan	Tổng tiền trước thuế, tiền thuế, tổng thanh toán
du_lieu_tho	(khi bật includeRawData) toàn bộ trường gốc đọc trực tiếp từ XML, chưa chuẩn hoá tên

Chi phí

Xem tab Pricing trên trang này để biết chi phí hiện tại.

Trách nhiệm dữ liệu & dữ liệu cá nhân

• File hoá đơn có thể chứa thông tin cá nhân của người mua (họ tên, địa chỉ, số điện thoại, email, số CCCD/hộ chiếu). Bạn là bên quyết định việc xử lý dữ liệu này và cần có căn cứ hợp pháp theo Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15 trước khi gửi vào Actor.
• Actor chạy trên hạ tầng của Apify, đặt ngoài Việt Nam. Dữ liệu bạn gửi và kết quả được lưu trong tài khoản Apify của chính bạn, theo thời hạn lưu trữ của gói Apify bạn dùng. Nếu việc gửi dữ liệu ra nước ngoài của bạn cần thủ tục theo pháp luật, bạn cần hoàn tất trước khi dùng.
• donerightlabs không truy cập dữ liệu các lượt chạy của bạn, trừ khi bạn chủ động chia sẻ (bật chia sẻ dữ liệu với nhà phát triển, hoặc gửi link lượt chạy khi báo lỗi). Khi báo lỗi, vui lòng dùng file mẫu đã xoá thông tin người mua.
• Khuyến nghị: Actor phù hợp nhất cho hoá đơn mua bán giữa doanh nghiệp. Nếu bạn không cần thông tin người mua là cá nhân, hãy xoá các thông tin đó khỏi file trước khi gửi, và giữ tuỳ chọn hideBuyerPersonalInfo ở mặc định (bật).
• Không dùng Actor để xử lý hoá đơn mà bạn không có quyền sở hữu hoặc quyền xử lý hợp pháp.

Câu hỏi thường gặp

Actor có tự tra cứu hoá đơn giúp tôi không? Không. Bạn phải tự có sẵn file XML — Actor chỉ đọc và chuẩn hoá, không truy cập bất kỳ hệ thống tra cứu nào của nhà cung cấp hay cơ quan thuế.

Vì sao đôi khi thấy trang_thai_phan_tich khác day_du? Cấu trúc XML giữa các phiên bản/nhà cung cấp có thể khác nhau đôi chút. Khi Actor không tìm thấy đúng khối dữ liệu chuẩn, nó vẫn trả về toàn bộ dữ liệu đọc được kèm cảnh báo cụ thể (du_lieu_tho khi bật includeRawData) thay vì báo lỗi im lặng — bạn luôn nhìn thấy Actor đã đọc được gì.

Dữ liệu của tôi có được lưu lại không? File bạn gửi vào chỉ được xử lý trong phạm vi lượt chạy; Actor không lưu ở đâu khác ngoài kho dữ liệu của lượt chạy trong chính tài khoản Apify của bạn (xem mục "Trách nhiệm dữ liệu & dữ liệu cá nhân" ở trên).

Có câu hỏi hoặc gặp hoá đơn không đọc đúng? Vào tab Issues để báo lại.