{"openapi":"3.1.0","info":{"title":"masothue.pro REST API","version":"1.0.0","description":"API tra cứu và đối soát dữ liệu đăng ký doanh nghiệp Việt Nam trên nền tảng Cloudflare-native. Toàn bộ endpoint yêu cầu Bearer token xác thực và tuân thủ định dạng RFC 9457 Problem Details.","contact":{"name":"masothue.pro Developer Support","email":"contact@masothue.pro","url":"https://masothue.pro/developers"}},"servers":[{"url":"https://masothue.pro","description":"Production Server"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key định dạng `msp_live_<token>` có được cấp quyền theo các scope cụ thể (company:read, company:search, changes:read, fresh:request)."}},"schemas":{"ProblemDetails":{"type":"object","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"retry_after":{"type":"integer"}}},"CompanyData":{"type":"object","required":["tax_code"],"properties":{"tax_code":{"type":"string","example":"1801724493"},"parent_tax_code":{"type":"string","example":"1801724493"},"branch_suffix":{"type":["string","null"],"example":null},"legal_name":{"type":["string","null"],"example":"CÔNG TY TNHH ĐẦU TƯ CÔNG NGHỆ KDIGI"},"short_name":{"type":["string","null"],"example":"KDIGI"},"status_code":{"type":["string","null"],"example":"00"},"status_label_source":{"type":["string","null"],"example":"NNT đang hoạt động"},"status_group":{"type":["string","null"],"example":"active"},"registered_address":{"type":["string","null"],"example":"Số 1, Phố Duy Tân, Phường Dịch Vọng Hậu, TP Hà Nội"},"representative_name":{"type":["string","null"],"description":"Chỉ xuất hiện khi chính sách công bố contact phía server được bật."},"contact_phone":{"type":["string","null"],"description":"Chỉ xuất hiện khi chính sách công bố contact phía server được bật."},"contact_email":{"type":["string","null"],"description":"Chỉ xuất hiện khi chính sách công bố contact phía server được bật."},"source_checked_at":{"type":"string","example":"2026-09-22T02:00:00.000Z"}}}}},"paths":{"/v1/companies/{tax_code}":{"get":{"tags":["Companies"],"summary":"Tra cứu hồ sơ doanh nghiệp theo mã số thuế","description":"Truy vấn thông tin pháp lý doanh nghiệp. mode=cache tính 1 credit; mode=fresh yêu cầu scope fresh:request, tính 2 credits khi quan sát được, 1 credit khi xác minh không có bản ghi, và 0 credit khi nguồn lỗi.","security":[{"BearerAuth":[]}],"parameters":[{"name":"tax_code","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{10}(-\\d{3})?$"},"description":"Mã số thuế 10 hoặc 13 chữ số có gạch nối","example":"1801724493"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["cache","fresh"],"default":"cache"},"description":"cache tính 1 credit. fresh yêu cầu scope fresh:request; observed=2, absent=1, source failure=0.","example":"cache"}],"responses":{"200":{"description":"Thành công - Trả về dữ liệu doanh nghiệp","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"$ref":"#/components/schemas/CompanyData"},"meta":{"type":"object","required":["request_id","mode","credits_charged","freshness","source_status"],"properties":{"request_id":{"type":"string"},"mode":{"type":"string","enum":["cache","fresh"]},"credits_charged":{"type":"integer"},"freshness":{"type":"string","enum":["fresh","cached","stale"]},"source_status":{"type":"string","enum":["ok","degraded","unavailable"]},"coverage":{"type":"string"}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"},"canonical_web":{"type":"string"}}}}},"example":{"data":{"tax_code":"1801724493","legal_name":"CÔNG TY TNHH ĐẦU TƯ CÔNG NGHỆ KDIGI","short_name":"KDIGI","status_code":"00","status_label_source":"NNT đang hoạt động","registered_address":"Số 1, Phố Duy Tân, Phường Dịch Vọng Hậu, TP Hà Nội","source_checked_at":"2026-09-22T02:00:00.000Z"},"meta":{"request_id":"req_demo_1801724493","mode":"cache","credits_charged":1,"source_checked_at":"2026-09-22T02:00:00.000Z","freshness":"cached","source_status":"ok","coverage":"Dữ liệu đăng ký doanh nghiệp quốc gia đối soát thực tế tại masothue.pro"},"links":{"self":"/v1/companies/1801724493","canonical_web":"https://masothue.pro/1801724493-cong-ty-tnhh-dau-tu-cong-nghe-kdigi"}}}}},"400":{"description":"Mã số thuế không đúng định dạng","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://masothue.pro/docs/errors#invalid_identifier","title":"Mã số thuế không đúng định dạng","status":400,"detail":"Mã số thuế phải gồm 10 chữ số hoặc 13 chữ số có dấu gạch ngang.","code":"invalid_identifier","request_id":"req_err_bad_id"}}}},"401":{"description":"Bearer token không hợp lệ hoặc đã hết hạn","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"402":{"description":"Tài khoản không đủ credit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Token thiếu scope bắt buộc","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Không tìm thấy doanh nghiệp trong dữ liệu (Tính 1 credit theo DEC-028)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://masothue.pro/docs/errors#not_found","title":"Không tìm thấy doanh nghiệp","status":404,"detail":"Không tìm thấy mã số thuế trong tập dữ liệu quốc gia.","code":"not_found","request_id":"req_err_404"}}}},"409":{"description":"Idempotency-Key đang được xử lý","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Idempotency-Key đã được dùng cho tham số khác","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Nguồn, cơ sở dữ liệu hoặc paid mutation tạm thời không khả dụng","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/companies":{"get":{"tags":["Companies"],"summary":"Tìm kiếm và lọc danh sách doanh nghiệp","description":"Tìm kiếm theo từ khoá hoặc lọc theo tỉnh thành, loại hình và năm thành lập (1 credit).","security":[{"BearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Từ khoá tìm kiếm","example":"kdigi"},{"name":"entity_type","in":"query","schema":{"type":"string","enum":["company","branch"]},"example":"company"},{"name":"province","in":"query","schema":{"type":"string"},"example":"Hà Nội"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Con trỏ phân trang","example":"eyJpZCI6IjE4MDE3MjQ0OTMifQ"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"example":20}],"responses":{"200":{"description":"Thành công - Danh sách doanh nghiệp khớp bộ lọc","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyData"}},"meta":{"type":"object"}}},"example":{"data":[{"tax_code":"1801724493","legal_name":"CÔNG TY TNHH ĐẦU TƯ CÔNG NGHỆ KDIGI","status_code":"00","province_name":"Hà Nội"}],"meta":{"total":1,"count":1,"credits_charged":1}}}}},"401":{"description":"Bearer token không hợp lệ hoặc đã hết hạn","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"402":{"description":"Tài khoản không đủ credit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Token thiếu scope bắt buộc","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Nguồn, cơ sở dữ liệu hoặc paid mutation tạm thời không khả dụng","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/company-events":{"get":{"tags":["Events"],"summary":"Lịch sử thay đổi pháp lý doanh nghiệp","description":"Truy vấn các sự kiện thay đổi material đã được kiểm chứng (1 credit).","security":[{"BearerAuth":[]}],"parameters":[{"name":"tax_code","in":"query","schema":{"type":"string"},"example":"1801724493"}],"responses":{"200":{"description":"Thành công - Danh sách sự kiện thay đổi","content":{"application/json":{"example":{"data":[{"event_id":"ev_1","tax_code":"1801724493","field_id":"status_code","old_value":"00","new_value":"03","change_kind":"material"}],"meta":{"count":1,"credits_charged":1}}}}},"401":{"description":"Bearer token không hợp lệ hoặc đã hết hạn","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"402":{"description":"Tài khoản không đủ credit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Token thiếu scope bắt buộc","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Nguồn, cơ sở dữ liệu hoặc paid mutation tạm thời không khả dụng","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/company-stats":{"get":{"tags":["Analytics"],"summary":"Thống kê tổng hợp doanh nghiệp từ khối dữ liệu (Cube)","description":"Truy vấn số liệu thống kê phân bố doanh nghiệp theo tỉnh thành, trạng thái và năm thành lập (2 credits).","security":[{"BearerAuth":[]}],"parameters":[{"name":"province","in":"query","required":true,"schema":{"type":"string"},"description":"Tên tỉnh hoặc thành phố trực thuộc trung ương","example":"Hà Nội"},{"name":"status_bucket","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive","unknown"]},"example":"active"},{"name":"founded_year","in":"query","required":false,"schema":{"type":"integer"},"example":2020},{"name":"industry","in":"query","required":false,"schema":{"type":"string"},"example":"6201"}],"responses":{"200":{"description":"Thành công - Dữ liệu thống kê kèm 4 trường metadata","content":{"application/json":{"example":{"data":{"province":"Hà Nội","included_count":1250,"unknown_count":5,"data_as_of":"2026-09-23","definition_version":"2026.09.25-1","status_bucket":"active","founded_year":2020},"meta":{"credits_charged":2,"mode":"aggregate_cube"}}}}},"401":{"description":"Bearer token không hợp lệ hoặc đã hết hạn","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"402":{"description":"Tài khoản không đủ credit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Token thiếu scope bắt buộc","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Không thể xử lý - Chưa có khối số liệu (cube) cho tổ hợp yêu cầu","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://masothue.pro/docs/errors#unprocessable_entity","title":"Chưa có số liệu tổng hợp","status":422,"detail":"Chưa có khối dữ liệu tổng hợp cho tổ hợp tiêu chí yêu cầu."}}}},"503":{"description":"Nguồn, cơ sở dữ liệu hoặc paid mutation tạm thời không khả dụng","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/usage":{"get":{"tags":["Account"],"summary":"Kiểm tra số dư và hạn mức tài khoản","description":"Tra cứu số dư credit khả dụng, phân cấp Data Explorer và các gói cước đang hoạt động (Miễn phí 0 credit).","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Thành công - Thông tin tài khoản và số dư","content":{"application/json":{"example":{"data":{"account_id":"acc_example","available_credits":4500,"total_initial_credits":5000,"total_credits_used":500,"tier":"pro","has_explorer_entitlement":true},"meta":{"credits_charged":0,"mode":"account_status"}}}}}}}}}}