OpenAPI 3.1v1 ổn định

Cổng phát triển masothue.pro

Dữ liệu pháp lý doanh nghiệp Việt Nam cho lập trình viên và AI agent, qua REST API chuẩn OpenAPI 3.1 và Model Context Protocol (MCP).

API Reference Sandbox (0 credit)

Bắt đầu nhanh

Mọi request gửi kèm header Authorization: Bearer <api_key>.

# Tra cứu thông tin doanh nghiệp theo mã số thuế
curl "https://masothue.pro/v1/companies/1801724493?mode=cache" \
  -H "Authorization: Bearer msp_live_YOUR_API_KEY"

Tải openapi.json Kết nối qua MCP

Xác thực & phân quyền

API key có dạng msp_live_…, tạo trong bảng điều khiển. Mỗi key chỉ mang các scope được cấp:

company:readTra cứu hồ sơ doanh nghiệp theo mã số thuế.
company:searchTìm kiếm và lọc danh sách doanh nghiệp.
changes:readĐọc sự kiện thay đổi pháp lý.
analytics:readSố liệu tổng hợp theo địa bàn.
fresh:requestCho phép mode=fresh gọi trực tiếp nguồn quốc gia.

Chi phí credit

Số credit trừ theo loại yêu cầu
Loại yêu cầu	Credit
Tra cứu dữ liệu đã lưu (mode=cache)	1
Làm mới từ nguồn (mode=fresh)	2
Nguồn xác nhận không có hồ sơ (404)	1
Ngân sách nguồn cạn, trả dữ liệu đã lưu (degraded)	1
Tìm kiếm / sự kiện thay đổi	1
Số liệu tổng hợp (company-stats)	2
Lỗi hệ thống, nguồn không phản hồi, lỗi xác thực/validate	0

Quota headers

X-Credit-Remaining — số dư credit khả dụng sau yêu cầu (phản hồi 2xx).
X-RateLimit-Limit — 120 yêu cầu/phút cho mỗi tài khoản.
Retry-After — số giây chờ khi nhận 429; yêu cầu bị chặn không trừ credit.

Định dạng lỗi

Mọi lỗi trả về RFC 9457 Problem Details. Hãy rẽ nhánh theo code, không theo title. Ví dụ: invalid_credentials, insufficient_scope, insufficient_credits, rate_limited, not_found, source_unavailable.

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "type": "https://masothue.pro/docs/errors#insufficient_credits",
  "title": "Không đủ credit",
  "status": 402,
  "code": "insufficient_credits",
  "request_id": "req_…",
  "retryable": false
}

Nguồn gốc dữ liệu & giới hạn pháp lý

Dữ liệu được đối soát từ Cổng thông tin quốc gia về đăng ký doanh nghiệp; mỗi bản ghi mang thời điểm kiểm tra source_checked_at độc lập. Thông tin phản ánh trạng thái ghi nhận tại thời điểm truy vấn; masothue.pro không đưa ra kết luận pháp lý thay cho cơ quan nhà nước có thẩm quyền.