Thuyết minh BCTC bằng Python — nhóm nợ, tồn kho, giá vốn

Bốn báo cáo chính cho bạn một con số. Thuyết minh cho bạn biết con số ấy gồm những gì.

Với ngân hàng: cho vay cho ai, ngành nào, và bao nhiêu trong đó đang có vấn đề. Với doanh nghiệp thường: hàng tồn kho gồm những gì, giá vốn cấu thành ra sao, tài sản cố định đã hao mòn bao nhiêu.

Hai phương thức, cùng nằm trong client.financials:

Năm nhóm nợ — thứ hầu hết người dùng tìm

import finlens

client = finlens.client()
df = client.financials.notes("VCB", section="loan_quality", start_year=2025, end_year=2025)

# Bỏ dòng gốc, giữ năm nhóm con
la = df[df["parent_code"].notna() & (df["quarter"] == 2)]
print(la[["code", "line_item", "value"]])

  code                        line_item         value
   4.1            4.1. Nợ đủ tiêu chuẩn  1.536317e+15
   4.2                4.2. Nợ cần chú ý  3.876597e+12
   4.3          4.3. Nợ dưới tiêu chuẩn  2.106631e+12
   4.4                 4.4. Nợ nghi ngờ  2.013210e+12
   4.5  4.5. Nợ xấu có khả năng mất vốn  1.145609e+13

Đây là phân nhóm theo Thông tư 11. Nhóm 3, 4 và 5 hợp thành nợ xấu:

goc = df[df["parent_code"].isna() & (df["quarter"] == 2)]["value"].iloc[0]
xau = la[la["code"].isin(["4.3", "4.4", "4.5"])]["value"].sum()
print(f"Tỷ lệ nợ xấu: {xau / goc:.2%}")

⚠️ Dòng cả năm: bằng quý 4, hay bằng tổng bốn quý?

Cùng một giá trị quarter = 0, nhưng nó mang hai nghĩa khác nhau tuỳ nhóm — và nhầm chiều nào cũng sai gần bốn lần.

Đừng đoán. Cột full_year_equals_q4 của note_sections() nói thẳng:

ds = client.financials.note_sections()
print(ds[["company_type", "section", "full_year_equals_q4"]].head())

# Nhóm nào cộng dồn bốn quý ra số cả năm?
cong_duoc = ds[ds["full_year_equals_q4"] == False]["section"].tolist()

Hệ quả cụ thể: với inventory thì đọc quý 4 là số cuối năm. Với revenue thì quý 4 chỉ là một quý — đọc nó như doanh thu cả năm là hiểu thiếu khoảng bốn lần.

car là nhóm duy nhất có full_year_equals_q4 là <NA> — không kỳ nào của nó có đủ bốn quý để so, nên thư viện nói chưa đo được thay vì đoán một trong hai.

Dựng lại cây bằng một groupby

Mỗi dòng mang parent_code, level và order_index, nên cấu trúc thuyết minh dựng lại được ngay trên frame — không phải gọi thêm một endpoint thứ hai:

df = client.financials.notes("VCB", section="loan_by_industry", start_year=2026)
ky = df[df["quarter"] == 2]

for cha, con in ky[ky["parent_code"].notna()].groupby("parent_code"):
    print(cha)
    for _, r in con.sort_values("order_index").iterrows():
        print(f"   {r['code']:<6} {r['line_item'][:44]:<44} {r['value']:,.0f}")

code là số thứ tự in trong chính bản BCTC (4.1, 4.2), không phải một id nội bộ — nên nó khớp đúng dòng trong bản PDF bạn mở cạnh.

Doanh nghiệp thường: tồn kho, giá vốn, hao mòn

df = client.financials.notes("HPG", section="inventory", start_year=2025, end_year=2025)
ky = df[(df["quarter"] == 2) & df["parent_code"].notna()]
print(ky[["code", "line_item", "value"]])

Nhóm này có tối đa chín dòng con: nguyên vật liệu, công cụ dụng cụ, chi phí sản xuất dở dang, thành phẩm, hàng hoá, hàng gửi đi bán… — tức đủ để thấy tồn kho đang đọng ở đâu, thứ mà một con số tổng trên bảng cân đối không nói.

"Tối đa" là chữ đúng: mỗi doanh nghiệp chỉ công bố những khoản nó có. HPG quý 2/2025 ra bảy dòng, không chín — và số dòng thiếu ấy là thông tin, không phải lỗi. Đừng viết code giả định một số dòng cố định.

Bốn nhóm hay dùng nhất của doanh nghiệp thường:

Cặp tangible_asset_cost / tangible_asset_depreciation là chỗ đáng để ý: có cả hai mới tính được giá trị còn lại và suy ra tuổi tài sản.

51 nhóm, và độ phủ của từng nhóm

ds = client.financials.note_sections()
print(ds[["company_type", "code", "section", "organization_count", "last_year"]])

# Danh mục của riêng doanh nghiệp thường
print(ds[ds["company_type"] == "CT"])

Bảng này tồn tại thay cho một danh sách tĩnh trong tài liệu, vì organization_count và last_year được đo lại mỗi lần gọi. Đọc chúng trước khi kết luận một nhóm là "không có dữ liệu".

Bảy nhóm hay dùng nhất của tổ chức tín dụng:

Bỏ trống section thì trả mọi nhóm của những loại có mặt trong symbols — hỏi một mã ngân hàng thì 29 nhóm của doanh nghiệp thường không tham gia. Tham số nhận một giá trị; muốn hai nhóm thì bỏ trống rồi lọc trên frame:

df = client.financials.notes("VCB", start_year=2026)
df = df[df["section"].isin(["loan_quality", "loan_provision"])]

Ai có dữ liệu, và từ năm nào

Cả hai loại đều từ 2006 tới nay: 30 tổ chức tín dụng và 1.443 doanh nghiệp thường. Nhưng độ phủ không đều — với nhóm ngân hàng, năm 2006 chỉ có 9 tổ chức và chỉ bão hoà 28–30 từ 2016.

Một lời gọi trộn được hai loại — và đó là chỗ có một cái bẫy:

df = client.financials.notes("VCB,HPG", start_year=2025, quarters=[0])
print(df["company_type"].unique())          # ['NH' 'CT']

df.groupby("code")["value"].sum()                       # ✗ cộng hai khoản mục lạ
df.groupby(["section", "code"])["value"].sum()          # ✓

Mã của công ty chứng khoán đi vào phần lỗi theo từng mã, kèm thông báo nói đúng nguyên nhân — cây thuyết minh của họ tồn tại trong nguồn nhưng chưa được phát hành, khác hẳn "mã này không có dữ liệu":

df = client.financials.notes("VCB,SSI", start_year=2025)
print(df.attrs["finlens"]["failed"]["SSI"]["message"])

Đơn vị là VND thô, trừ đúng một nhóm

Cột value tính bằng đồng Việt Nam nguyên, khác kVND của cột giá cổ phiếu. Đừng giả định — đọc thẳng:

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

value là <NA> khi nguồn không có ô đó — không phải 0.

df = client.financials.notes("VCB", section="car", start_year=2024)
print(df.attrs["finlens"]["units"]["value"])   # 'pct'

Chỉ có báo cáo hợp nhất

Nguồn không có báo cáo riêng lẻ cho nhóm này, nên không có tham số nào để chọn. Mọi con số là số hợp nhất.

Không có cột tỷ lệ nào

Nhóm này trả con số tuyệt đối, không phát thêm một cột npl_ratio. Lý do: indicators() đã có chỉ tiêu đó, và hai đường đã được đối chiếu — NPL suy từ thuyết minh cho 1,0012% với VCB quý 2/2025 so với 0,01001 của indicators(), lệch dưới 3e-05.

Cần tỷ lệ thì dùng indicators(); cần chính các con số của từng nhóm thì dùng notes().

Nếu bạn cũng dùng công cụ MCP của FinLens

Hai sản phẩm dùng hai bộ tên cho cùng dữ liệu, và điều đó có thật ở cả hai loại doanh nghiệp. Vài chỗ lệch hay gặp:

Thư viện dùng số ít, viết đủ chữ, không viết tắt — cùng quy ước với 22 token ngân hàng đã phát hành từ trước.

Và thư viện phủ rộng hơn ở nhóm doanh nghiệp thường: 29 nhóm so với 20 của MCP. Chín nhóm MCP không có là toàn bộ họ nguyên giá / hao mòn của tài sản thuê tài chính, tài sản vô hình, bất động sản đầu tư, lợi thế thương mại, cộng tangible_asset_depreciation — khoảng 619 nghìn dòng, tức 16% dữ liệu. Riêng nhóm hao mòn TSCĐ hữu hình có 230.857 dòng trên 1.442 tổ chức, và không có nó thì không tính được giá trị còn lại.

Bản async

import asyncio
import finlens

async def main():
    async with finlens.async_client() as client:
        df = await client.financials.notes("VCB", section="loan_quality")
        print(len(df))

asyncio.run(main())

Xem thêm