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.

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ỉ khi người mua là cá nhân lẻ (không có mã số thuế) — 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 tên/địa chỉ người mua khi người mua không có mã số thuế
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 },
  "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ỉ
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.

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, không được actor lưu trữ lại cho mục đích khác.

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