# Vietnam E-Invoice XML Normalizer (`donerightlabs/vn-einvoice-xml-normalizer`) Actor

Chuẩn hoá file XML hoá đơn điện tử VAT Việt Nam (Viettel, VNPT, MISA, BKAV, Softdream, Thái Sơn...) về 1 định dạng JSON thống nhất, sẵn sàng cho AI Agent làm sổ sách.

- **URL**: https://apify.com/donerightlabs/vn-einvoice-xml-normalizer.md
- **Developed by:** [donerightlabs](https://apify.com/donerightlabs) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 invoice processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### 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](https://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

```json
{
  "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.

# Actor input Schema

## `invoices` (type: `array`):

Mỗi mục là 1 hoá đơn điện tử VN dạng file XML gốc (không phải PDF/ảnh) mà bạn đã tự có sẵn. Đưa nội dung XML trực tiếp (xmlContent) hoặc link tải file XML (xmlUrl).

## `hideBuyerPersonalInfo` (type: `boolean`):

Khi bật (mặc định), nếu người mua trên hoá đơn không có mã số thuế (dấu hiệu là cá nhân, không phải doanh nghiệp), trường tên và địa chỉ người mua sẽ bị ẩn khỏi kết quả để bảo vệ thông tin cá nhân. Tắt đi nếu bạn cần đầy đủ thông tin này cho mục đích sổ sách của chính bạn.

## `includeRawData` (type: `boolean`):

Kèm thêm toàn bộ các trường đọc được trực tiếp từ file XML gốc (chưa chuẩn hoá tên) vào kết quả, để bạn tự đối chiếu/kiểm tra. Nên giữ bật cho tới khi đã xác nhận kết quả chuẩn hoá đúng với hoá đơn thật của nhà cung cấp bạn dùng.

## Actor input object example

```json
{
  "invoices": [],
  "hideBuyerPersonalInfo": true,
  "includeRawData": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "invoices": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("donerightlabs/vn-einvoice-xml-normalizer").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "invoices": [] }

# Run the Actor and wait for it to finish
run = client.actor("donerightlabs/vn-einvoice-xml-normalizer").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "invoices": []
}' |
apify call donerightlabs/vn-einvoice-xml-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,donerightlabs/vn-einvoice-xml-normalizer"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4WcuFRzNesZ1b5Hdj/builds/Wsv2AMjek8TCuWtXq/openapi.json