Vnstock Logo

Truy xuất và chuẩn hoá báo cáo tài chính

Mở rộng

Mục lục

Lớp Fundamental giúp bạn truy xuất bảng cân đối kế toán, báo cáo kết quả kinh doanh và báo cáo lưu chuyển tiền tệ. Toàn bộ số liệu được chuẩn hoá về hệ thống chỉ tiêu dựa trên Chuẩn mực Kế toán Việt Nam (VAS). Mỗi chỉ tiêu mang một mã định danh cố định (như BS_TOTAL_ASSETS, IS_NET_REVENUE…), giúp cùng một đoạn mã phân tích của bạn chạy xuyên suốt trên nhiều doanh nghiệp cùng loại hình.

Python
from vnstock import Fundamental

fpt = Fundamental().equity("FPT")
df = fpt.income_statement(period="year", source="fhsc")

Các hàm báo cáo và chỉ số tài chính trong lớp Fundamental

Tên hàmBáo cáo / Dữ liệu trả vềNguồn hỗ trợGhi chú sử dụng
balance_sheet()Bảng cân đối kế toán chuẩn VASfhscTự động nhận diện mẫu biểu theo loại hình doanh nghiệp
income_statement()Báo cáo kết quả hoạt động kinh doanh chuẩn VASfhscHỗ trợ kỳ năm ("year"), kỳ quý ("quarter") hoặc gộp cả hai
cash_flow()Báo cáo lưu chuyển tiền tệ chuẩn VASfhscGiữ nguyên dấu âm/dương theo bản chất dòng tiền
ratio()Bảng 40 chỉ số tài chính do nguồn tính sẵn (mỗi kỳ một dòng: year, quarter, pe, pb, roe…)fhscCông thức do nguồn tự định nghĩa. Nếu cần công thức minh bạch và kiểm chứng được, hãy tính bằng vnstock_quant
note(), financial_health(), filing()Thuyết minh báo cáo, sức khoẻ tài chính, văn bản công bố—Chưa có trên cổng Open API ở thế hệ 6; gọi hàm sẽ nhận lỗi UnsupportedError mã VNSTOCK_ROUTE_UNSUPPORTED

Để tính toán các chỉ số ROE, ROA, biên lợi nhuận, hệ số thanh khoản, đòn bẩy hay NIM với công thức tường minh từ ba báo cáo chuẩn VAS ở trên, bạn kết hợp cùng mô-đun vnstock_quant.fa ngay trên máy (xem hướng dẫn bên dưới).

Cú pháp gọi hàm và cách thiết lập nguồn mặc định

Bạn có thể truyền mã cổ phiếu vào .equity("Mã") trước rồi gọi tên báo cáo, hoặc truyền mã cổ phiếu làm tham số đầu tiên của hàm báo cáo:

Python
from vnstock import Fundamental

fun = Fundamental()

fun.equity("VCB").balance_sheet(period="year", source="fhsc")      # gắn mã cổ phiếu vào equity()
fun.equity.balance_sheet("VCB", period="year", source="fhsc")      # truyền mã cổ phiếu làm tham số đầu
fun.equity("SSI").cash_flow(period="quarter", format="wide", source="fhsc")

Vì thế hệ 6 không tự chọn nguồn ngầm, bạn truyền source= trong lời gọi hoặc đặt quy tắc mặc định một lần cho toàn bộ nhánh báo cáo tài chính:

Python
import vnstock
vnstock.sources.use("fhsc", route="fundamental.equity.*")

Nếu gọi hàm khi chưa chỉ định nguồn, thư viện sẽ báo lỗi InputError với mã VNSTOCK_INPUT_SOURCE (Cách chọn nguồn dữ liệu).

Các tham số tuỳ chỉnh kỳ báo cáo, ngôn ngữ và định dạng

Ba hàm báo cáo tài chính chia sẻ chung một chữ ký tham số:

Python
balance_sheet(company_type=None, period=None, lang="vi", drop_empty=False, format="long", *, source=None, compat=None)
income_statement(...)   # nhận cùng bộ tham số
cash_flow(...)          # nhận cùng bộ tham số
Tên tham sốKiểu dữ liệuGiá trị mặc địnhÝ nghĩa và cách dùng
company_typestr hoặc NoneNoneLoại hình doanh nghiệp. Để None hoặc "auto" để thư viện tự nhận diện từ dữ liệu nguồn. Chấp nhận "regular" (hoặc "generic", "dn"), "bank" ("banking", "tctd"), "securities" ("ctck"), "insurance" ("dnpnt"). Tên tham số cũ com_type vẫn được chấp nhận
periodstr hoặc NoneNoneKỳ báo cáo: "year" (hoặc "yearly", "annual", "y") cho kỳ năm; "quarter" ("quarterly", "q") cho kỳ quý. Để None sẽ lấy cả kỳ năm lẫn kỳ quý giống thế hệ 5
langstr"vi"Ngôn ngữ hiển thị tên chỉ tiêu: "vi" (tiếng Việt) hoặc "en" (tiếng Anh). Chỉ đổi cột tên hiển thị, mã id của chỉ tiêu không đổi
drop_emptyboolFalseKhi đặt True, thư viện lược bỏ những dòng chỉ tiêu không có số liệu khác 0 ở bất kỳ kỳ nào
formatstr"long"Định dạng bố cục bảng: "long" (bảng dọc), "wide" (bảng ngang theo kỳ) hoặc "time_series" (chuỗi thời gian), xem mục bên dưới
sourcestrNguồn dữ liệu sử dụng cho lời gọi này
compatstr"v5"Hồ sơ tên cột: "v5" giữ tên cột như thế hệ 5; "v6" dùng tên cột chuẩn thế hệ 6

Khi gọi hàm, bạn nên ghi rõ tên tham số như income_statement(period="quarter") (do tham số đầu tiên tính theo vị trí là company_type để giữ tương thích với thế hệ 5).

Lưu ý về hiệu năng: khi để mặc định period=None, thư viện phải thực hiện hai luồng truy vấn tới nguồn (một cho báo cáo năm và một cho báo cáo quý) và tự động lật hết các trang lịch sử mà nguồn có, nên có thể mất vài chục giây. Nếu chỉ phân tích theo năm hoặc theo quý, bạn hãy truyền rõ period="year" hoặc period="quarter" để giảm một nửa thời gian chờ.

Bốn mẫu biểu kế toán tự động theo loại hình doanh nghiệp

Tại Việt Nam, mỗi loại hình doanh nghiệp lập báo cáo tài chính theo một chế độ kế toán riêng. Thư viện tự động ánh xạ số liệu vào đúng cây chỉ tiêu chuẩn của từng loại hình:

Mẫu biểu kế toánGiá trị company_typeMã tiêu biểuChỉ tiêu đầu tiên trên Bảng cân đối kế toán
Doanh nghiệp phi tài chính (DN)regularFPT, HPG, VNMTài sản ngắn hạn
Tổ chức tín dụng / Ngân hàng (TCTD)bankVCB, ACB, TCBTiền mặt, vàng bạc, đá quý
Công ty chứng khoán (CTCK)securitiesSSI, HCM, VNDTài sản tài chính ngắn hạn
Doanh nghiệp bảo hiểm (DNPNT)insuranceBVH, PVI, BMITài sản ngắn hạn (kèm các chỉ tiêu nghiệp vụ bảo hiểm)

Thông thường, bạn không cần truyền company_type: thư viện tự xác định mẫu biểu dựa trên cấu trúc trường mà nguồn trả về (không đoán mò theo mã hay tên công ty). Nếu bạn truyền company_type khác với mẫu biểu thực tế của doanh nghiệp đó, hàm sẽ dừng lại và báo lỗi VNSTOCK_INPUT_COMPANY_TYPE kèm loại hình đúng, tuyệt đối không ép dữ liệu của ngân hàng vào cây chỉ tiêu của doanh nghiệp thường. Mẫu biểu thực tế đã dùng luôn được ghi tại df.attrs["template"] và df.attrs["company_type"].

So sánh bộ chỉ tiêu rút gọn và bộ chỉ tiêu VAS đầy đủ

Mỗi mẫu biểu kế toán có hai mức độ chi tiết của cây chỉ tiêu:

Tiêu chíBộ chỉ tiêu rút gọn (reduced)Bộ chỉ tiêu đầy đủ (full)
Độ sâu chỉ tiêuCác chỉ tiêu tổng hợp cấp 1 (ví dụ: Tài sản ngắn hạn, Doanh thu thuần, Lợi nhuận sau thuế)Toàn bộ các cấp chi tiết (tới từng khoản mục cấp 2, cấp 3 như Tiền, Các khoản tương đương tiền, Hàng tồn kho…)
Điều kiện áp dụngMáy chưa đăng nhập tài khoản Vnstock, hoặc tài khoản thuộc bản Cộng đồngMáy đã đăng nhập bằng khoá có Gói quyền sử dụng Vnstock còn hiệu lực
Cơ chế nạp cây chỉ tiêuTích hợp sẵn trong thư viện (không cần mạng)Tải tự động từ vnstocks.com theo khoá đã đăng nhập, xác thực chữ ký số và lưu trên bộ nhớ RAM của tiến trình

Con số tại các chỉ tiêu cấp 1 là hoàn toàn giống nhau ở cả hai bộ (vì thư viện đọc trực tiếp giá trị chỉ tiêu cấp 1 từ nguồn, không cộng ngược từ chỉ tiêu con), và số lượng kỳ lịch sử không bị cắt giới hạn ở bất kỳ bộ nào.

Khi máy chưa đủ điều kiện mở bộ chỉ tiêu đầy đủ, thư viện tự động chuyển về dùng bộ rút gọn và chỉ phát một cảnh báo DataWarning duy nhất trong suốt tiến trình:

Mã cảnh báoNguyên nhânCách khắc phục
VNSTOCK_TAXONOMY_NO_KEYMáy chưa đăng nhập tài khoản VnstockChạy lệnh vnstock login nếu bạn có Gói quyền sử dụng
VNSTOCK_TAXONOMY_KEY_REJECTEDKhoá đăng nhập hết hạn hoặc không hợp lệKiểm tra bằng vnstock status, sau đó đăng nhập lại
VNSTOCK_TAXONOMY_UNAVAILABLETạm thời chưa kết nối được tới vnstocks.comThư viện sẽ tự động thử lại sau 1 phút
VNSTOCK_TAXONOMY_MALFORMEDDữ liệu cây chỉ tiêu tải về không khớp chữ ký xác thựcKiểm tra lại kết nối mạng hoặc báo lỗi kèm df.attrs["taxonomy"]

Bạn có thể kiểm tra xem bảng dữ liệu vừa lấy đang dùng bộ chỉ tiêu nào qua thuộc tính df.attrs["taxonomy"]:

Python
df.attrs["taxonomy"]
# {'version': 'vas_v6.1', 'variant': 'full', 'origin': 'server', 'note': None}
# variant: 'full' (đầy đủ) hoặc 'reduced' (rút gọn); origin: 'server' hoặc 'floor'

Ba cách trình bày bảng dữ liệu (long, wide, time_series)

Cả ba định dạng đều chứa cùng một tập số liệu và luôn có chỉ mục (index) là RangeIndex tiêu chuẩn.

Dạng bảng dọc mặc định (format="long")

Mỗi dòng biểu diễn một chỉ tiêu tại một kỳ báo cáo. Kỳ mới nhất được xếp lên đầu; trong phạm vi mỗi kỳ, các chỉ tiêu giữ đúng thứ tự trình bày của mẫu biểu kế toán.

Tên cột (compat="v5")Tên cột (compat="v6")Kiểu dữ liệuÝ nghĩa
periodreport_periodstrKỳ báo cáo: "2025" với báo cáo năm, "2025-Q4" với báo cáo quý
iditem_idstrMã định danh cố định của chỉ tiêu (ví dụ: BS_TOTAL_ASSETS)
nameitem_namestrTên hiển thị của chỉ tiêu theo ngôn ngữ lang đã chọn
orderitem_orderintThứ tự dòng chuẩn trên mẫu biểu báo cáo tài chính
levelitem_levelintCấp độ phân cấp: 1 là chỉ tiêu tổng hợp chính, 2 và 3 là các chỉ tiêu chi tiết con
off_balanceoff_balanceboolChỉ có ở bảng cân đối kế toán: True đối với các chỉ tiêu ngoại bảng
unititem_unitstr"VNĐ" ở hồ sơ v5; "dong" hoặc "dong_per_share" (với EPS) ở hồ sơ v6
valueitem_valuefloatGiá trị số liệu, tính theo đơn vị đồng đúng như báo cáo gốc
line_codeline_codestrMã số chỉ tiêu theo thông tư kế toán (ví dụ "270" là Tổng cộng tài sản ở mẫu DN)

Ví dụ minh hoạ cấu trúc bảng ở định dạng format="long" (số liệu minh hoạ):

periodidnameorderlevelunitvalueline_code
2025BS_SHORT_TERM_ASSETSTÀI SẢN NGẮN HẠN11VNĐ1.0e+13100
2025BS_CASH_AND_PRECIOUS_METALSTiền và các khoản tương đương tiền22VNĐ2.0e+12110
2025BS_CASHTiền33VNĐ1.2e+12111

Dạng bảng ngang theo kỳ báo cáo (format="wide")

Mỗi dòng là một chỉ tiêu kế toán, mỗi cột phía sau là một kỳ báo cáo (kỳ cũ nhất nằm bên trái, kỳ mới nhất nằm bên phải giống trình bày truyền thống và thế hệ 5). Ở hồ sơ v5, các cột thông tin cố định đầu bảng gồm id, item, order, level, unit, line_code.

Dạng chuỗi thời gian phục vụ tính toán (format="time_series")

Mỗi dòng là một kỳ báo cáo, còn mỗi cột là một mã chỉ tiêu (IS_NET_REVENUE, IS_NET_PROFIT_AFTER_TAX…). Cột đầu tiên chứa kỳ báo cáo. Định dạng này rất thuận tiện khi bạn cần vẽ biểu đồ chuỗi thời gian hoặc đưa thẳng vào công thức tính toán vector hoá trong pandas.

Quy ước về đơn vị tiền tệ và dấu âm/dương của số liệu

  • Đơn vị tiền tệ: mọi khoản mục tiền tệ đều tính bằng đồng (VNĐ) đúng theo báo cáo gốc; riêng chỉ tiêu Lãi trên cổ phiếu (EPS) tính bằng đồng/cổ phiếu.
  • Quy ước dấu âm/dương: các khoản mục mang bản chất giảm trừ (như giá vốn hàng bán, chi phí bán hàng, chi phí quản lý doanh nghiệp, chi phí thuế TNDN…) đều được chuẩn hoá mang dấu âm, giống thế hệ 5. Nhờ đó, bạn có thể cộng trực tiếp các chỉ tiêu thành phần để ra chỉ tiêu tổng mà không sợ nhầm phép cộng/trừ.
  • Quy tắc dấu được định nghĩa tường minh cho từng mã dòng trên từng mẫu biểu, không suy đoán cảm tính theo tên gọi.

Siêu dữ liệu đi kèm kết quả (df.attrs)

Mỗi bảng báo cáo tài chính trả về đều đính kèm từ điển df.attrs chứa thông tin kiểm toán và ngữ cảnh truy vấn:

Khoá trong df.attrsÝ nghĩa chi tiết
template, company_typeMã mẫu biểu (DN, TCTD, CTCK, DNPNT) và loại hình doanh nghiệp tương ứng
statementTên loại báo cáo: balance_sheet, income_statement hoặc cash_flow
taxonomy, taxonomy_versionThông tin phiên bản và độ sâu (full / reduced) của cây chỉ tiêu VAS đã dùng
report_periodsTổng số kỳ báo cáo có mặt trong bảng kết quả
report_period_askedDanh sách loại kỳ đã truy vấn tới nguồn: ["year"], ["quarter"] hoặc cả hai
empty_periodsDanh sách các kỳ mà nguồn có liệt kê tên kỳ nhưng toàn bộ số liệu đều rỗng (đã được lọc bỏ khỏi bảng)
identitiesKết quả kiểm tra tự động các đẳng thức kế toán của mẫu biểu (xem mục ngay dưới)
unmapped_keysCác trường dữ liệu lạ do nguồn gửi về nhưng chưa có trong từ điển chỉ tiêu hiện hành
format, language, drop_emptyGiá trị các tham số định dạng đã dùng trong lời gọi hàm
profile, schema_changesHồ sơ tên cột (v5 / v6) và danh sách mã thay đổi cấu trúc so với thế hệ 5

Cơ chế tự động kiểm tra đẳng thức kế toán

Mỗi khi bạn gọi hàm lấy báo cáo tài chính, thư viện tự động kiểm tra chéo các đẳng thức kế toán bắt buộc của mẫu biểu trên từng kỳ (ví dụ: Tổng tài sản = Tài sản ngắn hạn + Tài sản dài hạn, hoặc Lợi nhuận sau thuế = Lợi nhuận sau thuế của cổ đông công ty mẹ + Lợi nhuận sau thuế của cổ đông không kiểm soát). Kết quả đối chiếu được lưu tại df.attrs["identities"]:

Python
df.attrs["identities"]
# ví dụ minh hoạ: {'checked': 594, 'passed': 594, 'known_breaks': 0, 'failed': []}
  • failed: liệt kê chi tiết từng đẳng thức không khớp kèm kỳ báo cáo và phát cảnh báo DataWarning mã VNSTOCK_VAS_IDENTITY. Lưu ý rằng thư viện giữ nguyên con số gốc mà nguồn gửi về, tuyệt đối không tự ý sửa số để ép đẳng thức phải khớp.
  • known_breaks: ghi nhận những trường hợp lệch đẳng thức đã biết trước do sự thay đổi thông tư kế toán ở các giai đoạn lịch sử cũ (không phát cảnh báo gây nhiễu).
  • unmapped_keys: nếu nguồn dữ liệu bổ sung trường mới chưa có trong cây chỉ tiêu, thư viện sẽ ghi vào df.attrs["unmapped_keys"] và báo VNSTOCK_VAS_UNMAPPED thay vì âm thầm bỏ qua.

Việc kiểm tra đẳng thức giúp phát hiện chỗ số liệu đọc về bị lệch, không bảo đảm số liệu chính xác tuyệt đối và không thay thế việc đối chiếu báo cáo gốc do doanh nghiệp công bố khi bạn đưa ra quyết định quan trọng.

Những lưu ý khi đọc số liệu

  • Độ dài lịch sử dữ liệu: tuỳ nguồn và tuỳ mã. Một số kỳ quá cũ chỉ có dữ liệu từng phần; những kỳ hoàn toàn không có số liệu sẽ được lược bỏ và ghi tên kỳ vào df.attrs["empty_periods"].
  • Chỉ tiêu có thể để trống: khi nguồn chưa có số liệu cho một chỉ tiêu ở một loại kỳ (chẳng hạn EPS ở báo cáo quý), dòng đó để trống thay vì được ước tính.
  • Số liệu báo cáo quý là số riêng của từng quý, không phải số luỹ kế từ đầu năm: vì vậy bạn có thể cộng 4 quý liên tiếp để tính số liệu trượt 12 tháng gần nhất (TTM).
  • Vốn chủ sở hữu (BS_EQUITY): bao gồm cả phần lợi ích của cổ đông không kiểm soát. Để lấy riêng vốn chủ sở hữu của cổ đông công ty mẹ, bạn lấy BS_EQUITY trừ đi BS_MINORITY_INTEREST.
  • Lưu ý khi tính chỉ số trên mỗi cổ phiếu (như BVPS, EPS): khoản mục Vốn điều lệ trên báo cáo tài chính lịch sử chưa phản ánh các đợt phát hành chia tách cổ phiếu diễn ra sau ngày lập báo cáo. Khi ghép với thị giá hiện tại, bạn nên lấy số lượng cổ phiếu đang lưu hành (outstanding_shares) từ hàm Reference("fhsc").company(mã).listing().
  • Dòng trống bất thường: ở một số kỳ, một khoản mục có thể được trình bày gộp vào khoản mục lân cận; khi thấy một dòng trống bất thường, hãy đối chiếu với báo cáo gốc của doanh nghiệp.
  • Nguồn tạm không phục vụ: khi nguồn ngoài giờ phục vụ hoặc đang bảo trì, yêu cầu truy vấn sẽ nhận mã lỗi VNSTOCK_SOURCE_UNAVAILABLE.

Tự tính chỉ số tài chính minh bạch công thức với vnstock_quant

Thay vì dùng bảng chỉ số tính sẵn theo công thức riêng của từng nguồn, thư viện vnstock_quant 1.x giúp bạn tự tính toàn bộ nhóm chỉ số tài chính ngay trên máy từ ba báo cáo chuẩn VAS. Bạn cài đặt vnstock_quant vào cùng môi trường làm việc:

Shell
python -m pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock_quant>=1.0,<2"

Sau đó, sử dụng fa.Dataset.load() để nạp báo cáo tài chính và tính các chỉ số cần thiết:

Python
from vnstock_quant import fa

ds = fa.Dataset.load("FPT", source="fhsc", prices=False)
ratios = fa.ratios(
    ds,
    ids=["RT_PRT_ROE", "RT_PRT_ROA", "RT_LQD_CR", "RT_LEV_DE"],
    period="year",
    format="time_series",
)
Lưu ý chuẩn bị đủ dữ liệu đầu vào

Nhiều công thức chỉ số tài chính chuyên sâu cần các khoản mục cấp 2, cấp 3 thuộc bộ chỉ tiêu đầy đủ. Các chỉ số định giá (như P/E, P/B, EV/EBITDA) cần thêm chuỗi giá đóng cửa chưa điều chỉnh và số lượng cổ phiếu lưu hành theo ngày; nếu thiếu dữ liệu thị trường, kết quả sẽ ghi nhận trạng thái MISSING_MARKET thay vì tự ước tính. Tương tự, các chỉ số đòi hỏi dữ liệu thuyết minh báo cáo tài chính sẽ trả về trạng thái MISSING_INPUT khi chưa có các dòng NT_*.

Xem hướng dẫn chi tiết cách tính trượt 12 tháng (TTM), tra cứu công thức từng chỉ số và đọc nguyên nhân ô trống tại tài liệu Chỉ số tài chính (vnstock_quant) và Quyền dùng và hạn mức.

Các mã lỗi thường gặp và cách xử lý

Mã lỗiKhi nào xuất hiệnCách khắc phục
VNSTOCK_INPUT_SOURCEChưa chỉ định nguồn dữ liệuTruyền source="<nguồn>" hoặc đặt mặc định qua vnstock.sources.use("<nguồn>", route="fundamental.equity.*")
VNSTOCK_INPUT_REPORT_PERIODGiá trị period không hợp lệTruyền period="year", period="quarter", hoặc bỏ trống để lấy cả hai
VNSTOCK_INPUT_COMPANY_TYPEcompany_type truyền vào lệch với mẫu biểu thực tế của doanh nghiệpBỏ tham số company_type để thư viện tự nhận diện, hoặc truyền đúng loại hình được gợi ý trong thông báo lỗi
VNSTOCK_INPUT_TABLE_FORMATGiá trị format không hợp lệChọn một trong ba định dạng: "long", "wide" hoặc "time_series"
VNSTOCK_INPUT_PARAMTruyền tham số không còn hỗ trợ (như orient= của thế hệ 5)Đổi sang dùng tham số format=
VNSTOCK_VAS_TEMPLATE_UNSUPPORTEDMẫu biểu đặc thù chưa có cây chỉ tiêu tương ứngĐọc phản hồi gốc bằng vnstock_oapi
VNSTOCK_ROUTE_UNSUPPORTEDGọi các hàm note(), financial_health(), filing()Các dữ liệu này hiện chưa có trên cổng Open API của thế hệ 6

Giới hạn phạm vi và những việc thư viện không làm

  • Không tự nội suy hay điền số ước tính cho những chỉ tiêu mà nguồn không gửi (chỉ tiêu thiếu số liệu từ nguồn sẽ được để trống NaN).
  • Không tự ý chỉnh sửa con số gốc để ép các đẳng thức kế toán phải khớp (mọi sai lệch từ dữ liệu nguồn đều được ghi nhận trung thực trong df.attrs["identities"]).
  • Không tự động lưu báo cáo xuống ổ cứng: nếu muốn lưu trữ lâu dài, bạn chủ động xuất DataFrame ra tệp hoặc sử dụng vnstock_pipeline.
  • Không đưa ra đánh giá, xếp hạng hay khuyến nghị đầu tư dựa trên số liệu báo cáo tài chính.