Dữ Liệu Cơ Bản (Fundamental Data)

📌 Tổng Quan

Fundamental Layer cung cấp dữ liệu báo cáo tài chính (BCTC) và tỷ số tài chính phục vụ cho phân tích cơ bản của doanh nghiệp. Ở phương thức nâng cao, hệ thống trang bị tính năng quy chuẩn hoá (Force scorecard) giúp định hình ma trận tài chính cực mạ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).

🏗️ Cấu Trúc Domain

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

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
    ├── .filing()            # Hồ sơ & Tài liệu BCTC (PDF)
    └── .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: MAS
Nhóm lệnh: equity.fundamental.balance_sheet
Tham số:

• period (str): Kỳ báo cáo ('year' cho năm, 'quarter' cho quý).
• lang (str): Ngôn ngữ ('vi' hoặc 'en'). Mặc định 'vi'.
• dropna (bool): Xoá các trường bị rỗng. Mặc định True.
• scorecard (str, optional): Ép chuẩn hoá theo khung ('auto', 'banking', 'securities', 'insurance', 'generic'). Mặc định None.

Ví Dụ:

df_bs = fun.equity.balance_sheet("VIC", period="quarter")

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

Source: MAS
Nhóm lệnh: equity.fundamental.income_statement
Tham số: Tương tự balance_sheet (period, lang, dropna, scorecard).

Ví Dụ:

from vnstock_data import Fundamental
fun = Fundamental()

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

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

Source: MAS
Nhóm lệnh: equity.fundamental.cash_flow
Tham số: Tương tự balance_sheet.

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: MAS
Nhóm lệnh: equity.fundamental.ratio
Tham số: Tương tự balance_sheet.

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'.
• mode (str): Trạng thái bản báo cáo (mặc định 'final').
• style (str): Cấu trúc format dữ liệu, mặc định 'readable' cho định dạng dễ đọc.
• get_all (bool): Lấy toàn bộ hay không. Mặc định False.
• 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. Hồ sơ & tài liệu PDF (Filing)

Source: MBK
Nhóm lệnh: equity.fundamental.filing
Tham số:

• doc_type (str, optional): Phân loại tài liệu muốn lấy. Mặc định None (lấy tất cả). Các tuỳ chọn hợp lệ bao gồm:
  • financial_report: Báo cáo tài chính
  • annual_report: Báo cáo thường niên
  • prospectus: Bản cáo bạch
  • shareholder_resolution: Nghị quyết HĐCĐ
  • shareholder_material: Tài liệu HĐCĐ
  • business_explanation: Giải trình KQKD
  • management_report: Báo cáo tình hình quản trị
  • capital_adequacy: Báo cáo tỷ lệ an toàn vốn
  • board_resolution: Nghị quyết HĐQT
  • capital_safety: Tỷ lệ an toàn tài chính
  • other: Khác

Cung cấp đường dẫn tải trực tiếp đến các bản cáo bạch, báo cáo thường niên, file PDF BCTC.

Ví Dụ:

df_filing = fun.equity("TCB").filing()

7. 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:

• scorecard: "auto", "banking", "securities", "insurance", "generic"
• 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="banking", 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. Đơ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ố.