{"openapi": "3.1.0", "info": {"title": "API ICD-10 và YHCT Việt Nam", "version": "1.0.0", "summary": "REST API tra cứu mã bệnh ICD-10 và Y học cổ truyền", "description": "Một bộ API read-only thống nhất, cung cấp 15.826 mã ICD-10 và 4.144 mã bệnh Y học cổ truyền theo nguồn Bộ Y tế. Không gửi dữ liệu nhận dạng người bệnh vào API.", "contact": {"name": "8Tech", "url": "https://8tech.vn/"}, "license": {"name": "Dữ liệu tra cứu – yêu cầu ghi nguồn", "url": "https://icd.8tech.vn/nguon-du-lieu/"}}, "servers": [{"url": "https://icd.8tech.vn/api/v1", "description": "Production"}], "security": [], "tags": [{"name": "Codes", "description": "Tìm kiếm, lọc và đọc chi tiết mã ICD-10."}, {"name": "Chapters", "description": "22 chương ICD-10."}, {"name": "Groups", "description": "Các nhóm mã thuộc từng chương."}, {"name": "YHCT", "description": "Danh mục bệnh Y học cổ truyền theo Quyết định 1978/QĐ-BYT."}], "paths": {"/codes/": {"get": {"tags": ["Codes"], "operationId": "listCodes", "summary": "Danh sách và tìm kiếm mã ICD-10", "description": "Tìm theo mã, tên tiếng Việt có dấu hoặc không dấu; có thể kết hợp nhiều bộ lọc.", "parameters": [{"name": "q", "in": "query", "description": "Mã hoặc tên bệnh, tối thiểu 2 ký tự.", "schema": {"type": "string"}, "example": "viem phoi"}, {"name": "chapter", "in": "query", "description": "Mã chương.", "schema": {"type": "string"}, "example": "X"}, {"name": "group", "in": "query", "description": "Mã nhóm.", "schema": {"type": "string"}, "example": "J09-J18"}, {"name": "primary", "in": "query", "description": "Lọc theo chỉ báo bệnh chính.", "schema": {"type": "string", "enum": ["allowed", "recommended", "forbidden"]}}, {"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách mã phân trang", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedCodes"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/codes/{code}/": {"get": {"tags": ["Codes"], "operationId": "retrieveCode", "summary": "Chi tiết một mã ICD-10", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Dữ liệu đầy đủ của mã", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeDetail"}, "example": {"code": "J18.9", "name": "Viêm phổi, không xác định", "api_url": "https://icd.8tech.vn/api/v1/codes/J18.9/", "inclusion": "", "exclusion": "", "coding_guidance": "", "primary_diagnosis": {"allowed": true, "cannot_be_primary": false, "not_recommended_as_primary": false, "requires_more_specific_code": false, "mortality_only": false}}}}}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/chapters/": {"get": {"tags": ["Chapters"], "operationId": "listChapters", "summary": "Danh sách chương", "parameters": [{"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách chương phân trang", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedChapters"}}}}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/chapters/{code}/": {"get": {"tags": ["Chapters"], "operationId": "retrieveChapter", "summary": "Chi tiết chương", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Chi tiết chương, số mã và các nhóm", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ChapterDetail"}}}}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/groups/": {"get": {"tags": ["Groups"], "operationId": "listGroups", "summary": "Danh sách nhóm", "parameters": [{"name": "chapter", "in": "query", "schema": {"type": "string"}, "example": "X"}, {"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách nhóm phân trang", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedGroups"}}}}}}}, "/groups/{code}/": {"get": {"tags": ["Groups"], "operationId": "retrieveGroup", "summary": "Chi tiết nhóm", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Chi tiết nhóm và URL danh sách mã", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GroupDetail"}}}}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/yhct/codes/": {"get": {"tags": ["YHCT"], "operationId": "listYhctCodes", "summary": "Danh sách và tìm kiếm mã bệnh YHCT", "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}, "example": "ban chan"}, {"name": "chapter", "in": "query", "schema": {"type": "string"}, "example": "U50"}, {"name": "category", "in": "query", "schema": {"type": "string"}}, {"name": "icd10", "in": "query", "schema": {"type": "string"}, "example": "A38"}, {"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách mã YHCT phân trang", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedYhctCodes"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}}}}, "/yhct/codes/{code}/": {"get": {"tags": ["YHCT"], "operationId": "retrieveYhctCode", "summary": "Chi tiết mã bệnh YHCT", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Tên YHCT, tên hiện đại và mã ICD-10 đối chiếu", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/YhctCodeDetail"}}}}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/yhct/chapters/": {"get": {"tags": ["YHCT"], "operationId": "listYhctChapters", "summary": "Danh sách 18 chương YHCT", "parameters": [{"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách chương", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedYhctChapters"}}}}}}}, "/yhct/chapters/{code}/": {"get": {"tags": ["YHCT"], "operationId": "retrieveYhctChapter", "summary": "Chi tiết chương YHCT", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Chi tiết chương và nhóm cấp đầu"}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/yhct/categories/": {"get": {"tags": ["YHCT"], "operationId": "listYhctCategories", "summary": "Danh sách nhóm phân loại YHCT", "parameters": [{"name": "chapter", "in": "query", "schema": {"type": "string"}}, {"name": "page", "in": "query", "description": "Số trang, bắt đầu từ 1.", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "description": "Số bản ghi mỗi trang.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}], "responses": {"200": {"description": "Danh sách nhóm", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaginatedYhctCategories"}}}}}}}, "/yhct/categories/{code}/": {"get": {"tags": ["YHCT"], "operationId": "retrieveYhctCategory", "summary": "Chi tiết nhóm YHCT", "parameters": [{"name": "code", "in": "path", "required": true, "description": "Mã ICD-10, ví dụ J18.9.", "schema": {"type": "string"}, "example": "J18.9"}], "responses": {"200": {"description": "Chi tiết nhóm và nhóm con"}, "404": {"$ref": "#/components/responses/NotFound"}}}}}, "components": {"responses": {"BadRequest": {"description": "Tham số không hợp lệ", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "NotFound": {"description": "Không tìm thấy tài nguyên", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"error": {"code": "not_found", "message": "Không tìm thấy mã ICD-10."}}}}}, "RateLimited": {"description": "Vượt giới hạn 120 yêu cầu/phút", "headers": {"Retry-After": {"schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "schemas": {"Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}, "PrimaryDiagnosis": {"type": "object", "properties": {"allowed": {"type": "boolean", "description": "Không có chỉ báo cấm, bắt buộc chi tiết hơn hoặc chỉ dùng cho tử vong."}, "cannot_be_primary": {"type": "boolean"}, "not_recommended_as_primary": {"type": "boolean"}, "requires_more_specific_code": {"type": "boolean"}, "mortality_only": {"type": "boolean"}}}, "SexRestrictions": {"type": "object", "properties": {"female_only_or_mainly": {"type": "boolean"}, "male_only_or_mainly": {"type": "boolean"}}}, "CodeSummary": {"type": "object", "required": ["code", "name", "api_url"], "properties": {"code": {"type": "string", "example": "J18.9"}, "normalized_code": {"type": "string", "example": "J189"}, "name": {"type": "string", "example": "Viêm phổi, không xác định"}, "slug": {"type": "string"}, "version": {"type": "string"}, "is_active": {"type": "boolean"}, "primary_diagnosis": {"$ref": "#/components/schemas/PrimaryDiagnosis"}, "sex_restrictions": {"$ref": "#/components/schemas/SexRestrictions"}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "CodeDetail": {"allOf": [{"$ref": "#/components/schemas/CodeSummary"}, {"type": "object", "properties": {"description": {"type": "string"}, "inclusion": {"type": "string"}, "exclusion": {"type": "string"}, "note": {"type": "string"}, "coding_guidance": {"type": "string"}, "index_terms": {"type": "array", "items": {"type": "string"}}, "group": {"$ref": "#/components/schemas/Group"}, "chapter": {"$ref": "#/components/schemas/Chapter"}, "official_source_synced_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}}}]}, "Chapter": {"type": "object", "properties": {"code": {"type": "string", "example": "X"}, "code_range": {"type": "string", "example": "J00-J99"}, "name": {"type": "string"}, "slug": {"type": "string"}, "order": {"type": "integer"}, "version": {"type": "string"}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "ChapterDetail": {"allOf": [{"$ref": "#/components/schemas/Chapter"}, {"type": "object", "properties": {"code_count": {"type": "integer"}, "groups": {"type": "array", "items": {"$ref": "#/components/schemas/Group"}}}}]}, "Group": {"type": "object", "properties": {"code": {"type": "string", "example": "J09-J18"}, "code_from": {"type": "string"}, "code_to": {"type": "string"}, "name": {"type": "string"}, "slug": {"type": "string"}, "order": {"type": "integer"}, "version": {"type": "string"}, "chapter": {"type": "object"}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "GroupDetail": {"allOf": [{"$ref": "#/components/schemas/Group"}, {"type": "object", "properties": {"code_count": {"type": "integer"}, "codes_url": {"type": "string", "format": "uri"}}}]}, "PaginatedCodes": {"$ref": "#/components/schemas/PaginatedCodeSummary"}, "PaginatedCodeSummary": {"type": "object", "properties": {"count": {"type": "integer"}, "page": {"type": "integer"}, "page_size": {"type": "integer"}, "total_pages": {"type": "integer"}, "next": {"type": ["string", "null"], "format": "uri"}, "previous": {"type": ["string", "null"], "format": "uri"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/CodeSummary"}}}}, "PaginatedChapters": {"type": "object", "properties": {"count": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/Chapter"}}}}, "PaginatedGroups": {"type": "object", "properties": {"count": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/Group"}}}}, "YhctCode": {"type": "object", "properties": {"code": {"type": "string", "example": "U50.452"}, "normalized_code": {"type": "string"}, "name": {"type": "string"}, "traditional_name": {"type": "string", "example": "Ban chẩn"}, "modern_name": {"type": "string", "example": "Bệnh tinh hồng nhiệt"}, "icd10_mappings": {"type": "array", "items": {"type": "string"}, "example": ["A38"]}, "source_version": {"type": "string", "example": "QD1978"}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "YhctCodeDetail": {"allOf": [{"$ref": "#/components/schemas/YhctCode"}, {"type": "object", "properties": {"billing_name": {"type": "string"}, "chapter": {"$ref": "#/components/schemas/YhctChapter"}, "category": {"$ref": "#/components/schemas/YhctCategory"}, "source_synced_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}}}]}, "YhctChapter": {"type": "object", "properties": {"code": {"type": "string", "example": "U50"}, "name": {"type": "string"}, "source_version": {"type": "string"}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "YhctCategory": {"type": "object", "properties": {"code": {"type": "string"}, "name": {"type": "string"}, "level": {"type": "string"}, "chapter": {"type": "object"}, "parent_code": {"type": ["string", "null"]}, "url": {"type": "string", "format": "uri"}, "api_url": {"type": "string", "format": "uri"}}}, "PaginatedYhctCodes": {"type": "object", "properties": {"count": {"type": "integer"}, "page": {"type": "integer"}, "page_size": {"type": "integer"}, "total_pages": {"type": "integer"}, "next": {"type": ["string", "null"], "format": "uri"}, "previous": {"type": ["string", "null"], "format": "uri"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/YhctCode"}}}}, "PaginatedYhctChapters": {"type": "object", "properties": {"count": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/YhctChapter"}}}}, "PaginatedYhctCategories": {"type": "object", "properties": {"count": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/YhctCategory"}}}}}}}