Báo cáo tài chính và chỉ số cơ bản

Lớp Fundamental() lấy số liệu báo cáo tài chính của một mã cổ phiếu: ba báo cáo chính, bộ chỉ số tài chính, thuyết minh và bảng sức khoẻ tài chính. Mọi báo cáo dùng chung một bộ chỉ tiêu chuẩn theo chuẩn mực kế toán Việt Nam, có mã chỉ tiêu cố định, nên mã bạn viết cho FPT chạy được cho mã khác cùng loại hình mà không phải sửa tên cột.

from vnstock import Fundamental

fin = Fundamental().equity("FPT")
df = fin.income_statement(period="year")

Tóm tắt

Ở cấp Khách và Cộng đồng, ba báo cáo chính trả về ở dạng rút gọn và giới hạn số kỳ, xem mục Quyền theo cấp bên dưới.

Kế hoạch kinh doanh năm (annual_plan) chưa có hàm trên Fundamental(). Bạn lấy nó qua lớp kiểu cũ Finance, xem mục Kế hoạch kinh doanh năm ở cuối trang.

Hai cách gọi

Cả hai cách cho cùng kết quả:

from vnstock import Fundamental

fun = Fundamental()

# Gắn mã trước, rồi chọn báo cáo
fun.equity("VCB").balance_sheet(period="year")

# Chọn báo cáo trước, mã là tham số đầu tiên
fun.equity.balance_sheet("VCB", period="year")

Mã cổ phiếu được tự chuyển sang chữ hoa.

Quyền theo cấp

Số kỳ. Thư viện giữ các kỳ gần nhất và bỏ các kỳ cũ hơn. Nếu kết quả bị cắt, df.attrs["tier_cap_periods"] cho biết số kỳ đã giữ. Phép cắt chạy trước khi xoay bảng, nên dạng dài, dạng rộng và dạng chuỗi thời gian của cùng một lời gọi có cùng các kỳ.

Báo cáo rút gọn. Mỗi báo cáo có chỉ tiêu cấp 1 (ví dụ "Doanh thu thuần", "Lợi nhuận gộp") và chỉ tiêu con nằm dưới chúng (ví dụ "Tiền" và "Các khoản tương đương tiền" dưới "Tiền và các khoản tương đương tiền"). Ở cấp Khách và Cộng đồng, ba báo cáo chính chỉ giữ chỉ tiêu cấp 1. Giá trị của chỉ tiêu cấp 1 không đổi: thư viện đọc nó thẳng từ nguồn, không cộng từ chỉ tiêu con. Khi kết quả bị rút gọn, df.attrs["tier_cap_level"] bằng 1. Thuyết minh không có ở hai cấp này.

Gọi hàm ngoài cấp, hay chọn nguồn ngoài cấp, thì nhận EntitlementError với mã VNSTOCK_TIER_ROUTE hoặc VNSTOCK_TIER_SOURCE, và thư viện không gửi truy vấn nào đi. Xem Cấp quyền và giới hạn.

Ba báo cáo chính

income_statement(com_type=None, *, period=None, lang="vi", drop_empty=False, format="long", source=None)
balance_sheet(com_type=None, *, period=None, lang="vi", drop_empty=False, format="long", source=None)
cash_flow(com_type=None, *, period=None, lang="vi", drop_empty=False, format="long", source=None)

Ba hàm có cùng tham số.

com_type là tham số vị trí đầu tiên. Viết income_statement("quarter") như bản 4.x sẽ nhận InputError mã VNSTOCK_INPUT_COMPANY_TYPE. Luôn ghi tên tham số: income_statement(period="quarter").

Thường bạn không cần truyền com_type. Thư viện tự nhận ngân hàng, công ty chứng khoán, bảo hiểm và doanh nghiệp thường, rồi dùng đúng bộ chỉ tiêu. Chỉ truyền khi một mã bị nhận sai loại hình khiến chỉ tiêu thiếu hay lệch.

Ví dụ

from vnstock import Fundamental

fpt = Fundamental().equity("FPT")
vcb = Fundamental().equity("VCB")

is_year = fpt.income_statement(period="year")
is_quarter = fpt.income_statement(period="quarter", format="wide")
bs_bank = vcb.balance_sheet(period="year")
cf_kbs = fpt.cash_flow(period="year", source="kbs")

Doanh nghiệp thường và ngân hàng

Mỗi loại hình có bộ chỉ tiêu riêng theo mẫu báo cáo của loại hình đó. Báo cáo kết quả kinh doanh của FPT bắt đầu bằng doanh thu bán hàng, của VCB bắt đầu bằng thu nhập lãi thuần.

FPT, income_statement(period="year"), chạy ngày 10/10/2026, cấp Tài trợ:

VCB, cùng lời gọi:

Chỉ tiêu con có ký tự ‣ ở đầu tên. Ở cấp Khách và Cộng đồng, hai dòng cấp 2 của VCB không có trong kết quả.

Bảng cân đối kế toán có thêm cột off_balance (bool): True với các chỉ tiêu ngoài bảng, ví dụ khoản bảo lãnh vay vốn của ngân hàng.

Nguồn

Mọi nguồn trả cùng bộ cột và cùng mã chỉ tiêu. Một chỉ tiêu nguồn không có thì giá trị là NaN. Nguồn thực tế của một kết quả nằm ở df.attrs["source"].

Hình dạng bảng

Tham số format chọn cách xếp bảng. Cả ba dạng chứa cùng số liệu, và chỉ mục luôn là RangeIndex (0, 1, 2…), không có cột report_time.

format="long" (mặc định)

Mỗi dòng là một chỉ tiêu của một kỳ. Kỳ mới nhất đứng đầu, trong mỗi kỳ chỉ tiêu xếp theo thứ tự trình bày trong báo cáo.

format="wide"

Mỗi dòng là một chỉ tiêu, mỗi kỳ là một cột, kỳ cũ bên trái, kỳ mới bên phải. Đây là dạng giống orient="report" của bản 4.x. Cột tên chỉ tiêu ở dạng này là item thay cho name.

FPT, income_statement(period="year", format="wide"), chạy ngày 10/10/2026 (chỉ hiện ba kỳ cuối):

format="time_series"

Mỗi dòng là một kỳ, mỗi chỉ tiêu là một cột, kỳ cũ ở trên. Cột đầu là period, các cột còn lại là mã chỉ tiêu (IS_NET_REVENUE…), không phải tên, nên không đổi theo lang. Dạng này hợp để vẽ biểu đồ hay đưa vào mô hình. Đây là dạng giống orient="time_series" của bản 4.x.

FPT, income_statement(period="quarter", format="time_series"), chạy ngày 10/10/2026 (ba dòng cuối, ba cột tiêu biểu):

Giá trị khác ba dạng trên thì nhận InputError mã VNSTOCK_INPUT_FINANCIAL_FORMAT.

Tham số orient của bản 4.x

Ba báo cáo chính và ratio() vẫn hiểu orient= của bản 4.x: orient="report" cho format="wide", orient="time_series" cho format="time_series". Nếu bạn truyền cả format khác "long", format được ưu tiên. Mã mới nên dùng format.

Thông tin đi kèm

df.attrs mang các khoá: source (nguồn), symbol, report (tên báo cáo), format, route, length (số dòng), taxonomy_version (phiên bản bộ chỉ tiêu). Khi kết quả bị cắt theo cấp có thêm tier_cap_periods và tier_cap_level.

Chỉ số tài chính: ratio()

ratio(com_type=None, *, period=None, lang="vi", drop_empty=False, format="long", source=None)

Cấp: Tài trợ. Khách và Cộng đồng nhận EntitlementError mã VNSTOCK_TIER_ROUTE.

Tham số giống ba báo cáo chính. Nguồn nhận: vci (mặc định), kbs, mas.

Bảng có cùng cột với dạng dài ở trên. Chỉ số xếp theo nhóm: dòng cấp 1 là tên nhóm (định giá, hiệu quả hoạt động…) và không có giá trị, các chỉ số nằm ở cấp 2. Cột unit cho biết đơn vị của từng chỉ số (lần, %…).

from vnstock import Fundamental

r = Fundamental().equity("FPT").ratio(period="year")

FPT, chạy ngày 10/10/2026:

Thuyết minh: note()

note(**kwargs)

Cấp: Tài trợ. Nguồn: vci.

Nhận cùng tham số từ khoá như income_statement(): com_type, period, lang, format, source, drop_empty. Bảng có cùng cột với dạng dài. Mã chỉ tiêu bắt đầu bằng NT_.

from vnstock import Fundamental

notes = Fundamental().equity("FPT").note(period="year")

FPT, chạy ngày 10/10/2026:

Sức khoẻ tài chính: financial_health()

financial_health(com_type="auto", reports=None, scorecard="auto", *, period=None, lang="vi",
                 format="wide", limit=16, source=None)

Cấp: Tài trợ. Nguồn: vci.

Hàm gom vài chục chỉ tiêu người đọc thường xem trước tiên, lấy từ ba báo cáo chính và bộ chỉ số, vào một bảng. Bộ chỉ tiêu chọn theo loại hình doanh nghiệp: ngân hàng có nợ xấu, bao phủ nợ xấu, hệ số an toàn vốn; doanh nghiệp thường có doanh thu, giá vốn, lợi nhuận gộp…

from vnstock import Fundamental

Fundamental().equity("VCB").financial_health(period="quarter", limit=4)

VCB, chạy ngày 10/10/2026 (ba dòng đầu):

Ở bảng này level là số nguyên, mọi dòng ở cấp 1.

Kế hoạch kinh doanh năm

Fundamental() chưa có hàm cho kế hoạch kinh doanh năm. Lớp kiểu cũ Finance lấy được, chỉ với nguồn mas, chỉ kỳ năm. Cấp: Tài trợ.

from vnstock.api import Finance

plan = Finance(source="mas", symbol="FPT").annual_plan()

Bảng có cùng cột với dạng dài (period, id, name, order, level, unit, value). Mã chỉ tiêu ở đây viết thường, ví dụ total_revenue, total_profit_before_tax.

FPT, chạy ngày 10/10/2026:

Đã ngừng

Khác bản cũ

• Dạng mặc định là dạng dài. Bản 4.x mặc định mỗi kỳ một cột. Muốn như cũ, truyền format="wide" (hoặc orient="report").
• Kỳ mặc định là mọi kỳ. Bản 4.x mặc định period="year". Ở thế hệ 5, bỏ trống period là lấy cả năm lẫn quý.
• Tham số vị trí đầu tiên là com_type. Luôn ghi period= bằng tên.
• Nguồn mặc định là vci. Bản 4.x dùng KBS.
• Cột chuẩn hoá. Bản 4.x trả item, item_en và các cột năm. Thế hệ 5 có thêm mã chỉ tiêu id, cấp level, thứ tự order, đơn vị unit, và tên tiếng Anh lấy bằng lang="en".
• ratio() cần cấp Tài trợ.

Xem thêm Chuyển đổi từ vnstock 4.x, Chuyển đổi từ vnstock_data 3.x và Nguồn dữ liệu.