# HS Knowledge Base

> Kho tri thức mở về mã HS, thuế nhập khẩu và pháp lý xuất nhập khẩu Việt Nam.
> 11.871 mã HS · chú giải nhóm phủ 100% · 1.045 mã có tiền lệ TB-TCHQ · 108 văn bản pháp
> luật · API tra cứu mở, không cần token.

Dự án cộng đồng, mã nguồn MIT và dữ liệu CC BY-SA 4.0. Dùng lại được cho cả mục
đích thương mại và huấn luyện AI, miễn ghi nguồn và chia sẻ ngược bản phái sinh.

## Quan trọng khi dùng dữ liệu này

- **Đừng đoán mã HS từ trí nhớ** — hãy gọi API hoặc đọc dữ liệu ở đây.
- **25,7% mã trong biểu thuế có tên đúng bằng ba chữ "Loại khác"** (3.050/11.871;
  28,5% có chứa cụm đó). Tên dòng đó không mang thông tin nào về hàng — nghĩa
  thật nằm ở `breadcrumb.scopeVi` và `breadcrumb.excludesVi` mà `/api/search` và
  `/api/tax` trả kèm. Đọc mỗi `nameVi` rồi kết luận là đọc thiếu.
- **Khi kết quả có `avoidedCodes` hoặc `clarifyingQuestionsVi`, hãy nói lại cho
  người dùng.** `avoidedCodes` là các mã hệ thống đã CỐ Ý loại vì chúng là bẫy
  nhầm lẫn đã biết (kèm lý do); `clarifyingQuestionsVi` là dữ kiện còn thiếu để
  chốt mã. Nuốt hai trường này đi là biến một câu trả lời thận trọng thành một
  câu trả lời tự tin mà sai.
- **Tên gọi chỉ đưa tới nhóm 4 số; lá 8 số do thuộc tính quyết định.** `/api/search`
  và `/api/suggest` trả `decisions[]`: với nhóm đã có bảng quyết định, `status`
  RESOLVED kèm `hsCode`, `ruleId`, `reasonVi`, `source`; hoặc INSUFFICIENT kèm
  `missingFacts[]` — đúng thuộc tính còn thiếu và `questionVi` để hỏi người dùng.
  Hỏi xong thì gọi lại với `facts` (`?facts={"thicknessMm":2}` hoặc body
  `facts`). `basis: RULE_TABLE` chỉ khi bảng đã được kiểm chứng; HEURISTIC thì
  trình bày như một gợi ý có căn cứ, không phải kết luận.
- **`vatReduction.eligible === false` nghĩa là KHÔNG được giảm VAT** theo
  NĐ 174/2025/NĐ-CP — 1.561 mã thuộc phụ lục loại trừ (sắt thép cán nóng, một số
  hoá chất). Khai 8% cho nhóm này là bị truy thu cộng phạt chậm nộp. Quy ước
  trường `taxVat` dạng "A/B": A là mức ĐANG áp dụng, B là mức còn lại.
- **Luôn kèm ngày dữ liệu** (`generatedAt` trong mỗi tệp). Luật XNK đổi liên tục;
  dữ liệu không có ngày là dữ liệu không kiểm chứng được.
- **Độ chính xác thật** (đo trên 57 tờ khai, phủ 50 chương): đúng chương 73,7% ·
  đúng nhóm 4 số 64,9% · đúng 6 số 40,4% · **đúng đủ 8 số 24,6%**. Hệ thống định
  hướng tốt tới chương/nhóm, hai số cuối phải để người có chuyên môn chốt.
- **Mỗi trích dẫn quy tắc GIR đều có trường `basis`**: `RULE_TABLE` và
  `DETERMINISTIC` là căn cứ chắc, dùng được cho hồ sơ giải trình; `HEURISTIC` và
  `LLM_ASSERTED` phải kiểm chứng lại. Hãy truyền mức này cho người dùng.
- **Đây là tài liệu tham khảo nghiệp vụ**, không phải phán quyết phân loại của cơ
  quan Hải quan và không phải tư vấn pháp lý.

## API — không cần token

- [Đặc tả OpenAPI 3.1](https://hs-kb.uythacnhapkhau.com/openapi.json): toàn bộ endpoint, tham số, mức phân quyền
- [Tra thuế theo mã HS](https://hs-kb.uythacnhapkhau.com/api/tax?hs=84137090): thuế NK/ACFTA/VAT + cảnh báo chính sách + link văn bản
- [Tìm mã theo từ khoá](https://hs-kb.uythacnhapkhau.com/api/search?q=máy%20bơm): tra nhanh không cần AI. Hiểu được cả tên hàng theo cách người đi khai gọi — thử [`tấm thép làm khuôn nhựa`](https://hs-kb.uythacnhapkhau.com/api/search?q=t%E1%BA%A5m%20th%C3%A9p%20l%C3%A0m%20khu%C3%B4n%20nh%E1%BB%B1a) hoặc [`quạt điều hòa hơi nước`](https://hs-kb.uythacnhapkhau.com/api/search?q=qu%E1%BA%A1t%20%C4%91i%E1%BB%81u%20h%C3%B2a%20h%C6%A1i%20n%C6%B0%E1%BB%9Bc)
- [Chú giải chương](https://hs-kb.uythacnhapkhau.com/api/notes?chapter=84): căn cứ áp dụng GIR 1
- [Tiền lệ phân loại TB-TCHQ](https://hs-kb.uythacnhapkhau.com/api/precedents?hs=84137090): cách Hải quan đã từng phân loại
- [Cảnh báo mã dễ nhầm](https://hs-kb.uythacnhapkhau.com/api/conflicts?hs=84137090): cụm mã hay bị áp sai
- [Thư viện văn bản pháp luật](https://hs-kb.uythacnhapkhau.com/api/legal-docs): 108 văn bản, 106 đã verify tiêu đề thật
- [Thủ tục kiểm tra chuyên ngành](https://hs-kb.uythacnhapkhau.com/api/policy-procedures): hồ sơ cần chuẩn bị theo từng loại chính sách
- [Mã loại hình XNK](https://hs-kb.uythacnhapkhau.com/api/customs-types): theo QĐ 1357/QĐ-TCHQ
- [Corpus sản phẩm mã "Loại khác"](https://hs-kb.uythacnhapkhau.com/api/products?hs=84137090): tên sản phẩm ví dụ giúp hiểu phạm vi mã residual
- [Tổng quan số liệu + benchmark](https://hs-kb.uythacnhapkhau.com/community-data.json): thống kê kho dữ liệu và độ chính xác đo được

## Ba lớp bắc cầu giữa lời văn biểu thuế và tiếng người đi khai

Biểu thuế đặt tên hàng theo lời văn pháp lý; người khai gọi hàng theo cách khác.
`/api/search` bắc cầu bằng ba lớp, mỗi lớp có mức căn cứ khác nhau — **hãy truyền
mức đó cho người dùng, đừng gộp chung**:

1. **`precedent`** — cụm từ này đã được khai bao nhiêu lần trong tờ khai đã thông
   quan, kèm `share` (mức tập trung về một mã). Đây là bằng chứng thực tế, không
   phải văn bản. `share` thấp nghĩa là chính dữ liệu cũng không thống nhất.
2. **`tradeTerm`** — mục từ điển tên thương mại do người soạn, có `sourceVi` dẫn
   nguyên văn biểu thuế. **Luôn đọc `appliesWhenVi` trước khi dùng**: một tên
   thương mại thường ứng với nhiều mã, phân biệt nhau bằng khổ rộng, dạng gia
   công hoặc thành phần. `confidence: "low"` là bảng tự thừa nhận chưa chắc —
   khi đó `askVi` mới là việc cần làm, không phải chốt mã.
3. **`breadcrumb`** — vị trí trong biểu thuế, và với mã dư thì `scopeVi` là phạm
   vi thật, `excludesVi` là các mã anh em bị loại trừ.

Ba lớp có thể mâu thuẫn nhau, và **đó là thông tin, không phải lỗi**. Ví dụ thật:
với `biến tần`, bảng soạn tay đề xuất `85044090` nhưng 6/6 tờ khai thực tế lại
khai `85044040`, nên mã đó xếp trên. Hãy trình bày cả hai căn cứ cho người dùng
tự quyết, thay vì chọn hộ rồi giấu cái còn lại.

## API AI — không cần token, không giới hạn lượt

Gọi POST thẳng, **không cần header Authorization**. Nhóm này gọi mô hình ngôn ngữ nên mỗi lượt tốn chi phí:
hãy gọi có chủ đích (một lượt cho mỗi mặt hàng, không lặp thăm dò).

- `POST /api/suggest` — body `{"description": "máy bơm nước ly tâm 1.5HP"}`: gợi ý mã HS kèm audit trail GIR có căn cứ
- `POST /api/describe` — body `{"hsCode": "84137090", "productName": "máy bơm nước"}`: sinh mô tả khai báo Hải quan chuẩn TT 39/2018, tối đa 200 ký tự ECUS
- `POST /api/classify` — body `{"tenHang": "máy bơm nước ly tâm"}`: phân loại có cây quyết định + bảng phân giải cụm mã dễ nhầm
- `POST /api/search?mode=match`: đối sánh sản phẩm theo từ khoá (không dùng để chọn mã)

Đọc `status` + `nextAction` trong kết quả TRƯỚC khi dùng bất kỳ mã nào.

## API — cần Bearer token

Chỉ nhóm quản trị và ghi dữ liệu (feedback, cập nhật biểu thuế, dashboard). Người dùng ngoài không cần nhóm này.

## Hướng dẫn cho AI

- [AGENTS.md](https://github.com/ozvietnam/hs-code-api/blob/main/AGENTS.md): quy trình 6 bước xác định mã HS đúng phương pháp, cách đọc `basis`, và các ranh giới không được vượt
- [NOTICE.md](https://github.com/ozvietnam/hs-code-api/blob/main/NOTICE.md): giấy phép, nguồn dữ liệu gốc, cách ghi công
- [Hướng dẫn tích hợp](https://github.com/ozvietnam/hs-code-api/blob/main/docs/integration-guide.md): hợp đồng dữ liệu chi tiết cho ERP

## Bản sao trên GitHub — dùng khi domain không truy cập được

Toàn bộ dữ liệu nằm công khai trên GitHub, **không qua Cloudflare và không có
hạn chế crawler nào**. Nếu bạn là AI agent bị chặn ở `hs-kb.uythacnhapkhau.com`,
hãy đọc thẳng từ đây — nội dung giống hệt, cùng một nguồn:

- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/AGENTS.md` — hướng dẫn phương pháp
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/public/openapi.json` — đặc tả API
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/public/community-data.json` — số liệu + benchmark
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/data/tax.json` — 11.871 mã HS, thuế NK/ACFTA/VAT (5,4 MB)
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/data/notes.json` — chú giải chương
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/data/precedents.json` — tiền lệ TB-TCHQ
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/data/conflicts.json` — cụm mã dễ nhầm
- `https://raw.githubusercontent.com/ozvietnam/hs-code-api/main/data/legal-docs.json` — thư viện văn bản

**Dùng `raw.githubusercontent.com`, đừng dùng CDN cho dữ liệu thuế.** Bản raw
cache 5 phút nên gần như luôn mới. Bản trên `cdn.jsdelivr.net/gh/...@main` cache
tới 7 ngày — nhanh hơn nhưng có thể trả biểu thuế cũ, mà thuế sai thì hậu quả
thuộc về người khai. Chỉ dùng jsDelivr khi tải cả kho về dùng offline, và khi đó
hãy ghim theo tag phiên bản thay vì `@main`.

Khác biệt duy nhất so với API: bản GitHub là **tệp thô**, không có phần suy luận
(`/api/tax` còn trả kèm cảnh báo chính sách đã phân tích, mã anh em cùng phân
nhóm, và link văn bản). Tra một mã thì gọi API tiện hơn; nạp cả kho thì lấy ở đây.

## Dữ liệu tải thẳng

- [Kho mã nguồn + toàn bộ dữ liệu](https://github.com/ozvietnam/hs-code-api): clone về là có `data/tax.json` (11.871 mã), chú giải, tiền lệ, bảng quyết định

## Đóng góp

Dự án cần dữ liệu cộng đồng để mã HS ngày càng rõ ràng cho mọi người: tờ khai đã
thông quan (cặp mô tả ↔ mã HS, **không kèm thông tin khách hàng**), thông báo
TB-TCHQ mới, cụm mã hay nhầm kèm cách phân biệt, hoặc báo lỗi sai trong dữ liệu.

- [Mở Issue đóng góp](https://github.com/ozvietnam/hs-code-api/issues)