Báo cáo tài chính
Mục lục
Trang này viết cho vnstock v6.0.0rc2, bản thử nghiệm. Tên hàm, tham số và cột dữ liệu có thể còn đổi trước ngày phát hành; khi cài, ghi rõ số phiên bản như ở trang Cài đặt. Bản đang phát hành chính thức là v5.0.1, xem tài liệu bản đó.
Fundamental đọc ba báo cáo tài chính chính của một mã cổ phiếu: 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ệ. Thư viện đưa số liệu về một bộ chỉ tiêu chung theo chuẩn mực kế toán Việt Nam (VAS).
Mỗi chỉ tiêu có mã cố định (BS_TOTAL_ASSETS, IS_NET_REVENUE…), giữ nguyên như thế hệ 5, nên đoạn mã bạn viết cho một mã
cổ phiếu dùng được cho mã khác cùng loại hình.
from vnstock import Fundamental
fpt = Fundamental().equity("FPT")
df = fpt.income_statement(period="year", source="fhsc")Phần báo cáo tài chính đang ở mức thử nghiệm trong bản 6.0.0rc2. Mã chỉ tiêu giữ như thế hệ 5; tên tham số và các khoá trong df.attrs còn có thể đổi trước ngày phát hành.
Hàm có trong bản này
| Hàm | Chức năng | Nguồn |
|---|---|---|
balance_sheet() | Bảng cân đối kế toán | fhsc |
income_statement() | Báo cáo kết quả kinh doanh | fhsc |
cash_flow() | Báo cáo lưu chuyển tiền tệ | fhsc |
ratio(), note(), financial_health(), filing() | Chưa có ở thế hệ 6 | Gọi thì nhận UnsupportedError mã VNSTOCK_ROUTE_UNSUPPORTED |
Chỉ số tài chính tính từ chính các báo cáo đã chuẩn hoá nằm ở vnstock_quant, không lấy bảng chỉ số do nguồn tự tính.
Cách gọi
from vnstock import Fundamental
fun = Fundamental()
fun.equity("VCB").balance_sheet(period="year", source="fhsc") # gắn mã trước
fun.equity.balance_sheet("VCB", period="year", source="fhsc") # mã là tham số đầu
fun.equity("SSI").cash_flow(period="quarter", format="wide", source="fhsc")Thế hệ 6 không có nguồn mặc định. Truyền source= cho từng lời gọi, hoặc đặt một lần cho cả nhóm:
import vnstock
vnstock.sources.use("fhsc", route="fundamental.equity.*")Thiếu nguồn thì nhận InputError mã VNSTOCK_INPUT_SOURCE. Xem Chọn nguồn.
Tham số
balance_sheet(company_type=None, period=None, lang="vi", drop_empty=False, format="long", *, source=None, compat=None)
income_statement(...) # cùng tham số
cash_flow(...) # cùng tham số| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
company_type | str hoặc None | None | Loại hình doanh nghiệp. None hoặc "auto" để thư viện tự nhận theo dữ liệu nguồn gửi. Nhận "regular" (cũng viết "generic", "dn"), "bank" ("banking", "tctd"), "securities" ("ctck"), "insurance" ("dnpnt"). Tên cũ com_type vẫn nhận |
period | str hoặc None | None | "year" (cũng viết "yearly", "annual", "y") hoặc "quarter" ("quarterly", "q"). None lấy cả năm và quý như thế hệ 5 |
lang | str | "vi" | Ngôn ngữ tên chỉ tiêu: "vi" hoặc "en". Chỉ đổi cột tên, không đổi mã chỉ tiêu |
drop_empty | bool | False | Bỏ chỉ tiêu không có số khác 0 ở mọi kỳ |
format | str | "long" | "long", "wide" hoặc "time_series", xem Hình dạng bảng |
source | str | Nguồn cho lời gọi này | |
compat | str | "v5" | "v5": tên cột như thế hệ 5; "v6": tên cột chuẩn thế hệ 6 |
Ghi tên tham số khi gọi: income_statement(period="quarter"). Tham số đầu tiên theo vị trí là company_type,
giống thế hệ 5.
period=None gửi hai lần gọi tới nguồn, một cho kỳ năm và một cho kỳ quý. Mỗi lần gọi lấy hết các trang mà nguồn
có, nên một báo cáo theo quý có thể mất vài chục giây. Chỉ cần một loại kỳ thì truyền period= để đỡ một lần gọi.
Bốn mẫu biểu
Mỗi loại hình doanh nghiệp lập báo cáo theo một mẫu biểu riêng. Thư viện dùng đúng cây chỉ tiêu của mẫu biểu đó:
| Mẫu biểu | company_type | Ví dụ mã | Bảng cân đối bắt đầu bằng |
|---|---|---|---|
| Doanh nghiệp (DN) | regular | FPT, HPG, VNM | Tài sản ngắn hạn |
| Tổ chức tín dụng (TCTD) | bank | VCB, ACB, TCB | Tiền mặt, vàng bạc, đá quý |
| Công ty chứng khoán (CTCK) | securities | SSI, HCM, VND | Tài sản tài chính ngắn hạn |
| Doanh nghiệp bảo hiểm (DNPNT) | insurance | BVH, PVI, BMI | Tài sản ngắn hạn, kèm các dòng riêng của bảo hiểm |
Thường bạn không cần truyền company_type. Thư viện nhận mẫu biểu theo các trường mà nguồn gửi về, không đoán theo mã
hay theo tên công ty. Truyền một loại hình khác với mẫu biểu nguồn trả thì nhận InputError mã
VNSTOCK_INPUT_COMPANY_TYPE, kèm loại hình đúng. Thư viện không đọc báo cáo của mẫu biểu này lên cây của mẫu biểu
khác. Mẫu biểu và loại hình đã dùng ghi ở df.attrs["template"], df.attrs["company_type"].
Bộ chỉ tiêu đầy đủ và rút gọn
Mỗi mẫu biểu có hai bộ chỉ tiêu:
| Rút gọn | Đầy đủ | |
|---|---|---|
| Chỉ tiêu | Chỉ tiêu cấp 1 (ví dụ "Tài sản ngắn hạn", "Doanh thu thuần") | Mọi cấp, tới chỉ tiêu chi tiết như "Tiền", "Các khoản tương đương tiền" |
| Dành cho | Máy chưa đăng nhập, hoặc khoá chưa có Gói quyền sử dụng | Khoá có Gói quyền sử dụng còn hiệu lực |
| Lấy ở đâu | Có sẵn trong thư viện | Thư viện tải từ vnstocks.com theo khoá đã đăng nhập, kiểm chữ ký rồi giữ trong bộ nhớ |
Giá trị của chỉ tiêu cấp 1 như nhau ở hai bộ, vì thư viện đọc thẳng từ nguồn, không cộng từ chỉ tiêu con. Số kỳ không bị cắt ở bộ nào.
Bộ đầy đủ chỉ ở trong bộ nhớ của tiến trình, không ghi xuống đĩa. Thư viện tải lại sau vnstock login hoặc
vnstock logout. Khi không dùng được bộ đầy đủ, thư viện dùng bộ rút gọn và cảnh báo một lần mỗi tiến trình bằng
DataWarning:
| Mã cảnh báo | Nghĩa | Cách xử lý |
|---|---|---|
VNSTOCK_TAXONOMY_NO_KEY | Máy chưa đăng nhập vnstock | vnstock login |
VNSTOCK_TAXONOMY_KEY_REJECTED | vnstocks.com từ chối khoá | vnstock status, rồi đăng nhập lại |
VNSTOCK_TAXONOMY_UNAVAILABLE | Chưa tới được vnstocks.com | Thư viện tự thử lại sau một phút |
VNSTOCK_TAXONOMY_MALFORMED | Tài liệu nhận được không qua kiểm tra chữ ký | Báo lỗi kèm df.attrs["taxonomy"] |
Bộ đang dùng ghi ở df.attrs["taxonomy"]:
df.attrs["taxonomy"]
# {'version': 'vas_v6.1', 'variant': 'full', 'origin': 'server', 'note': None}
# variant: 'full' hoặc 'reduced'; origin: 'server' (vnstocks.com) hoặc 'floor' (bản có sẵn trong thư viện)Hình dạng bảng
Ba dạng chứa cùng số liệu. Chỉ mục luôn là RangeIndex.
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 trên mẫu biểu.
Cột (compat="v5") | Cột (compat="v6") | Kiểu | Ý nghĩa |
|---|---|---|---|
period | report_period | str | Kỳ: "2025" với kỳ năm, "2025-Q4" với kỳ quý |
id | item_id | str | Mã chỉ tiêu, ví dụ BS_TOTAL_ASSETS |
name | item_name | str | Tên chỉ tiêu theo lang |
order | item_order | int | Thứ tự trên mẫu biểu |
level | item_level | int | Cấp: 1 là chỉ tiêu chính, 2 và 3 là chỉ tiêu con |
off_balance | off_balance | bool | Chỉ ở bảng cân đối: True với chỉ tiêu ngoài bảng |
unit | item_unit | str | "VNĐ" ở hồ sơ v5; "dong" hoặc "dong_per_share" (lãi trên cổ phiếu) ở hồ sơ v6 |
value | item_value | float | Số liệu, theo đồng như trên báo cáo |
line_code | line_code | str | Mã số chỉ tiêu trên mẫu biểu ("270" là tổng cộng tài sản ở mẫu DN); trống khi chưa khai |
Minh hoạ cấu trúc (số liệu giả định):
| period | id | name | order | level | unit | value | line_code |
|---|---|---|---|---|---|---|---|
| 2025 | BS_SHORT_TERM_ASSETS | TÀI SẢN NGẮN HẠN | 1 | 1 | VNĐ | 1.0e+13 | 100 |
| 2025 | BS_CASH_AND_PRECIOUS_METALS | Tiền và các khoản tương đương tiền | 2 | 2 | VNĐ | 2.0e+12 | 110 |
| 2025 | BS_CASH | Tiền | 3 | 3 | VNĐ | 1.2e+12 | 111 |
format="wide"
Mỗi dòng là một chỉ tiêu, mỗi kỳ là một cột. Kỳ cũ nhất bên trái như thế hệ 5. Ở hồ sơ v5, các cột đầu là id,
item, order, level, unit, line_code.
format="time_series"
Mỗi dòng là một kỳ, mỗi chỉ tiêu là một cột đặt tên theo mã (IS_NET_REVENUE…). Cột đầu là kỳ báo cáo. Dạng này hợp
để tính toán và vẽ chuỗi thời gian.
Dấu và đơn vị
- Số tiền theo đồng, đúng như báo cáo in. Lãi trên cổ phiếu theo đồng trên cổ phiếu.
- Các khoản mà mẫu biểu in thành số lớn hơn 0 rồi trừ đi (giá vốn, chi phí bán hàng, chi phí thuế…) mang dấu âm, như thế hệ 5. Vì vậy cộng các chỉ tiêu con là ra chỉ tiêu tổng, không cần đổi dấu.
- Việc đổi dấu được khai sẵn cho từng dòng của từng mẫu biểu. Thư viện không đoán dấu theo tên chỉ tiêu.
Thông tin kèm kết quả
Khoá df.attrs | Ý nghĩa |
|---|---|
template, company_type | Mẫu biểu (DN, TCTD, CTCK, DNPNT) và loại hình |
statement | balance_sheet, income_statement hoặc cash_flow |
taxonomy, taxonomy_version | Bộ chỉ tiêu đã dùng, xem mục trên |
report_periods | Số kỳ trong bảng |
report_period_asked | Loại kỳ đã gửi tới nguồn: ["year"], ["quarter"] hoặc cả hai |
empty_periods | Các kỳ nguồn có liệt kê nhưng không gửi số nào. Thư viện bỏ các kỳ này khỏi bảng |
identities | Kết quả kiểm đẳng thức của mẫu biểu, xem mục dưới |
unmapped_keys | Trường nguồn gửi mà bộ chỉ tiêu chưa có |
format, language, drop_empty | Tham số đã dùng |
profile, schema_changes | Hồ sơ tên cột và các thay đổi so với thế hệ 5 |
Kiểm tra số liệu
Mỗi lời gọi chạy các đẳng thức của mẫu biểu trên mọi kỳ, ví dụ tổng cộng tài sản bằng tài sản ngắn hạn cộng tài sản
dài hạn, hay lợi nhuận sau thuế bằng phần của công ty mẹ cộng phần của cổ đông không kiểm soát. Kết quả nằm ở
df.attrs["identities"]:
df.attrs["identities"]
# {'checked': 594, 'passed': 594, 'known_breaks': 0, 'failed': []}failedliệt kê từng đẳng thức hỏng kèm kỳ, kèm cảnh báoDataWarningmãVNSTOCK_VAS_IDENTITY. Số trong bảng là số nguồn gửi; thư viện không sửa số để đẳng thức khớp.known_breaksđếm những chỗ hỏng đã biết trước vì mẫu biểu đổi theo năm, ví dụ các năm trước khi thông tư hiện hành có hiệu lực. Những chỗ này không cảnh báo.- Trường nguồn gửi mà bộ chỉ tiêu chưa có thì không bị bỏ lặng lẽ: chúng nằm ở
df.attrs["unmapped_keys"], kèm cảnh báoVNSTOCK_VAS_UNMAPPED.
Cách ánh xạ từng trường của nguồn về mã chỉ tiêu được kiểm bằng hai cách:
- chạy các đẳng thức trên dữ liệu thật của nhiều công ty thuộc cả bốn mẫu biểu;
- đối chiếu từng dòng theo mã số chỉ tiêu với báo cáo tài chính hợp nhất đã kiểm toán, đọc từ tệp PDF doanh nghiệp công bố.
Việc kiểm tra cho biết thư viện đọc đúng số nguồn gửi; nó không thay được việc bạn đối chiếu với báo cáo gốc khi cần ra quyết định.
Điều cần biết về dữ liệu nguồn
- Lịch sử: với nhiều mã, nguồn có kỳ năm từ giữa thập niên 2000 và kỳ quý từ khoảng 2009–2013. Kỳ cũ có thể chỉ
có một phần báo cáo; những kỳ không có số nào nằm ở
df.attrs["empty_periods"]. - Lãi trên cổ phiếu có ở kỳ năm, chưa có ở kỳ quý.
- Phải thu về cho vay (mẫu DN, mã số 135 và 215): ở một số kỳ, nguồn cộng khoản này vào phải thu khác (mã số 136, 216) và để trống dòng phải thu về cho vay.
- Chỉ tiêu ngoài bảng của ngân hàng và công ty chứng khoán (bảo lãnh, cam kết, tài sản nhận giữ hộ…) nguồn chưa gửi.
fhscchỉ trả lời trong khoảng 06:00 tới 21:00 giờ Việt Nam. Ngoài giờ đó thư viện báoVNSTOCK_SOURCE_UNAVAILABLE.
Lỗi hay gặp
| Mã | Khi nào | Cách sửa |
|---|---|---|
VNSTOCK_INPUT_SOURCE | Chưa chọn nguồn | source="<nguồn>" hoặc vnstock.sources.use("<nguồn>", route="fundamental.equity.*") |
VNSTOCK_INPUT_REPORT_PERIOD | period không phải năm hay quý | period="year", period="quarter", hoặc bỏ trống |
VNSTOCK_INPUT_COMPANY_TYPE | company_type không khớp mẫu biểu nguồn trả | Bỏ company_type, hoặc dùng loại hình ghi trong thông báo |
VNSTOCK_INPUT_TABLE_FORMAT | format không hợp lệ | long, wide hoặc time_series |
VNSTOCK_INPUT_PARAM | Tham số hàm không nhận, ví dụ orient= của thế hệ 5 | Dùng format= |
VNSTOCK_VAS_TEMPLATE_UNSUPPORTED | Mẫu biểu chưa có cây chỉ tiêu | Lấy dữ liệu thô bằng vnstock_oapi |
VNSTOCK_ROUTE_UNSUPPORTED | ratio(), note(), financial_health(), filing() | Chưa có ở thế hệ 6 |
Thư viện không làm gì
- Không tự tính hay bù số nguồn không gửi. Chỉ tiêu nguồn không có thì để trống.
- Không sửa số để đẳng thức khớp. Chỗ lệch được ghi lại để bạn xem.
- Không lưu báo cáo xuống đĩa. Muốn giữ thì tự ghi
dfra tệp, hoặc dùngvnstock_pipeline. - Không đưa ra nhận định hay khuyến nghị dựa trên số liệu.