Lớp Fundamental: hàm truy xuất dữ liệu báo cáo tài chính

📌 Tổng Quan

Fundamental Layer giúp bạn truy xuất dữ liệu báo cáo tài chính (BCTC) và tỷ số tài chính từ nguồn bên thứ ba, phục vụ phân tích cơ bản của doanh nghiệp. Ở phương thức nâng cao, thư viện có tính năng quy chuẩn hoá (Force scorecard) giúp định hình ma trận tài chính cho các mô hình AI dự báo.

Bao gồm Báo cáo kết quả kinh doanh, Bảng cân đối kế toán, Lưu chuyển tiền tệ, Tỷ số tài chính, Thuyết minh BCTC và Báo cáo sức khỏe tài chính tổng hợp (Auto Scorecard).

🗂️ Định Dạng Dữ Liệu & Cấu Trúc Cột Mới

Từ phiên bản 3.2.8, tất cả các cơ chế triển khai hàm lấy BCTC đều có chung định dạng dữ liệu trả về mặc định là Tidy Data (long format). Dữ liệu được tái cấu trúc, chuẩn hóa theo tiêu chuẩn kế toán Việt Nam (VAS) và các biểu mẫu ban hành đã được chuẩn hoá cho từng loại hình doanh nghiệp:

• id: Mã (primary key) duy nhất cho mỗi tiêu chí (ví dụ: IS_NET_REVENUE). Giúp code gọi hàm đảm bảo thuật toán ổn định.
• name: Tên tiêu chí theo chuẩn mực kế toán Việt Nam, dùng để giải nghĩa cho id.
• unit: Đơn vị dữ liệu giúp đọc hiểu chuẩn xác.
• order: Thứ tự trình bày tiêu chí trong báo cáo, giúp tái tạo chuẩn thứ tự khi dùng pivot hoặc hiển thị nhiều kỳ.
• level: Phân cấp cha/con theo hệ thống chuẩn mực kế toán.

Khi đổi tham số format sang 'wide' hoặc 'time_series', hệ thống sẽ dùng id làm khoá chính để xoay trục báo cáo thay vì tên gốc dạng snake_case đã được làm sạch như ở phiên bản cũ.

🔗 Xem chi tiết: Hướng dẫn Migration v3.2.8

🏗️ Cấu Trúc Nhóm Hàm

Mô đun Fundamental hỗ trợ 2 dạng cú pháp linh hoạt:

1. Dạng hướng đối tượng (Object Oriented): fun.equity("TCB").cash_flow()
2. Dạng hàm tiện ích (Utility Function): fun.equity.cash_flow("TCB")

Fundamental()
└── .equity                  # Dữ liệu tài chính chứng khoán (Cổ phiếu)
    ├── .income_statement()  # Báo cáo kết quả kinh doanh
    ├── .balance_sheet()     # Cân đối kế toán
    ├── .cash_flow()         # Lưu chuyển tiền tệ
    ├── .ratio()             # Tỷ số tài chính
    ├── .note()              # Thuyết minh cơ cấu BCTC
    └── .financial_health()  # Báo cáo hợp nhất với Auto Scorecard

1. Bảng cân đối kế toán (Balance Sheet)

Source: VCI
Nhóm lệnh: equity.fundamental.balance_sheet
Tham số:

• period (str, optional): Kỳ báo cáo ('year' cho năm, 'quarter' cho quý).

• lang (str, optional): Ngôn ngữ ('vi' hoặc 'en'). Mặc định 'vi'.

• format (str, optional): Định dạng dữ liệu đầu ra ('long', 'wide', 'time_series'). Mặc định 'long' ngoại từ hàm financial_health.

• drop_empty (bool, optional): Xoá các tiêu chí trống hoàn toàn (NaN) trong kỳ báo cáo. Mặc định False.

• com_type (str, optional): Cố định loại hình công ty để áp dụng taxonomy ('Regular', 'Bank', 'Securities', 'Insurance'). Theo mặc định sẽ tự động dò. Sử dụng nếu có mã bất kỳ bị nhận diện sai nhóm ngành khiến cho các chỉ tiêu bị thiếu hụt hoặc sai lệch.

Ví Dụ:

from vnstock_data import Fundamental
fun = Fundamental()
df_bs = fun.equity.balance_sheet("VIC", period="quarter")

2. Báo cáo kết quả kinh doanh (Income Statement)

Source: VCI
Nhóm lệnh: equity.fundamental.income_statement
Tham số: Tương tự balance_sheet (period, lang, format, drop_empty, com_type).

Ví Dụ:

df_income = fun.equity("TCB").income_statement(period="year")

3. Lưu chuyển tiền tệ (Cash Flow)

Source: VCI
Nhóm lệnh: equity.fundamental.cash_flow
Tham số: Tương tự balance_sheet (period, lang, format, drop_empty, com_type).

Ví Dụ:

df_cf = fun.equity("VNM").cash_flow(period="year")

4. Tỷ số tài chính (Financial Ratio)

Chứa các tỷ số quan trọng như PE, PB, ROE, Debt/Equity.

Source: VCI
Nhóm lệnh: equity.fundamental.ratio
Tham số: Tương tự balance_sheet (period, lang, format, drop_empty, com_type).

Ví Dụ:

df_ratio = fun.equity("HPG").ratio(period="quarter")

5. Thuyết minh BCTC (Note)

Source: VCI
Nhóm lệnh: equity.fundamental.note
Tham số:

• period (str, optional): Kỳ báo cáo.

• lang (str): Ngôn ngữ ('en' hoặc 'vi'). Mặc định 'en'.

• dropna (bool): Xóa trường rỗng. Mặc định True.

Trích xuất tự động các thuyết minh con/ghi chú chi tiết đính kèm trên báo cáo tài chính hàng quý.

Ví Dụ:

df_note = fun.equity("FPT").note(period="year", lang="vi")

6. Bảng tiêu chí tổng hợp (Financial Health)

Từ Vnstock 3.1.0, hàm này được trang bị nhằm tăng tính ổn định cho code của người dùng và trích xuất bộ tiêu chí phân tích phổ biến một cách nhanh chóng. Cơ chế hoạt động của financial_health như sau:

• Dò tìm mã ngành ICB tự động (qua Reference layer).
• Ép chuẩn dữ liệu tài chính đi qua bộ tiêu chí (scorecard) (Ngân hàng, CK, Bảo hiểm, chung...).
• Chỉ cho phép các tiêu chí đã chỉ định.
• Nối BCTC theo phương ngang dựa vào index là period.
• Áp lang="vi" để ánh xạ ra giao diện hiển thị.

Tham số bổ sung:

• com_type: "auto", "bank", "securities", "insurance", "regular"
• reports: List các loại báo cáo muốn hợp nhất (Mặc định: cả 4 fundamental reports).

Ví Dụ:

df_ssi = fun.equity("SSI").financial_health(scorecard="auto", lang="vi", limit=4)

df_tcb = fun.equity("TCB").financial_health(scorecard="bank", lang="en", limit=4)

⚠️ Lưu Ý Quan Trọng

1. Tần Suất Update: BCTC định kỳ được công bố theo quý, bán niên, báo cáo năm.
2. Tự động cập nhật: Dữ liệu các kỳ đã có báo cáo kiểm toán/soát xét sẽ tự động cập nhật thay thế dữ liệu do doanh nghiệp tự công bố trước đó.
3. Mẫu báo cáo: Dữ liệu chuẩn hoá tuân theo nội dung của báo cáo Hợp Nhất (nếu có).
4. Đơn Vị Tiền Tệ: Mặc định là VND trừ khi có chỉ định khác. Bạn có thể đối chiếu với trang chính thức của nguồn dữ liệu được công bố.