{"openapi":"3.1.0","info":{"title":"Tính thuế hộ kinh doanh và tài chính cá nhân","version":"0.2.0","description":"API công khai, không cần khoá. Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế. Cùng 4 hàm này cũng có qua MCP tại /mcp; 2 hàm tra cứu font tiếng Việt có qua MCP tại /font/mcp."},"servers":[{"url":"/"}],"paths":{"/api/thue/tinh-thue-hkd":{"post":{"summary":"Tính thuế GTGT và TNCN của hộ kinh doanh","description":"Ước lượng thuế một năm. Tiền là đồng. Kết quả kèm can_cu và chua_xac_minh.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinhThueYeuCau"},"example":{"nganh":[{"nhom":"san_xuat_van_tai_an_uong","doanh_thu":1800000000}],"chi_phi":null,"nam":2026}}}},"responses":{"200":{"description":"Kết quả tính","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinhThueKetQua"},"example":{"gtgt":54000000,"tncn":{"cach_1":12000000,"cach_2":null,"chon":"cach_1","ly_do":"Chưa có chi phí nên dùng cách 1 (theo % doanh thu).","truoc_giam":12000000,"sau_giam":8400000},"giam_30":{"ap_dung":true,"so_tien":3600000},"tong":62400000,"tong_kinh_doanh":62400000,"cho_thue_bds":null,"nhom_ho":2,"can_cu":["Nghị định 141/2026/NĐ-CP, Điều 1, khoản 1 (sửa Nghị định 68/2026/NĐ-CP); Luật 09/2026/QH16","Luật 48/2024/QH15, Điều 12, khoản 2, điểm b","Luật 109/2025/QH15, Điều 7, khoản 3","Nghị định 68/2026/NĐ-CP, Điều 4, khoản 3","Nghị định 68/2026/NĐ-CP, Điều 4, khoản 5","Nghị định 398/2026/NĐ-CP","Nghị định 141/2026/NĐ-CP, Điều 1, khoản 2 (sửa Điều 8, khoản 5 Nghị định 68/2026/NĐ-CP)"],"chua_xac_minh":[],"canh_bao":["Doanh thu trên 1 tỷ cần dùng hóa đơn điện tử (Nghị định 141/2026/NĐ-CP, Điều 1, khoản 2 (sửa Điều 8, khoản 5 Nghị định 68/2026/NĐ-CP))."],"ngay_du_lieu":"2026-11-19","luu_y":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/thue/nguong":{"get":{"summary":"Tra nhóm hộ và nghĩa vụ theo doanh thu cả năm","parameters":[{"name":"doanh_thu","in":"query","required":true,"example":2000000000,"schema":{"type":"integer","minimum":0},"description":"Doanh thu cả năm (đồng)."},{"name":"nam","in":"query","required":false,"schema":{"type":"integer","default":2026}}],"responses":{"200":{"description":"Kết quả tra","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NguongKetQua"},"example":{"nhom_ho":2,"mo_ta":"Nhóm 2: trên 1 đến 3 tỷ","mien_thue":false,"phuong_phap":"Được chọn: theo % doanh thu (cách 1) hoặc theo lợi nhuận (cách 2)","hoa_don_dien_tu":"bat_buoc","giam_30":true,"can_cu":["Nghị định 141/2026/NĐ-CP, Điều 1, khoản 1 (sửa Nghị định 68/2026/NĐ-CP); Luật 09/2026/QH16","Nghị định 68/2026/NĐ-CP, Điều 4, khoản 5","Nghị định 141/2026/NĐ-CP, Điều 1, khoản 2 (sửa Điều 8, khoản 5 Nghị định 68/2026/NĐ-CP)","Nghị định 398/2026/NĐ-CP"],"ngay_du_lieu":"2026-11-19","luu_y":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/thue/lai-tiet-kiem":{"post":{"summary":"Tính lãi tiết kiệm (lãi đơn)","description":"Lãi suất do người gọi truyền vào, tính theo %/năm.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaiYeuCau"},"example":{"so_tien":100000000,"lai_suat_nam_pct":5.5,"ky_han_thang":12}}}},"responses":{"200":{"description":"Kết quả tính","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaiKetQua"},"example":{"tien_lai":5500000,"tong_nhan":105500000,"lai_moi_thang":null,"luu_y":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/thue/tra-gop":{"post":{"summary":"Lập lịch trả góp","description":"Lãi suất do người gọi truyền vào, tính theo %/năm.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraGopYeuCau"},"example":{"so_tien":30000000,"lai_suat_nam_pct":12,"so_thang":3}}}},"responses":{"200":{"description":"Kết quả tính","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraGopKetQua"},"example":{"lich":[{"ky":1,"goc":10000000,"lai":300000,"tong":10300000,"con_lai":20000000},{"ky":2,"goc":10000000,"lai":200000,"tong":10200000,"con_lai":10000000},{"ky":3,"goc":10000000,"lai":100000,"tong":10100000,"con_lai":0}],"tong_lai":600000,"tong_tra":30600000,"luu_y":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/thue/suc-khoe":{"get":{"summary":"Kiểm tra dịch vụ còn sống","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SucKhoe"},"example":{"ok":true,"phien_ban":"0.2.0","ngay_du_lieu":"2026-11-19"}}}}}}},"/api/font/kiem-tra":{"get":{"summary":"Kiểm tra một font có đủ dấu tiếng Việt không","description":"Dựa trên kiểm thực tế 134 ký tự. Font chưa có trong dữ liệu trả ket_luan chua_kiem.","parameters":[{"name":"ten","in":"query","required":true,"description":"Tên font.","schema":{"type":"string"},"example":"Be Vietnam Pro"}],"responses":{"200":{"description":"Kết luận: dung_tot, dung_duoc, co_dieu_kien, cam, ten_gia hoặc chua_kiem","content":{"application/json":{"schema":{"type":"object"},"example":{"tim_thay":true,"ten":"Be Vietnam Pro","hang":"A","diem_dau_viet":100,"ket_luan":"dung_tot","dung_cho":"Mặc định mọi thứ tiếng Việt: slide, báo cáo, landing, UI. 9 độ đậm.","loai_giay_phep":"mo","ghi_chu":"","thay_the_goi_y":[],"quy_tac":["Line-height tối thiểu 1.35 cho tiêu đề, 1.4 cho thân bài (dấu chồng như Ẫ, Ộ, Ử cần chỗ).","Không tự ghép dấu bằng cách chồng dấu lên chữ cái; font thiếu dấu thì đổi font.","Font hạng C: web dùng được với line-height >= 1.4, tránh Word/PowerPoint (dấu chồng bị cắt)."],"luu_y":"Kết quả từ kiểm thực tế 134 ký tự; font thương mại cần bản quyền riêng; dịch vụ không phân phối file font."}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/font/goi-y":{"get":{"summary":"Gợi ý font tiếng Việt theo vai trò hoặc tình huống","parameters":[{"name":"vai_tro","in":"query","required":false,"description":"tieu_de, than_bai, so, serif, display, script hoặc mono.","schema":{"type":"string","enum":["tieu_de","than_bai","so","serif","display","script","mono"]}},{"name":"tinh_huong","in":"query","required":false,"description":"Mô tả ngắn, ví dụ: thiệp mời, slide, dashboard.","schema":{"type":"string"},"example":"thiệp mời"},{"name":"chi_giay_phep_mo","in":"query","required":false,"description":"Mặc định true: chỉ font giấy phép mở.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Danh sách font (hạng A trước B) và cặp font nếu khớp tình huống","content":{"application/json":{"schema":{"type":"object"},"example":{"quy_tac":["Line-height tối thiểu 1.35 cho tiêu đề, 1.4 cho thân bài (dấu chồng như Ẫ, Ộ, Ử cần chỗ).","Không tự ghép dấu bằng cách chồng dấu lên chữ cái; font thiếu dấu thì đổi font.","Font hạng C: web dùng được với line-height >= 1.4, tránh Word/PowerPoint (dấu chồng bị cắt)."],"luu_y":"Kết quả từ kiểm thực tế 134 ký tự; font thương mại cần bản quyền riêng; dịch vụ không phân phối file font.","cap_font":{"tinh_huong":"Thiệp / thư mời / sự kiện","tieu_de":"Playfair Display 700","than_bai":"Lora 400","so":"Cormorant Garamond 600","co_chu":"tiêu đề 32-48pt · thân 12-14pt","line_height":1.5,"luu_y":"Chữ ký/lời chúc: Dancing Script hoặc Charm (chỉ 1-2 dòng)."},"font":[{"ten":"Charm","hang":"B","diem_dau_viet":100,"dung_cho":"Chữ viết tay, thiệp.","loai_giay_phep":"mo","do_dam":[400]},{"ten":"Charmonman","hang":"B","diem_dau_viet":100,"dung_cho":"Chữ viết tay.","loai_giay_phep":"mo","do_dam":[400]},{"ten":"Dancing Script","hang":"B","diem_dau_viet":100,"dung_cho":"Chữ viết tay, chữ ký.","loai_giay_phep":"mo","do_dam":[400]},{"ten":"Pacifico","hang":"B","diem_dau_viet":100,"dung_cho":"Chữ viết tay đậm, ads vui.","loai_giay_phep":"mo","do_dam":[400]}]}}}},"400":{"description":"Đầu vào sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Loi"},"example":{"loi":"Doanh thu không được âm."}}}}}}},"/api/font/suc-khoe":{"get":{"summary":"Kiểm tra dịch vụ font còn sống","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true}}}}}}}},"components":{"schemas":{"Loi":{"type":"object","required":["loi"],"properties":{"loi":{"type":"string"}}},"DongNganh":{"type":"object","required":["nhom","doanh_thu"],"properties":{"nhom":{"type":"string","enum":["hang_hoa","dich_vu","san_xuat_van_tai_an_uong","cho_thue_tai_san_khac","dai_ly_bh_xs_dacap","noi_dung_so","khac","cho_thue_bat_dong_san"],"description":"Nhóm ngành nghề."},"doanh_thu":{"type":"integer","description":"Doanh thu cả năm của nhóm này, đơn vị đồng.","minimum":0}}},"TinhThueYeuCau":{"type":"object","required":["nganh"],"properties":{"nganh":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DongNganh"}},"chi_phi":{"type":["integer","null"],"minimum":0,"description":"Chi phí cả năm (đồng) để tính theo lợi nhuận; trên 3 tỷ là bắt buộc."},"nam":{"type":"integer","description":"Năm tính thuế.","default":2026}}},"TinhThueKetQua":{"type":"object","properties":{"gtgt":{"type":["integer","null"],"description":"GTGT (đồng); null nếu chưa xác minh."},"tncn":{"type":"object","description":"cach_1, cach_2, chon, ly_do, truoc_giam, sau_giam."},"giam_30":{"type":"object","description":"ap_dung (bool), so_tien (đồng)."},"tong":{"type":["integer","null"],"description":"Tổng GTGT + TNCN sau giảm (đồng)."},"tong_kinh_doanh":{"type":["integer","null"]},"cho_thue_bds":{"type":["object","null"]},"nhom_ho":{"type":"integer","minimum":1,"maximum":4},"can_cu":{"type":"array","items":{"type":"string"},"description":"Văn bản pháp luật đã dùng."},"chua_xac_minh":{"type":"array","items":{"type":"string"},"description":"Khoản chưa xác minh nên không tính."},"canh_bao":{"type":"array","items":{"type":"string"},"description":"Lưu ý khi áp dụng."},"ngay_du_lieu":{"type":"string"},"luu_y":{"type":"string","example":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}},"NguongKetQua":{"type":"object","properties":{"nhom_ho":{"type":"integer"},"mo_ta":{"type":"string"},"mien_thue":{"type":"boolean"},"phuong_phap":{"type":"string"},"hoa_don_dien_tu":{"type":"string"},"giam_30":{"type":"boolean"},"can_cu":{"type":"array","items":{"type":"string"},"description":"Căn cứ pháp lý."},"ngay_du_lieu":{"type":"string"},"luu_y":{"type":"string","example":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}},"LaiYeuCau":{"type":"object","required":["so_tien","lai_suat_nam_pct","ky_han_thang"],"properties":{"so_tien":{"type":"integer","description":"Số tiền gốc (đồng).","minimum":1},"lai_suat_nam_pct":{"type":"number","minimum":0,"description":"Lãi suất %/năm."},"ky_han_thang":{"type":"integer","description":"Kỳ hạn (tháng).","minimum":1},"cach":{"type":"string","enum":["cuoi_ky","hang_thang"],"default":"cuoi_ky"},"so_ngay":{"type":["integer","null"],"minimum":1,"description":"Nếu có (chỉ với cuoi_ky): lãi = gốc x lãi năm x số ngày / 365."}}},"LaiKetQua":{"type":"object","properties":{"tien_lai":{"type":"integer","description":"Tổng lãi (đồng)."},"tong_nhan":{"type":"integer","description":"Gốc + lãi (đồng)."},"lai_moi_thang":{"type":["integer","null"]},"luu_y":{"type":"string","example":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}},"TraGopYeuCau":{"type":"object","required":["so_tien","lai_suat_nam_pct","so_thang"],"properties":{"so_tien":{"type":"integer","description":"Số tiền vay (đồng).","minimum":1},"lai_suat_nam_pct":{"type":"number","minimum":0,"description":"Lãi suất %/năm."},"so_thang":{"type":"integer","description":"Số tháng trả.","minimum":1},"kieu":{"type":"string","enum":["du_no_giam_dan","tra_deu"],"default":"du_no_giam_dan"}}},"TraGopKetQua":{"type":"object","properties":{"lich":{"type":"array","items":{"type":"object","properties":{"ky":{"type":"integer"},"goc":{"type":"integer"},"lai":{"type":"integer"},"tong":{"type":"integer"},"con_lai":{"type":"integer"}}}},"tong_lai":{"type":"integer"},"tong_tra":{"type":"integer"},"luu_y":{"type":"string","example":"Kết quả ước tính theo văn bản pháp luật trích dẫn, không thay thế hướng dẫn của cơ quan thuế."}}},"SucKhoe":{"type":"object","properties":{"ok":{"type":"boolean"},"phien_ban":{"type":"string"},"ngay_du_lieu":{"type":"string"}}}}}}