{"openapi":"3.0.3","info":{"title":"Casso Open Platform: API tra cứu mã số thuế (IDKit)","version":"1.0.0","description":"Tra cứu mã số thuế doanh nghiệp, chi nhánh, ngành nghề (VSIC) và hộ kinh doanh Việt Nam qua Casso Open Platform.\n\nGọi 2 bước: (1) POST /oauth/token đổi app_id + app_secret lấy JWT (sống khoảng 15 phút, hãy cache), (2) gọi API với header Authorization: Bearer <JWT>.\n\nKEY TRIAL CÔNG KHAI, chỉ chạy sandbox, giới hạn rate, không phải secret: app_id=trial-app_3c1e7aa6dabfbc3b9e51517e app_secret=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI\n\nTài liệu: https://www.vietqr.io/tra-cuu-mst · Gói miễn phí: 1.000 lượt/tháng (cá nhân đã xác thực), 5.000 lượt/tháng (doanh nghiệp đã xác thực).","contact":{"name":"Casso Open Platform","url":"https://open.casso.vn"}},"servers":[{"url":"https://openapi.casso.vn","description":"Production"}],"tags":[{"name":"Auth"},{"name":"IDKit"}],"paths":{"/oauth/token":{"post":{"tags":["Auth"],"operationId":"createToken","summary":"Đổi app_id + app_secret lấy JWT","description":"Giới hạn 30 request/phút/IP. Cache JWT đến gần thời điểm hết hạn.\n\nKEY TRIAL CÔNG KHAI, chỉ chạy sandbox, giới hạn rate, không phải secret: app_id=trial-app_3c1e7aa6dabfbc3b9e51517e app_secret=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"},"examples":{"trial":{"summary":"Key trial công khai","value":{"app_id":"trial-app_3c1e7aa6dabfbc3b9e51517e","app_secret":"sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI"}}}}}},"responses":{"200":{"description":"JWT RS256","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"JWT thiếu hoặc hết hạn, gọi lại /oauth/token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ hoặc hết quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/idkit/v1/business/{taxCode}":{"get":{"tags":["IDKit"],"operationId":"getBusiness","summary":"Tra cứu doanh nghiệp theo mã số thuế","description":"Tên, địa chỉ, cơ quan thuế quản lý, trạng thái hoạt động. Scope: idkit:business:read.","parameters":[{"name":"taxCode","in":"path","required":true,"description":"Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).","schema":{"type":"string","pattern":"^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"},"example":"0316794479"}],"responses":{"200":{"description":"Thông tin doanh nghiệp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessResponse"},"example":{"requestId":"pEkrC2C-ZzzgMFBQ","business":{"taxCode":"0316794479","taxDepartment":"Sở Kế hoạch và Đầu tư TPHCM","name":"CÔNG TY TNHH CASSO","address":"I.102D, Nhà A, Khu CNC Phần mềm, ĐHQG TP.HCM","status":"NNT đang hoạt động","source":"state-registry"}}}}},"400":{"description":"MST sai định dạng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"JWT thiếu hoặc hết hạn, gọi lại /oauth/token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"App chưa được cấp scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không tìm thấy mã số thuế","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ hoặc hết quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Nguồn dữ liệu tạm thời không phản hồi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/idkit/v1/business/{taxCode}/industries":{"get":{"tags":["IDKit"],"operationId":"getBusinessIndustries","summary":"Ngành nghề kinh doanh (VSIC) của doanh nghiệp","description":"Scope: idkit:business:read.","parameters":[{"name":"taxCode","in":"path","required":true,"description":"Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).","schema":{"type":"string","pattern":"^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"},"example":"0316794479"}],"responses":{"200":{"description":"Danh sách mã ngành","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndustriesResponse"},"example":{"requestId":"pEkrC2C-ZzzgMFBQ","businessIndustries":{"taxCode":"0316794479","name":"CÔNG TY TNHH CASSO","primaryIndustryCode":"6201","primaryIndustryName":"Lập trình máy vi tính","industries":[{"code":"6201","name":"Lập trình máy vi tính","detail":""}]}}}}},"400":{"description":"MST sai định dạng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"JWT thiếu hoặc hết hạn, gọi lại /oauth/token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"App chưa được cấp scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không tìm thấy mã số thuế","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ hoặc hết quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Nguồn dữ liệu tạm thời không phản hồi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/idkit/v1/household/{taxCode}":{"get":{"tags":["IDKit"],"operationId":"getHousehold","summary":"Tra cứu hộ kinh doanh theo mã số thuế 12 số","description":"Scope: idkit:household:read.","parameters":[{"name":"taxCode","in":"path","required":true,"description":"Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).","schema":{"type":"string","pattern":"^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"},"example":"080066008592"}],"responses":{"200":{"description":"Thông tin hộ kinh doanh","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"MST sai định dạng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"JWT thiếu hoặc hết hạn, gọi lại /oauth/token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"App chưa được cấp scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không tìm thấy mã số thuế","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ hoặc hết quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Nguồn dữ liệu tạm thời không phản hồi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TokenRequest":{"type":"object","required":["app_id","app_secret"],"properties":{"app_id":{"type":"string"},"app_secret":{"type":"string"}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":900}}},"Business":{"type":"object","properties":{"taxCode":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"taxDepartment":{"type":"string"},"status":{"type":"string"},"source":{"type":"string"}}},"BusinessResponse":{"type":"object","properties":{"requestId":{"type":"string"},"business":{"$ref":"#/components/schemas/Business"}}},"IndustriesResponse":{"type":"object","properties":{"requestId":{"type":"string"},"businessIndustries":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"security":[{"bearerAuth":[]}]}