API REST dạng JSON

Tra cứu doanh nghiệp Việt Nam theo MST, lọc theo tỉnh / ngành. Công khai, không cần xác thực, 60 yêu cầu / phút / IP.

Đặc tả OpenAPI 3.1: /api/v1/openapi.json — nhập vào Postman, Insomnia, Stoplight, hoặc Swagger UI để khám phá nhanh.

v1 ổn định: Cấu trúc phản hồi có thể được mở rộng theo hướng cộng-thêm (thêm trường mới, không xoá trường cũ). Khi v2 ra mắt, v1 sẽ chạy song song tối thiểu 6 tháng.

Điểm cuối

GET/api/v1/stats

Tổng số DN, breakdown theo trạng thái, top 10 tỉnh / ngành

Tham số	Type	Bắt buộc	Mô tả

GET/api/v1/industries

Liệt kê 21 ngành VSIC cấp 1 (cho ?industry= filter)

Tham số	Type	Bắt buộc	Mô tả

GET/api/v1/provinces

Liệt kê tỉnh / thành phố (cho ?province=<slug> filter)

Tham số	Type	Bắt buộc	Mô tả

GET/api/v1/search

Tìm kiếm fuzzy theo tên / MST / người đại diện (Meilisearch)

Tham số	Type	Bắt buộc	Mô tả
q	string	có	Từ khoá tìm kiếm. MST 10/13 chữ số sẽ short-circuit sang findUnique.
limit	integer	—	Số kết quả, mặc định 10, tối đa 20.
status	string	—	active \| suspended \| dissolved — narrow result.
is_listed	string	—	true/false hoặc 1/0 — chỉ DN niêm yết.
industry	string	—	VSIC prefix (J → all J*). Same semantics as /companies.
province	string	—	Province slug ('ha-noi') hoặc code ('VN-HN').

GET/api/v1/companies

Liệt kê doanh nghiệp với bộ lọc

Tham số	Type	Bắt buộc	Mô tả
province	string	—	Slug tỉnh / TP, ví dụ: ha-noi
industry	string	—	Mã VSIC (case-insensitive). Prefix roll-up: 'J' khớp tất cả J*, 'J62' khớp J6201/J6202/..., 'J6201' khớp đúng leaf đó. Ví dụ phổ biến: J = Thông tin và truyền thông; K = Tài chính & ngân hàng; F = Xây dựng.
page	integer	—	Trang, 1-based, mặc định 1
page_size	integer	—	Số dòng mỗi trang, mặc định 20, tối đa 100
format	string	—	json (mặc định) hoặc csv. CSV trả file Excel-safe (UTF-8 BOM, RFC-4180 quote escape) với pagination metadata trên header (x-total-count, x-page, x-page-count, x-page-size).
status	string	—	active \| suspended \| dissolved (exact match).
is_listed	string	—	true/false hoặc 1/0 — chỉ DN niêm yết HOSE/HNX/UPCOM.
min_capital_vnd	string	—	Vốn điều lệ tối thiểu (VND, BigInt). Rows null charter_capital_vnd không match.
max_capital_vnd	string	—	Vốn điều lệ tối đa (VND, BigInt).
sort	string	—	freshness (mặc định) \| capital_desc \| capital_asc \| registered_desc \| registered_asc. Mỗi key có tie-breaker id desc.
mst	array	—	Lọc theo danh sách MST. Repeatable (?mst=A&mst=B) hoặc comma-joined (?mst=A,B,C). Tối đa 50 unique / request (dups không tính). Khi set mà không có page_size: default page_size tự bump lên bằng batch size (cap 100) để toàn bộ batch trả 1 page.

GET/api/v1/companies/{mst}

Chi tiết một doanh nghiệp

Tham số	Type	Bắt buộc	Mô tả
mst	string	có	Mã số thuế 10 hoặc 13 chữ số

GET/api/v1/companies/{mst}/events

Lịch sử thay đổi (capital, name, address, status, ...)

Tham số	Type	Bắt buộc	Mô tả
mst	string	có	Mã số thuế 10 hoặc 13 chữ số
page	integer	—	Trang, 1-based, mặc định 1
page_size	integer	—	Số dòng / trang, mặc định 20, tối đa 100
format	string	—	json (mặc định) hoặc csv. CSV mỗi event 1 row, changes flatten thành 'label: before → after · ...'. Pagination headers x-total-count / x-page-count / x-page / x-page-size.

Ví dụ

curl

curl https://doanhnghiep.vn/api/v1/companies/0101248141 \
  -H "Accept: application/json"

curl + filter

curl "https://doanhnghiep.vn/api/v1/companies?\
province=ha-noi&industry=J&page_size=10"

Python (httpx)

import httpx

r = httpx.get(
    "https://doanhnghiep.vn/api/v1/companies/0101248141"
)
r.raise_for_status()
print(r.json()["name_vi"])
# Quota:
# r.headers["x-ratelimit-remaining"]

JavaScript (fetch)

const r = await fetch(
  "https://doanhnghiep.vn/api/v1/companies/0101248141"
);
const dn = await r.json();
console.log(dn.name_vi);
// CORS expose-headers cho phép đọc:
// r.headers.get("x-ratelimit-remaining")

Cấu trúc phản hồi

Tất cả response là JSON. Trường ngày (registered_at, first_trade_date) format YYYY-MM-DD theo Asia/Ho_Chi_Minh. Số lớn (charter_capital_vnd) là chuỗi để an toàn khi round-trip JSON.

GET /api/v1/companies/0101248141

{
  "mst": "0101248141",
  "name_vi": "Công ty Cổ phần FPT",
  "name_en": "FPT Corporation",
  "legal_form": "Cổ phần",
  "registered_at": "1988-09-13",
  "status": "active",
  "charter_capital_vnd": "12500000000000",
  "address_full": "Số 17 phố Duy Tân, ...",
  "legal_rep_name": "Trương Gia Bình",
  "is_listed": true,
  "listed_exchange": "HOSE",
  "listed_ticker": "FPT",
  "province":  { "code": "VN-HN", "name_vi": "Hà Nội", "slug": "ha-noi" },
  "district":  { "name_vi": "Quận Cầu Giấy" },
  "industry":  { "code": "J6201", "name_vi": "Lập trình máy vi tính" }
}

Shape minh hoạ. Item cụ thể tuỳ thuộc bộ data thực tế và thứ tự (orderBy: data_freshness_at desc, id desc). Trường nullable (district, legal_rep_name, ...) trả null khi crawler chưa thu được.

GET /api/v1/companies?province=ha-noi&page_size=1

{
  "page": 1,
  "page_size": 1,
  "total": 43,
  "page_count": 43,
  "filters": { "province": "ha-noi", "industry": null },
  "items": [
    {
      "mst": "0100112437",
      "name_vi": "Ngân hàng TMCP Ngoại thương Việt Nam",
      "legal_form": "Cổ phần",
      "status": "active",
      "charter_capital_vnd": "55891000000000",
      "registered_at": "1963-04-01",
      "is_listed": true,
      "listed_ticker": "VCB",
      "legal_rep_name": null,
      "industry": { "code": "K", "name_vi": "Hoạt động tài chính, ngân hàng và bảo hiểm" },
      "industry_main_code": "K",
      "district": null,
      "district_name": null
    }
  ]
}

Mã lỗi

HTTP	error	Khi nào
200	OK	Yêu cầu thành công.
400	invalid_mst / invalid_filter	Tham số sai định dạng (MST không phải 10/13 chữ số, slug tỉnh không tồn tại, mã ngành không tồn tại).
404	not_found	Không tìm thấy doanh nghiệp với MST này.
429	rate_limited	Quá 60 yêu cầu / phút trên cùng IP. Trường retry_after_seconds chỉ thời gian đợi.
500	server_error	Lỗi nội bộ. Không trả nguyên văn err.message ra ngoài (Codex Day-25–30 P3).

Giới hạn tốc độ

60 yêu cầu / phút / IP. Bucket dùng chung cho hầu hết endpoint /api/v1/*. Ngoại lệ: /api/v1/industries và /api/v1/provinces không bị giới hạn (reference data, public-cached 1h). Header phản hồi: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset (epoch giây). Khi 429, đợi retry_after_seconds trong body.

Cần quota cao hơn? Gói Business (Q3/2026) sẽ mở 10.000 req/tháng. Liên hệ qua /lien-he để vào early-access.

PDPL 2025 + ToS

API chỉ trả dữ liệu công bố theo Luật Doanh nghiệp 2020. Không có thông tin cá nhân (CCCD, số điện thoại, email cá nhân).
Không được dùng để gửi spam, lừa đảo, làm danh sách CCCD, hoặc các mục đích vi phạm PDPL 2025.
Cache kết quả tối đa 24h. Sau đó re-fetch để lấy dữ liệu cập nhật (registered_at có thể thay đổi sau M&A).
Mọi yêu cầu xoá dữ liệu DN: gửi qua /yeu-cau-go-thong-tin.