API & Tích Hợp Dữ Liệu Máy Đọc
Hướng dẫn truy xuất dữ liệu BOP Data cho ứng dụng, bot và hệ thống AI. Dữ liệu được phân phối qua HTML ngữ nghĩa chuẩn kèm Schema.org Dataset microdata — truy cập công khai, không cần API key, không giới hạn tần suất cứng.
BOP Data hiện đang vận hành theo kiến trúc Static Site Generation (SSG). Dữ liệu công dân được phân phối qua HTML ngữ nghĩa chuẩn mực và thuộc tính máy đọc trên từng Data Page.Không yêu cầu API key, không cần tài khoản, và không có endpoint REST runtime giả mạo.
1. Ma trận Năng lực Kỹ thuật (Capability Matrix)
Trạng thái thực tế của từng kênh truy cập dữ liệu trong hệ thống BOP Data:
| Kênh / Giao diện | Trạng thái | Định tuyến / Tài nguyên | Mô tả & Khả năng sử dụng |
|---|---|---|---|
| Trang dữ liệu (HTML) | Khả dụng | /[category]/[subcategory]/[slug]/ | Trang tĩnh SSG có đầy đủ Answer Zone, bảng dữ liệu ngữ nghĩa và Schema.org Dataset microdata. |
| Danh mục Dữ liệu | Khả dụng | /catalog | Danh bạ cấu trúc công khai dẫn chiếu toàn bộ 5 tập dữ liệu chính thức. |
| Lược đồ Cấu trúc | Khả dụng | /schemas | Đặc tả định dạng trường dữ liệu, kiểu dữ liệu và thuộc tính bắt buộc của từng schemaId. |
| Nhúng tiện ích (Embed) | Khả dụng | /[category]/[subcategory]/[slug]/?embed=true | Giao diện nhúng tối giản thông qua tham số query ?embed=true trên bất kỳ Data Page nào. |
| Tài liệu Tích hợp API | Khả dụng | /api | Tài liệu chuẩn hóa mô hình dữ liệu máy đọc; REST API endpoint truy vấn tự động đang trong lộ trình phát triển. |
| Bản ghi JSON tĩnh | Lộ trình | /api#json | Tệp JSON tải trực tiếp cho từng Data Page đang được chuẩn bị; hiện tại dữ liệu cấu trúc sẵn sàng qua HTML Schema.org. |
| Bảng tính CSV | Lộ trình | /api#csv | Tệp xuất dữ liệu bảng CSV đang được biên tập; dữ liệu bảng hiện tại được phân phối qua thẻ table HTML chuẩn. |
| Model Context Protocol (MCP) | Lộ trình | /mcp | Máy chủ MCP chưa được triển khai; AI agent hiện tại tích hợp qua Catalog, Schemas và HTML Data Pages. |
2. Mô hình Cấu trúc Dữ liệu Chuẩn (Canonical Data Model)
Mỗi bản ghi trong BOP Data tuân theo hợp đồng dữ liệu chuẩn hóa độc lập với URL và phân loại. Dưới đây là cấu trúc đối tượng thực tế của tập dữ liệu Biểu thuế GTGT Việt Nam 2026:
# Truy xuất tài nguyên HTML chứa siêu dữ liệu máy đọc
curl -s -H "Accept: text/html" https://data.bop.ink/thue/thue-gtgt/thue-gtgt-viet-nam-2026/{
"canonicalId": "vn.tax.vat.rates",
"category": "thue-phi",
"subcategory": "thue-gtgt-thue-tieu-dung",
"slug": "thue-gtgt-viet-nam-2026",
"title": {
"vi": "Biểu thuế giá trị gia tăng (GTGT) Việt Nam 2026",
"en": "Vietnam VAT Rates 2026"
},
"summary": {
"vi": "Tra cứu biểu thuế suất GTGT 0%, 5%, 10% áp dụng năm 2026",
"en": "VAT tax rates 0%, 5%, 10% for 2026"
},
"geography": "VN",
"jurisdiction": {
"vi": "Toàn quốc",
"en": "National"
},
"schemaId": "schema.vn.tax.vat.rates",
"schemaVersion": "1.0.0",
"currentVersion": "2026.01",
"lifecycleState": "current",
"effectiveDate": "2026-01-01",
"sources": [
{
"id": "src-vat-2026",
"publisher": "Tổng cục Thuế (Bộ Tài chính) / Quốc hội Việt Nam",
"documentNumber": "142/2025/QH15",
"sourceDate": "2025-06-25",
"canonicalUrl": "https://vanban.chinhphu.vn/",
"license": "Open Public Domain"
}
],
"body": {
"renderer": "rate-table",
"highlights": [
{
"label": {
"vi": "Thuế suất chuẩn",
"en": "Standard Rate"
},
"value": "10%"
},
{
"label": {
"vi": "Thuế suất ưu đãi",
"en": "Reduced Rate"
},
"value": "5%"
}
],
"records": [
{
"item": "Hàng hoá thông thường",
"rate": "10%"
},
{
"item": "Nước sạch, thuốc y tế",
"rate": "5%"
},
{
"item": "Hàng hoá xuất khẩu",
"rate": "0%"
}
]
},
"license": "Open Public Domain",
"lastUpdated": "2026-01-01"
}Ví dụ ngữ nghĩa thứ hai: Thang điểm IELTS (intl.education.ielts.scoring)
Chứng minh tính nhất quán của mô hình trên các họ dữ liệu khác nhau (dải điểm / quy chuẩn):
{
"canonicalId": "intl.education.ielts.scoring",
"category": "giao-duc",
"subcategory": "khao-thi-ngoai-ngu-chung-chi-quoc-te",
"schemaId": "schema.intl.education.ielts.scoring",
"schemaVersion": "1.0.0",
"currentVersion": "2026.01",
"body": {
"renderer": "scale-table",
"scale": "0.0 - 9.0",
"bands": [
{
"band": "9.0",
"description": "Expert user"
},
{
"band": "8.0",
"description": "Very good user"
},
{
"band": "7.0",
"description": "Good user"
}
]
}
}3. Hướng dẫn Khởi đầu Nhanh (Quick Start)
Tra cứu Danh mục (Catalog)
Truy cập /catalog để lấy danh sách toàn bộ 5 dataset chính thức kèm canonicalId, lược đồ và trạng thái vòng đời hiện hành.
Đọc Đặc tả Lược đồ (Schemas)
Truy cập /schemas để kiểm tra các trường bắt buộc, kiểu dữ liệu và ý nghĩa nghiệp vụ trước khi tích hợp vào hệ thống máy.
Trích xuất & Xác minh
Trích xuất dữ liệu từ Data Page HTML kèm Schema.org Dataset microdata, hoặc sử dụng tham số nhúng?embed=true để hiển thị Answer Zone độc lập.
4. Xác thực & Giới hạn Truy cập (Auth & Limits)
Không yêu cầu xác thực. Mọi dữ liệu công dân trên BOP Data đều được công khai miễn phí. Không có hệ thống API Key, Bearer Token hay OAuth.
Hạ tầng hiện tại phục vụ qua mạng phân phối tĩnh (CDN). Đề nghị các bot và crawler tuân thủ lịch sự với tần suất hợp lý, tránh gửi yêu cầu đồng thời vượt quá ngưỡng phục vụ thông thường.
Khám phá danh bạ tập dữ liệu, định nghĩa lược đồ chi tiết hoặc tài liệu dành cho AI Agent: