Báo cáo tài chính Python: lấy BCTC cổ phiếu Việt Nam

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"]]

Đơ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.

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ả ba 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