BCTC & chỉ tiêu P/E, ROE cổ phiếu Việt Nam bằng Python

Cân đối kế toán, kết quả kinh doanh và lưu chuyển tiền tệ của doanh nghiệp niêm yết — theo năm hoặc theo quý, trả về pandas.DataFrame.

Ba phương thức, và chúng trả lời ba câu hỏi khác nhau:

Bốn loại hình doanh nghiệp, bốn cây khoản mục

Đây là điều chi phối cả trang: không tồn tại một "bảng cân đối kế toán" duy nhất. Có bốn cây khác nhau, một cho mỗi loại hình doanh nghiệp, không cùng số khoản mục và không cùng tên khoản mục.

Loại hình của từng mã do máy chủ tra, và nó đi kèm ngay ở cột company_type của mỗi dòng — bạn không phải gọi thêm gì trước, cũng không phải tự giữ một bảng tra riêng.

df = client.financials.statement("HPG,VCB,SSI")
sorted(df["company_type"].unique())      # ['CK', 'CT', 'NH']

Loại hình thứ năm là QU (quỹ), và nó không có báo cáo tài chính dạng cây — đó là trạng thái vĩnh viễn của dữ liệu chứ không phải một khoảng trống tạm thời. Mã thuộc QU đi vào phần lỗi theo từng mã và không làm hỏng phần còn lại của lời gọi; xem on_error ở Xử lý lỗi.

statement() — số liệu từng khoản mục

client.financials.statement(
    symbols,
    *,
    kind="balance_sheet",
    period="annual",
    start_year=None,
    end_year=None,
    quarters=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Chỉ symbols là tham số vị trí; mọi tham số còn lại là keyword-only.

Bốn giá trị của kind

Tên chứ không phải số thứ tự: một con số như 3 không tự nói nó là lưu chuyển tiền tệ trực tiếp hay gián tiếp, nên mỗi người đọc phải giữ một bảng tra nằm ngoài dữ liệu — và nếu nguồn đánh số lại thì mọi truy vấn vẫn chạy, chỉ trả sai báo cáo.

Cột trả về

Mười hai cột luôn có mặt đúng dtype kể cả khi không có dòng nào, nên bạn không cần bọc if not df.empty quanh mỗi lời gọi.

item_id là một mã hiển thị do máy chủ cấp, không phải id nội bộ của nguồn: nó được cấp một lần và không đổi theo thời gian, nên con số bạn ghi vào notebook hôm nay vẫn trỏ đúng khoản mục ấy về sau. Đổi lại, nó chỉ có nghĩa trong phạm vi một (company_type, kind) — cùng một con số ở hai loại hình doanh nghiệp là hai khoản mục khác hẳn nhau.

Frame giữ nguyên thứ tự máy chủ gửi, tức kỳ mới nhất đứng trước — đó là thứ người mở một báo cáo tài chính muốn thấy đầu tiên. Muốn khác thì df.sort_values(...).

import finlens

client = finlens.client()

df = client.financials.statement("HPG")
df.attrs["finlens"]["units"]["value"]     # 'VND'

# Kết quả kinh doanh theo quý, từ 2023
df = client.financials.statement(
    "HPG",
    kind="income_statement",
    period="quarterly",
    start_year=2023,
)

# Chỉ quý 1 và quý 3
df = client.financials.statement("HPG", period="quarterly", quarters=[1, 3])

quarter = 0 nghĩa là cả năm

ca_nam = df[df["quarter"] == 0]     # số liệu năm
theo_quy = df[df["quarter"] > 0]    # số liệu quý

Có hai thứ tên gần giống nhau và cố ý không trùng tên:

• Tham số period= nhận "annual" / "quarterly" — nó nói bạn muốn kỳ loại nào.
• Cột period_label mang "2025" / "Q1 2025" — nó nói dòng này thuộc kỳ nào.

Hai tập giá trị rời hẳn nhau. Nếu cột đó cũng tên period thì df[df["period"] == "annual"] sẽ trả bảng rỗng mà không ném lỗi nào — người viết tin mình đang lọc, thực ra đang xoá sạch. Muốn lọc thì lọc theo quarter.

Dựng lại cây báo cáo từ chính frame này

Mỗi dòng đã mang sẵn parent_id, level và order_index, nên bạn dựng được cây ngay trên bảng số liệu — không cần gọi line_items() trước:

ky = df[(df["symbol"] == "HPG") & (df["quarter"] == 0) & (df["year"] == 2025)]

goc = ky[ky["parent_id"].isna()]                       # các node gốc
con = ky.groupby("parent_id")["item_id"].apply(list)   # con của từng node

# Đọc theo đúng thứ tự của bản báo cáo giấy
ky.sort_values("order_index")[["level", "line_item", "value"]]

goc = ky[ky["parent_id"].isna()]     # đúng
goc = ky[ky["parent_id"] == 0]       # sai

Join hai mã khác loại hình

item_id chỉ có nghĩa trong phạm vi (company_type, kind). Cùng một số ở hai loại hình là hai khoản mục khác hẳn nhau, nên khoá join phải mang theo cả hai cột đó:

# Đúng
a.merge(b, on=["company_type", "kind", "item_id"])

# Sai — ghép nhầm hai khoản mục không liên quan
a.merge(b, on="item_id")

Vài giá trị vượt ngưỡng chính xác của số thực

periods() — kỳ nào thực sự có số liệu

client.financials.periods(
    symbols,
    *,
    refresh=False,
    on_error="warn",
) -> DataFrame

Một dòng cho mỗi bộ (symbol, year, quarter). Dùng nó để chọn start_year / end_year cho đúng, thay vì hỏi một khoảng rồi nhận về bảng rỗng và không biết vì sao. Rẻ hơn statement() rất nhiều: nó chỉ trả lịch kỳ, không trả khoản mục nào.

Không cột nào ở đây mang đơn vị — đây là lịch kỳ, không phải số liệu.

Kết quả sắp tăng dần theo symbol, year, quarter. Đây là chỗ khác statement() một cách có chủ đích: bảng này là một trục thời gian để chọn khoảng, mà một trục thời gian thì đọc xuôi.

ky = client.financials.periods("HPG")

nam_co_du_lieu = sorted(ky.loc[ky["quarter"] == 0, "year"].unique())
df = client.financials.statement("HPG", start_year=int(min(nam_co_du_lieu)))

Yêu cầu một khoảng rộng hơn dải thực có không phải lỗi: máy chủ cắt về phần có thật thay vì từ chối cả lời gọi. periods() là cách biết trước dải đó.

line_items() — cây khoản mục, không cần mã nào

client.financials.line_items(
    *,
    com_type,
    kind,
    refresh=False,
    on_error="warn",
) -> DataFrame

Phương thức duy nhất trong nhóm không nhận mã chứng khoán, và cũng không có tham số vị trí nào. Khoá của cây là cặp (com_type, kind) — cấu trúc báo cáo không thuộc về một doanh nghiệp cụ thể nào.

Cả hai đều không có giá trị mặc định, và đó là chủ đích: bốn loại hình có bốn cây khác nhau nên không giá trị nào là trung lập, còn kind thì đoán hộ sẽ trả về một cây bạn không hỏi. statement() mặc định được balance_sheet vì hỏi báo cáo mà không nói loại nào thì cân đối kế toán là câu trả lời ít bất ngờ nhất; ở đây thì không.

"QU" (quỹ) không nằm trong kiểu CompanyType, nên gõ nó vào là một gạch đỏ ngay trong IDE chứ không phải một lỗi sau một vòng gọi mạng.

Cột trả về

Không cột nào mang đơn vị — đây là cấu trúc, không phải số liệu. Năm cột cây trùng đúng tên và đúng dtype với statement(), nên hai frame join được với nhau theo (company_type, kind, item_id) mà không phải đổi hình.

cay_nh = client.financials.line_items(com_type="NH", kind="balance_sheet")
cay_ct = client.financials.line_items(com_type="CT", kind="balance_sheet")

len(cay_nh) != len(cay_ct)      # True — hai cây, hai kích thước

# Đọc cây theo đúng thứ tự trình bày
cay_nh.sort_values("order_index")[["level", "line_item"]]

indicators() — chỉ tiêu tài chính tính sẵn

client.financials.indicators(
    symbols,
    *,
    codes=None,
    groups=None,
    period="annual",
    start_year=None,
    end_year=None,
    quarters=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

statement() trả về khoản mục thô; muốn P/E, ROE, NIM hay nợ xấu thì bạn phải tự dựng lại — tức tự viết lại đúng phần khó nhất. indicators() trả về 135 mã chỉ tiêu đã tính, một dòng cho mỗi chỉ tiêu của mỗi kỳ.

import finlens

client = finlens.client()

# Toàn bộ chỉ tiêu của một ngân hàng
chi_tieu = client.financials.indicators("VCB", start_year=2025)

# Vài chỉ tiêu, nhiều mã, trộn loại hình doanh nghiệp
chi_tieu = client.financials.indicators(
    "VCB,HPG,SSI", codes="roe,roa,total_assets", start_year=2023
)

Bốn loại hình, bốn bộ chỉ tiêu

Chúng khác nhau một cách có nội dung, không phải vì thiếu số liệu: nim chỉ tồn tại ở ngân hàng, margin_to_equity chỉ ở công ty chứng khoán, loss_ratio_retained chỉ ở doanh nghiệp bảo hiểm.

Cột bên phải chỉ liệt kê nhóm độc quyền của một loại hình. Phần lớn nhóm dùng chung ở nhiều loại: capital có ở cả CT, NH và BH; solvency có ở CT và CK; income_structure có ở NH, CK và BH. Cộng bốn con số bên trái ra 181 — đó là số cặp (loại hình, chỉ tiêu), không phải số mã, vì một mã như roe xuất hiện ở cả bốn loại.

Xin một mã không áp cho loại hình đó thì đơn giản là không có dòng nào — nó khác hẳn một mã gõ sai, vốn bị từ chối bằng lỗi cho cả lời gọi.

⚠️ Đơn vị nằm ở CỘT, không ở df.attrs

Một frame chỉ tiêu mang nhiều đơn vị cùng lúc — roe là tỷ lệ, total_assets là VND, inventory_days là ngày — nên df.attrs["finlens"]["units"] không trả lời được câu hỏi ở đây. Đọc cột unit của từng dòng.

⚠️ Khoá units vẫn có mặt, và units["value"] là None chứ không ném KeyError. Nghĩa là một đoạn code kiểu if "value" in units: vẫn chạy vào nhánh trong rồi lấy ra None — hàng rào duy nhất có tác dụng là đọc cột unit.

chi_tieu.attrs["finlens"]["units"]["value"]   # None — không phải 'VND'

Từ vựng đơn vị đóng, và không có %: VND · VND/share · x · ratio · days.

⚠️ ratio là phân số, và nó KHÔNG bị chặn trong 0–1

roe = 0.16721 nghĩa là 16,721% — nhân 100 khi hiển thị.

Nhưng đừng viết "giá trị lớn hơn 1 thì chắc đang ở thang phần trăm, chia 100":

Phép "chuẩn hoá" ấy biến chúng thành 0,018 và 0,019: đúng ở những kỳ bình thường, sai ở đúng những kỳ đáng chú ý nhất.

period="ttm" — luỹ kế bốn quý

ttm = client.financials.indicators("HPG", period="ttm")

Chỉ tiêu dòng (kết quả kinh doanh, lưu chuyển tiền) được cộng bốn quý; số dư (cân đối kế toán) và tỷ số lấy ở cuối cửa sổ. Cộng một số dư qua bốn quý sẽ ra tổng tài sản gấp bốn lần sự thật.

Cửa sổ thiếu quý thì kỳ đó không tồn tại — một tổng ba quý phát ra như kỳ bốn quý là con số sai duy nhất bạn không phát hiện được từ chính nó.

⚠️ period="ttm" không có ở statement(), và đó là chủ đích: một cây khoản mục luỹ kế bốn quý không phải báo cáo nào doanh nghiệp từng nộp.

⚠️ quarters= chỉ có nghĩa với period="quarterly". Truyền kèm "ttm" bị từ chối chứ không bị bỏ qua — lọc bớt quý sẽ làm mọi cửa sổ bốn quý đứt.

⚠️ Lọc kỳ bằng period_type, đừng lọc bằng quarter một mình

quarter = 2 xuất hiện ở cả một quý rời rạc lẫn một cửa sổ TTM kết thúc ở quý đó, và hai đại lượng ấy chênh nhau khoảng bốn lần.

chi_tieu[chi_tieu["period_type"] == "ttm"]   # đúng
chi_tieu[chi_tieu["quarter"] == 2]           # trộn hai loại kỳ

indicator_catalog() — nhãn, đơn vị và công thức

client.financials.indicator_catalog(
    *,
    com_type=None,
    groups=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

indicators() không trả label và formula: chúng là thuộc tính của code, không của từng kỳ — gắn vào mỗi dòng thì một frame 40 chỉ tiêu × 12 kỳ chở cùng một chuỗi công thức 12 lần.

Gọi một lần rồi giữ lại, merge theo cặp (company_type, code):

values = client.financials.indicators("VCB", start_year=2025)
catalog = client.financials.indicator_catalog()

named = values.merge(
    catalog[["company_type", "code", "label", "formula", "higher_is_better"]],
    on=["company_type", "code"],
)
print(named[["symbol", "period_label", "label", "value", "unit"]])

⚠️ Lấy đúng những cột bạn cần thay vì merge cả bảng: hai frame cùng có group và unit, nên values.merge(catalog, on=[...]) đổi tên chúng thành group_x, unit_x, group_y, unit_y — và dòng print ngay trên ném KeyError: "['unit'] not in index".

Cột formula trả lời câu hỏi "roic của các anh tính thế nào" mà không phải đi hỏi ai:

catalog.loc[catalog["code"] == "roic", "formula"].iloc[0]
# 'EBIT × (1 − thuế suất thực tế) ÷ (vốn chủ sở hữu + nợ vay có lãi − tiền).
#  Thuế suất thực tế lùi về 20% khi không tính được.'

⚠️ higher_is_better bằng null là một khẳng định, không phải ô quên điền: total_assets lớn không "tốt hơn" nhỏ. Xếp hạng hay tô màu theo một chỉ tiêu null là bịa ra một chiều tốt/xấu không tồn tại.

Đơn vị là VND thô

Mọi giá trị trong statement() tính bằng VND thô — không phải nghìn VND như cột giá cổ phiếu, cũng không phải triệu hay tỷ đồng.

⚠️ Mục này không áp cho indicators(): ở đó một frame mang nhiều đơn vị cùng lúc nên đơn vị nằm ở cột unit của từng dòng, và df.attrs không nói gì về nó.

df.attrs["finlens"]["units"]["value"]     # 'VND'

Nghĩa là tổng tài sản của một doanh nghiệp lớn sẽ là một con số mười lăm chữ số. Muốn hiển thị cho người đọc thì chia ở tầng trình bày, đừng chia trong dữ liệu — df["value"] / 1e9 để ra tỷ đồng.

⚠️ DataFrame.attrs không sống sót qua pd.concat hay merge của pandas. Đọc đơn vị ra biến trước khi ghép bảng. Chi tiết ở Kiểu dữ liệu.

Bản async

Cả năm phương thức đều có bản bất đồng bộ với cùng chữ ký:

import asyncio
import finlens

async def main():
    async with finlens.AsyncClient() as client:
        df = await client.financials.statement("HPG,VCB", kind="income_statement")

asyncio.run(main())

Xem thêm