# Vnstock - Hệ sinh thái công cụ Python cho dữ liệu và nghiên cứu thị trường tài chính Việt Nam | Full Documentation Context > Vnstock là hệ sinh thái công cụ Python giúp bạn tự kết nối, chuẩn hoá và phân tích dữ liệu thị trường tài chính Việt Nam, chạy trên hạ tầng do bạn kiểm soát. > > Vnstock là hệ sinh thái công cụ Python cho quy trình dữ liệu và nghiên cứu thị trường tài chính Việt Nam: kết nối và chuẩn hoá dữ liệu từ nguồn bên thứ ba, chỉ báo kỹ thuật, xử lý tin tức, pipeline dữ liệu và bộ hướng dẫn cho AI Agent. Phần mềm chạy trên thiết bị hoặc máy chủ do bạn kiểm soát; truy vấn đi thẳng từ đó tới nguồn. Bản Cộng đồng công khai mã nguồn theo giấy phép riêng; bản mở rộng dành cho người tài trợ. Vnstock cấp quyền sử dụng phần mềm, không cấp quyền sử dụng dữ liệu của nguồn và không vận hành kho dữ liệu thị trường để bán lại. > Vnstock is an ecosystem of Python tools for financial-market data and research workflows in Vietnam: connectors and normalization for third-party sources, technical indicators, news processing, data pipelines and guides for AI agents. The software runs on infrastructure you control; market queries go straight from there to the source. The Community edition is source-available under Vnstock's own licence; the extended edition is for sponsors. Vnstock licenses software, does not license source data, and does not operate a centralized market-data store for resale. All data originates from and is owned by the respective third-party sources. Users must comply with each data source's terms of service. ## Vnstock là gì / không là gì - Truy vấn dữ liệu thị trường xuất phát từ runtime của người dùng và đi thẳng tới nguồn, trực tiếp hoặc qua proxy do người dùng tự cấu hình. Không có máy chủ trung chuyển dữ liệu thị trường của Vnstock. - Vnstock không vận hành kho dữ liệu thị trường tập trung để bán lại hoặc phân phối nội dung nguồn. - Dịch vụ do Vnstock vận hành xử lý dữ liệu tài khoản, thanh toán, giấy phép, thiết bị, hạn mức, bảo mật và đo lường kỹ thuật theo Chính sách quyền riêng tư. - Vnstock cấp quyền sử dụng phần mềm và tính năng dành cho người tài trợ. Quyền đó không tạo ra quyền khai thác, lưu trữ, hiển thị hay phân phối dữ liệu của nguồn. - Vnstock bảo lưu quyền đối với mã nguồn, schema, taxonomy, mapping, tài liệu, thiết kế và nhãn hiệu; không tuyên bố sở hữu sự kiện, số liệu hay nội dung nguồn chỉ vì đã chuẩn hoá chúng. - Vnstock là công cụ của người viết công cụ (tool builder): không phải data vendor, không phải đơn vị tư vấn đầu tư, không phải sàn hay công ty môi giới, không phải nguồn tin thị trường chính thức. Kết quả tính toán và output AI không phải khuyến nghị đầu tư. # Library Documentation & User Guides ## Document: Dòng lệnh cho server và Colab Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member/cai-dat-go-loi/cai-dat-nang-cao](/onboard-member/cai-dat-go-loi/cai-dat-nang-cao). --- ## Document: Giải quyết lỗi thường gặp Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/docs/vnstock-insider-api/go-loi-va-cau-hoi-thuong-gap](/docs/vnstock-insider-api/go-loi-va-cau-hoi-thuong-gap). --- ## Document: Môi trường và thư viện phụ thuộc Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member/cai-dat-go-loi/moi-truong-python](/onboard-member/cai-dat-go-loi/moi-truong-python). --- ## Document: Trình cài giao diện, từng bước Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member/cai-dat-go-loi/cai-dat-phan-mem](/onboard-member/cai-dat-go-loi/cai-dat-phan-mem). --- ## Document: Trung tâm hướng dẫn thành viên Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard-member](/onboard-member). --- ## Document: Agent Skills Hub Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/agent-skills-hub](/agent-skills-hub). --- ## Document: Cài Python lần đầu Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/cai-dat-moi-truong-python](/onboard/cai-dat-moi-truong-python). --- ## Document: Chạy thử trên Colab Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/trai-nghiem-vnstock](/onboard/trai-nghiem-vnstock). --- ## Document: Trung tâm hướng dẫn Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard](/onboard). --- ## Document: Vibe Coding với Vnstock Trang này chỉ là lối vào từ cây tài liệu. Nội dung đầy đủ nằm tại [/onboard/vibe-coding](/onboard/vibe-coding). --- ## Document: Dữ liệu cổ phiếu
Bảng thông tin dưới đây mô tả về độ phủ (coverage) của dữ liệu có thể truy xuất từ Vnstock3. Lưu ý: Vnstock3 chạy trên máy của bạn, gửi truy vấn thẳng tới các API truy cập công khai của công ty chứng khoán và tải dữ liệu vào môi trường Python. Dữ liệu truy xuất qua Vnstock3 phản ánh đúng dữ liệu đang được cập nhật trên website gốc. Thông tin tần suất cập nhật dựa vào kinh nghiệm quan sát các thay đổi trong đặc tính và cập nhật của dữ liệu.
| Nhóm thông tin | Lớp | Mục | Hàm | Tần suất cập nhật | Nguồn truy xuất | | ------------------- | ------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Danh sách niêm yết | Listing | [Tất cả mã](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `all_symbols()` | - | VCI | | | | [Tất cả mã chia theo sàn](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_exchange()` | - | VCI | | | | [Tất cả mã chia theo nhóm](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_group('VN30')` | - | VCI | | | | [Tất cả mã chia theo ngành](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `symbols_by_industries()` | - | VCI | | | | [Danh sách ngành icb](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#a-lop-co-phieu) | `industries_icb()` | - | VCI | | | | [Danh sách mã CK quốc tế](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#4-tim-kiem) | `search_symbol_id('USD')` | trong phiên, theo độ trễ của nguồn | MSN | | Thông tin công ty | Company | [Tổng quan](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `overview()` | - | TCBS | | | | [Hồ sơ công ty](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `profile()` | - | TCBS | | | | [Cổ đông lớn](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `shareholders()` | - | TCBS | | | | [Lãnh đạo](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `officers()` | - | TCBS | | | | [Công ty con](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `subsidiaries()` | - | TCBS | | | | [Cổ tức](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `dividends()` | - | TCBS | | | | [Giao dịch nội bộ](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `insider_deals()` | - | TCBS | | | | [Sự kiện](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `events()` | - | TCBS | | | | [Tin tức](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference#c-lop-thong-tin-doanh-nghiep) | `news()` | - | TCBS | | Báo cáo tài chính | Finance | Báo cáo kết quả kinh doanh | `income_statement()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bao-cao-ket-qua-kinh-doanh), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bao-cao-ket-qua-kinh-doanh) | | | | Bảng cân đối kế toán | `balance_sheet()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bang-can-doi-ke-toan), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bang-can-doi-ke-toan) | | | | Báo cáo lưu chuyển tiền tệ | `cash_flow()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#bao-cao-luu-chuyen-tien-te), [TCBS](/docs/vnstock/bao-cao-tai-chinh#bao-cao-luu-chuyen-tien-te) | | | | Chỉ số tài chính | `ratio()` | Tháng đầu tiên mỗi quý. Chậm so với thông tin công bố trên website UBCK trong 1 tuần. | [VCI](/docs/vnstock/bao-cao-tai-chinh#chi-so-tai-chinh), [TCBS](/docs/vnstock/bao-cao-tai-chinh#chi-so-tai-chinh) | | Giá chứng khoán | Quote | Giá lịch sử (đồ thị nến) | `history(start='2020-01-01', end='2024-12-31')` | Trong phiên theo độ trễ của nguồn, chi tiết đến cấp độ phút | [VCI](/docs/vnstock/thong-ke-gia-lich-su#gia-lich-su-ohlcv), TCBS | | | | Khớp lệnh trong ngày | `intraday(symbol='ACB', show_log=False)` | Trong phiên theo từng giao dịch, chi tiết đến cấp độ giây, theo độ trễ của nguồn | [VCI](/docs/vnstock/thong-ke-gia-lich-su#du-lieu-khop-lenh-intraday), TCBS | | | | Khối lượng giao dịch theo bước giá. | `price_depth('ACB')` | Trong phiên, theo độ trễ của nguồn | VCI, TCBS | | Thông tin Giao dịch | Trading | Thông tin bảng giá | `price_board(['ACB'])` | Trong phiên, theo độ trễ của nguồn | [VCI](/docs/vnstock/du-lieu-thi-truong-market-data), TCBS | --- ## Document: Lịch sử phiên bản ## 2026-09-06 > Cập nhật phiên bản Vnstock 4.0.8 **Thay đổi cần lưu ý** * **Loại bỏ cấu hình proxy**: Gỡ bỏ các tham số `proxy_config`, `proxy_mode` và `proxy_list` khỏi `vnstock.explorer` để loại bỏ cấu hình dư thừa và đảm bảo tính ổn định, nhất quán khi kết nối với máy chủ. * **Ngừng hỗ trợ `random_agent`**: Tham số này không còn tác dụng (sẽ hiện cảnh báo nếu dùng). Header nay được giữ ổn định. Khi cần tùy chỉnh, hãy dùng `get_headers(browser=..., platform=...)`. **Cải thiện** * Cập nhật chuỗi User-Agent theo các phiên bản trình duyệt hiện hành, đối chiếu ngày 06/09/2026. Bổ sung cấu hình cho Linux — môi trường phổ biến khi chạy thư viện trên máy chủ. * Đơn giản hoá tầng gửi yêu cầu trong `vnstock.core.utils.client`, giảm số nhánh xử lý và giúp thông báo lỗi dễ đọc hơn. **Tài liệu & giấy phép** * Làm rõ điều kiện giấy phép trong README: bản công khai mã nguồn trên GitHub theo giấy phép riêng, miễn phí cho mục đích cá nhân, học tập và nghiên cứu. Đây không phải giấy phép nguồn mở theo chuẩn OSI; phân phối lại và mục đích thương mại cần văn bản chấp thuận từ tác giả. * Bổ sung phần miễn trừ trách nhiệm và điều kiện giấy phép cho bản tiếng Anh của README, trước đây chỉ có ở phần tiếng Việt. * Bổ sung tuyên bố Vnstock không liên kết, không được tài trợ hay chứng thực bởi bất kỳ tổ chức nào được nhắc tới trong tài liệu và mã nguồn. Vnstock cấp quyền sử dụng phần mềm, không cấp quyền sử dụng dữ liệu; điều kiện của từng nguồn do bạn tự kiểm tra và tuân thủ. * Bổ sung ghi chú về dữ liệu ẩn danh của môi trường chạy được ghi nhận nhằm cải thiện hiệu năng và độ ổn định. ## 2026-05-16 > Cập nhật phiên bản Vnstock 4.0.3 **Bổ sung** * **Giao dịch Trái phiếu**: Bổ sung cấu trúc dữ liệu trái phiếu vào tầng giao diện Unified UI, đồng nhất kiến trúc với bản `vnstock_data` và bổ sung các hàm ohlcv, trades, quote. * **InstrumentType Enum**: Thêm phân loại định danh chứng khoán chuyên sâu để chuẩn hoá việc nhận diện các loại tài sản tài chính. **Thay đổi & Cải thiện** * Bổ sung danh sách các chỉ số index từ HNX, UPCOM và cải thiện khả năng nhận diện symbol qua hàm get_asset_type chính xác hơn với hỗ trợ các mã index mới. * **Dữ liệu Báo cáo Tài chính**: Hỗ trợ hệ số nhân (`unit_multiplier`), ánh xạ nhất quán cấu trúc cột dữ liệu giữa các nguồn KBS và VCI. * **Xử lý Nguồn dữ liệu (MSN & VCI)**: Xây dựng cơ chế resolve mã `SecId` động cho nguồn MSN để sửa lỗi truy xuất dữ liệu lịch sử; làm sạch các header Device-ID của VCI và thêm cơ chế fallback/sanitize URL an toàn khi tải danh sách mã. ## 27-04-2026 > Cập nhật phiên bản Vnstock 4.0 **Thư viện dữ liệu** * Sửa lỗi truy cập dữ liệu từ nguồn VCI cho các module thông tin niêm yết (Listing), thông tin công ty (Company), và thông tin BCTC (Finance). Thay thế cơ chế lấy dữ liệu từ GraphQL sang REST API mới của Vietcap. * Sửa lỗi tham số `to_df` bị thiếu gây ngừng chương trình. * Cập nhật Unified UI (giao diện người dùng hợp nhất): cung cấp cách thức sử dụng hệ thống class/method chuẩn hoá cho toàn thư viện, thương thích với cách đặt tên và tiêu chuẩn của bản Mở rộng đã giới thiệu trước đó. **Tiện ích** * Cải thiện khả năng sử dụng Google Colab thuận tiện hơn khi không yêu cầu kết nối Google Drive bắt buộc. * Cải thiện logic phát hiện phiên bản phần mềm của hệ sinh thái vnstock đã cập nhật để không hiện lại thông báo phiền phức. * Tinh chỉnh lời nhắn hiển thị hướng dẫn chuyển đổi câu lệnh import từ vnstock sang vnstock_data cho nhà tài trợ mới. **Tài liệu** * Cập nhật Vnstock Agent Guide với các hướng dẫn mới nhất hỗ trợ chuyển đổi code sử dụng class Vnstock sẽ bị loại bỏ từ 1/9/2026 vào skill `vnstock-migration-expert`. **Thông báo** * Hiển thị cảnh báo ngừng hoạt động cho lớp hàm Vnstock thường được sử dụng qua lệnh `from vnstock import Vnstock` sẽ kết thúc hỗ trợ vào 31/8/2026. * Thông báo nâng cấp đi kèm hướng dẫn chuyển đổi code sang các lớp hàm tương đương trong thư viện. * Agent Skills hỗ trợ việc chuyển đổi được bố sung hướng dẫn trong Vnstock Agent Guide. ## 05-04-2026
Bản cập nhật v3.5.1 mang đến những bước tiến lớn trong trải nghiệm lập trình AI (Vibe Coding) và hỗ trợ cập nhật cấu trúc nền tảng êm ái hơn bao giờ hết.
**Tính năng bổ sung nổi bật** * **Chuẩn hóa API cột dữ liệu (Module KBS)**: Mình đã thiết kế lại định danh tên cột dữ liệu chứng khoán nhằm khớp chính xác 100% với giao diện trên terminal của phần mềm KBS thực tế. * Cột `total_trades` 👉 `volume_accumulated` (tổng khối lượng) * Sinh thêm cột ánh xạ 👉 `volume_last` (khối lượng khớp lệnh lần cuối). **Lưu ý cho bạn**: Anh em đang phân tích DataFrame dựa vào các key trên nhớ cập nhật lại tên hàm nhé để pipeline hệ thống tiếp tục chạy ổn định. * **Hệ thống chuyển đổi "Một chạm" (Auto Migration)**: Nâng cấp dự án từ bản cá nhân lên bản Mở rộng với đầy đủ chức năng mở rộng (`vnstock_data`) giờ đây không còn là thao tác "Find & Replace" đầy rủi ro nơm nớp lo sợ làm hỏng code. Chỉ với một hàm gọi `migrate_to_sponsor()`, thư viện sẽ trực tiếp sử dụng công nghệ Cây cú pháp trừu tượng (AST) rà quét và tự động chuyển đổi cấu trúc mã nguồn cũ của bạn sang nền tảng chuyên sâu một cách an toàn tuyệt đối! * **Hệ thống Nhận diện Môi trường (Auto-Detection Guardrail)**: Vnstock nay trở nên tinh tế hơn bao giờ hết: Nếu nhận thấy bạn đang ở tư cách thành viên Sponsor của mình nhưng lại vô tình nhập các hàm phân tích của gói cơ bản, hệ thống sẽ tự động nhắc nhở và điều hướng để hỗ trợ bạn khai thác trọn vẹn đặc quyền và sức mạnh của thư viện sponsor mà bạn đã đăng ký. * **Tối ưu hóa Vibe Coding cùng AI**: Vnstock dồn tâm huyết phát triển các chỉ báo hệ thống ngầm (System Prompts) thiết kế đặc biệt dành cho các AI Agent khi phân tích mã nguồn. Giờ đây, các AI sẽ tự nhận diện rõ năng lực của API và đóng vai trò người cố vấn thay vì cố gắng tự gỡ rối hoặc rò rỉ mã lỗi. Chúng sẽ giúp bạn phân tích khi nào việc nâng cấp lên bản Mở rộng sẽ mang lại giá trị cao hơn nhiều việc cắm cúi code. *** ## 07-03-2026
Phiên bản 3.5.0 mang tính bản lề trong việc tái cấu trúc thư viện, tập trung loại bỏ các nguồn cấp thiếu ổn định và chuẩn hóa điểm dữ liệu để hướng tới sự tương thích với AI (Vibe Coding).
**Các thay đổi quan trọng (Breaking Changes)** * **Tinh gọn Nguồn Cấp Dữ Liệu**: Để đảm bảo một hệ sinh thái công cụ mã nguồn công khai tinh gọn và luôn vận hành ổn định tối đa, Vnstock đã đành phải nói lời chia tay với các module dữ liệu lấy từ TCBS cũng như bộ tính năng Lọc cổ phiếu (Screener). Nhưng bạn đừng lo, nếu bạn cần các bộ lọc chuyên sâu nhiều tiêu chí hay tra tìm dữ liệu mở rộng cho nghiên cứu, mọi sức mạnh này hiện được gói trọn trong bản Mở rộng `vnstock_data`. * **Chuẩn hóa Thông số Bảng giá (KBS Quote)**: Cập nhật định dạng dữ liệu giá lịch sử (`history`) và dữ liệu trong ngày (`intraday`) thống nhất sử dụng hệ số thập phân (đơn vị nghìn đồng) thay cho VND. Điều này giúp tính toán nhẹ nhàng hơn nhưng bạn nhớ điều chỉnh lại các công thức nhân chia mệnh giá trong dòng code cũ để tránh tình trạng lệch dữ liệu biểu đồ phân tích. * **Loại bỏ hàm `price_depth`**: Hàm này đã chính thức ngừng cung cấp trên module `vci.quote`. Tính năng chỉ có trong gói sponsor `vnstock_data`. **Tính năng bổ sung & Cải tiến** * **Dữ liệu Sự kiện Thị trường (Market Events)**: Vnstock thấu hiểu nỗi đau của những ai làm backtesting khi chiến lược bị lệch pha do các ngày nghỉ lễ hay những hôm nghẽn hệ thống. Module mới `vnstock.core.utils.market_events` ra đời cung cấp bộ lịch sử sự kiện chứng khoán Việt Nam từ năm 2000. Đây là công cụ đắc lực hỗ trợ các mô hình AI và thuật toán phân tích chuỗi thời gian (time-series) của bạn vượt qua bài toán nhiễu loạn dữ liệu. * **Hàng loạt Cải thiện Ổn định**: Vá ngoạn mục hàng loạt lỗi hệ thống: Bổ sung phương pháp lấy mã cổ phiếu fallback cực thông minh (hiệu quả khi sàn thiếu column gốc); sửa lỗi bắt dữ liệu cho Hợp đồng tương lai đáo hạn và nâng cấp thuật toán đọc số bar trên khung ngày (`500b`) cho KBS Quote được chính xác. Cùng với đó là hoàn thiện việc tích hợp `pytz` hỗ trợ làm đồng bộ các bộ dữ liệu đa không gian múi giờ. *** ## 01-02-2026
Phiên bản 3.4.2 tập trung vào sửa lỗi và cải thiện tính ổn định, đặc biệt là tương thích với các phiên bản pandas khác nhau và chuẩn hóa dữ liệu giá.
**Sửa lỗi quan trọng** * **Sửa lỗi tương thích pandas**: Khắc phục vấn đề `include_groups` parameter không được hỗ trợ trong pandas 2.1.4, giúp hàm `intraday()` hoạt động bình thường trên mọi phiên bản pandas * **Sửa lỗi kiểm thử Listing**: Cập nhật các bài kiểm thử để xử lý chính xác kiểu dữ liệu `pd.Series` trả về từ `all_future_indices` và các phương thức liên quan * **Sửa lỗi kiểm thử Quote**: Cải thiện khả năng xử lý dữ liệu thiếu và các hợp đồng đã hết hạn một cách linh hoạt mà không làm thất bại toàn bộ bộ kiểm thử * **Sửa lỗi KBS Quote**: Cải thiện khả năng diễn giải các độ dài lookback dựa trên thanh (ví dụ: '500b') sử dụng logic `interpret_lookback_length` **Cải tiến** * **Bổ sung liên kết đến Agent Guide**: Giúp dễ dàng truy cập và sử dụng bộ hướng dẫn chi tiết cho AI trong Vibe Coding. * **Chuẩn hóa dữ liệu giá KBS**: Chuyển đổi dữ liệu giá từ nguồn KBS sang sử dụng giá trị thập phân (đơn vị nghìn) thay vì VND trong các phương thức `history` và `intraday`, giúp dữ liệu nhất quán và dễ xử lý hơn **Loại bỏ** * **Loại bỏ phương thức `price_depth`**: khỏi `vnstock.explorer.vci.quote`, tập trung các hàm cơ bản cho bản Cộng đồng. *** ## 23-01-2026
Phiên bản 3.4.0 đã được phát hành chính thức. Cài đặt ngay với lệnh pip install vnstock -U. Phiên bản này tập trung vào trải nghiệm người dùng: dữ liệu tài chính sạch hơn, trực quan dễ hiểu hơn và cài đặt/xác thực thuận tiện hơn.
**Những điểm nổi bật** * **Cài đặt & xác thực dễ dàng** * Cài nhanh bằng `pip install vnstock -U` và nhập API Key từ trang quản lý tài khoản Vnstock để sử dụng, hỗ trợ hàm trực tiếp từ thư viện để sử dụng. * **Báo cáo tài chính thân thiện với người dùng từ nguồn KBS** * Dữ liệu báo cáo giờ đây được chuẩn hóa tốt hơn: cột rõ ràng, ít trùng lặp và dễ đọc. * Hỗ trợ **lọc ngôn ngữ** (Tiếng Việt / Tiếng Anh / Cả hai) và các chế độ hiển thị (`standardized_only`, `all_fields`, `auto_convert`) giúp bạn nhanh chóng lấy dữ liệu phù hợp cho báo cáo hoặc phân tích. * **Dữ liệu đáng tin cậy & chuẩn hóa tiếng Việt** * Cải tiến chuẩn hóa văn bản tiếng Việt (bảng ký tự nâng cấp, chuyển đổi tên trường ổn định) giúp việc tìm, so sánh và tự động hoá xử lý dữ liệu trở nên dễ dàng hơn. * Tự động **phát hiện xung đột các trường thông tin trong BCTC** và sinh ID khi cần, giảm rủi ro nhầm lẫn khi trộn nhiều nguồn dữ liệu. * Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. * **Trực quan hoá & báo cáo nhanh** * Tích hợp `vnstock_ezchart` cùng tiện ích mở rộng cho pandas để vẽ biểu đồ và tạo báo cáo chỉ bằng vài dòng mã. * **Ổn định & chất lượng phát hành** * Cải thiện quy trình kiểm thử và CI/CD giúp phát hành phiên bản ổn định hơn, lỗi được phát hiện và sửa nhanh hơn. **Một vài thay đổi nhỏ** * Cập nhật đường dẫn đăng ký API key từ `/account` → `/login` (trải nghiệm đăng ký/đăng nhập thống nhất hơn). * Tối ưu hiệu suất mô-đun dữ liệu KBS và một số tinh chỉnh nội bộ để nâng cao tốc độ và độ tin cậy. *** ## 11-11-2025 * 🚀 **Phiên bản v3.3.0** * **Tương thích hệ thống thư viện Sponsor** sử dụng phương thức xác thực người dùng và quyền sử dụng thông qua Vnstock API key thay cho Github. * **Tăng tốc sử dụng Vnstock trên Google Colab**: Cho phép lưu trữ thư viện & cấu hình vĩnh viễn trong Google Drive để khởi động nhanh thay vì cài đặt lại sau mỗi phiên làm việc. * **Hỗ trợ proxy tự động**: Thêm khả năng cấu hình proxy khi môi trường chạy (ví dụ Google Colab) không kết nối được tới nguồn, dùng trong phạm vi quyền truy cập của bạn với nguồn, phù hợp cho nghiên cứu và sử dụng cá nhân * **Hệ thống quản lý nguồn dữ liệu**: Tạo hệ thống thống nhất để quản lý tất cả nguồn dữ liệu (VCI, TCBS, FMP, XNO, DNSE) * **Kết nối FMP & XNO**: Thêm nguồn dữ liệu thị trường quốc tế, cần lấy API key miễn phí từ FMP và XNO * **Tái tổ chức mã nguồn**: Gộp các module trong core.utils, chuẩn hóa cách đặt tên và cấu trúc trong common * **Hệ thống kiểm thử đầy đủ**: Thêm bộ test toàn diện cho các module VCI, TCBS, FMP với kiểm thử tích hợp * **Chuyển sang pyproject.toml**: Thay thế setup.py bằng pyproject.toml, cập nhật các thư viện phụ thuộc * **Cấu hình Context7**: Thiết lập hệ thống lập chỉ mục tài liệu cho AI * **Cập nhật tài liệu**: Làm mới notebook hướng dẫn nhanh, hướng dẫn sử dụng * 🔧 **Cải thiện kỹ thuật** * Chuẩn hóa hằng số thị trường, chỉ số và định nghĩa kiểu dữ liệu * Cải thiện xử lý lỗi và thông báo xác thực * Tối ưu cấu hình proxy với chế độ dự phòng và xử lý lỗi * Tái cấu trúc mã nguồn tiêu chuẩn với tài liệu mô tả bằng tiếng Anh * 📚 **Tài liệu** * Cập nhật notebook hướng dẫn nhanh cho FMP và XNO * Thêm script demo và ví dụ [sử dụng proxy](https://github.com/thinh-vu/vnstock/blob/main/docs/PROXY_GUIDE.md) tại Github ## 23-05-2025
Chính thức phát hành phiên bản mới sau khi đã cập nhật bản thử nghiệm từ 17/05/2025 hỗ trợ mã hợp đồng tương lai mới sau khi chuyển đổi hệ thống KRX.
* Hỗ trợ mã hợp đồng tương lai mới theo chuẩn KRX: 1. **Loại CK phái sinh** (ký tự 1) 2. **Nhóm CK** (ký tự 2: 1=Future, 2=Spread) 3. **Tài sản cơ sở** (ký tự 3–4: I1=VN30, B5=GB05, BA=GB10, I2=VN100) 4. **Năm đáo hạn** (ký tự 5: 0→W, loại trừ I,O,U) 5. **Tháng đáo hạn** (ký tự 6: 1→C) 6. **Mã sản phẩm** (ký tự 7–9, ví dụ 000 = HĐTL) * **Ví dụ chuyển đổi**: VN30F2504 → 41I1F4000 Cập nhật này giúp Vnstock nhận diện đúng loại hợp đồng tương lai khi bạn nhập mã hợp đồng theo cấu trúc mới. ## 07-05-2025
Cập nhật mã nguồn trên Github cho phiên bản kế tiếp. Bạn có thể cập nhật phiên bản để trải nghiệm trong khi phiên bản ổn định sẽ được phát hành trong những ngày tới.
Cài đặt phiên bản thử nghiệm: ```bash pip install vnstock -U ``` Xem thêm hướng dẫn tại [Tải về & Cài đặt](/onboard/trai-nghiem-vnstock) **Cập nhật nổi bật** * [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Gỡ & thay thế code cho package fake_user_agent trong toàn bộ hệ sinh thái * Sửa lỗi hàm `intraday` sau cập nhật hệ thống KRX * Dữ liệu từ nguồn VCI thay đổi kiểu dữ liệu (`object`/`float`) thay vì `int` như trước đó. * Dữ liệu từ nguồn TCBS bị sai lệnh múi giờ (dữ liệu mới đã chuẩn múi giờ GMT+7) * Bổ sung thông tin bạn đồng hành đóng góp mã nguồn và tài trợ dự án nổi bật vào mô tả dự án. ## 22-04-2025
Phiên bản **3.2.4** tái cấu trúc bộ adapter từ `vnstock/common` → `vnstock/api` với thuật toán xử lý chặt chẽ hơn, dần loại bỏ lớp trung gian không cần thiết hiện đang sử dụng với `Vnstock` class; bổ sung **notebook minh họa**; tối ưu hóa quy trình **báo lỗi** và **theo dõi dự án** trên GitHub.
**Cải tiến kiến trúc** * Bổ sung cấu trúc Adapter mới tại `vnstock/api` * Thuật toán mới tăng độ chính xác và linh hoạt khi chuyển đổi nguồn dữ liệu * Loại bỏ lớp trung gian cấp cao Vnstock, trực tiếp sử dụng các lớp: `Quote`, `Finance`, `Trading`, `Listing`, `Company` * Tương thích ngược: mọi hàm và class cũ vẫn hoạt động bình thường **Hướng dẫn minh họa** * Bổ sung file notebook minh họa mới sử dụng các cấu trúc lớp trung gian chuyển đổi nguồn nhanh chóng [tại đây](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/wrapper/1_1_quickstart_stock_vietnam.ipynb) **Hoàn thiện quy trình phát triển** * Báo lỗi qua [GitHub Issues](https://github.com/thinh-vu/vnstock/issues) tại trang Github Vnstock * Theo dõi lộ trình qua [GitHub Projects](https://github.com/users/thinh-vu/projects/4) tại trang Github Vnstock ## 27-03-2025 > Cập nhật phiên bản 3.2.3 cải thiện trải nghiệm người dùng * Xử lý chính xác các cột có tên trùng lặp trong hàm `balance_sheet` trả về bảng cân đối kế toán. Theo đó cột xuất hiện sau với tên trùng lặp sẽ được đặt tên với tiền tố `_`. Ví dụ `Chứng khoán kinh doanh` và `_Chứng khoán kinh doanh` cho cột xuất hiện sau. Hai cột này tồn tại có ý nghĩa theo hình thức cha/con trên bảng cân đối kế toán tiêu chuẩn. * Merge [pull request 159](https://github.com/thinh-vu/vnstock/pull/159): Bổ sung cột sẽ được lựa chọn hiển thị tiếng Việt khi trích xuất dữ liệu từ Dict * Bổ sung `tenacity` là gói phụ thuộc khi cài đặt dự án * Sửa lỗi không cho truy cập dữ liệu intraday từ nguồn TCBS ngoài giờ giao dịch. * Sửa lỗi hàm Pandas `map` và thay thế với `applymap` để tương thích với bản Pandas cũ hơn 2.x trong module company của nguồn VCI (dòng 135) * Cập nhật file README đổi tên Vnstock3 thành Vnstock ## 24-03-2025 > Cập nhật phiên bản 3.2.2 sửa lỗi 502 Bad Request xuất hiện với nguồn dữ liệu VCI. Lỗi 502 Bad Request xuất hiện trùng thời điểm với việc nâng cấp lên phiên bản 3.2.1 đã khiến nhiều người thắc mắc. Sau khi phân tích, nguyên nhân được xác định: VCI đã thay đổi địa chỉ cấp dữ liệu API, khiến các yêu cầu gửi đến API cũ không còn hiệu lực và dẫn đến phản hồi không ổn định. ## 23-03-2025 > Cập nhật phiên bản 3.2.1 với nhiều thay đổi quan trọng * Bổ sung tính năng bộ lọc cổ phiếu từ TCBS * Thêm dữ liệu thông tin công ty từ nguồn VCI * Kết nối Google Drive từ Colab - Không bao giờ quên lưu dữ liệu nữa * Cải tiến trải nghiệm người dùng * Nhận diện phiên giao dịch: tự động gửi cảnh báo lỗi chi tiết giúp bạn điều hướng dễ dàng khi truy cập dữ liệu `intraday` và `price_depth` trước phiên giao dịch. * Cảnh báo chủ động rate limit * Chuẩn hóa tên cột: Thay đổi `ticker` → `symbol`, `HOSE` → `HSX`, giúp dữ liệu đồng nhất, dễ xử lý hơn. * Cập nhật API key MSN: Đảm bảo việc lấy dữ liệu luôn ổn định và nhanh chóng. * Tái cấu trúc mã nguồn * Tăng mức độ module hóa mã nguồn * Cấu trúc tinh gọn và dễ bảo trì * Chuẩn hóa xử lý lỗi Chi tiết, vui lòng xem trong bài blog.
Xem thêm
## 02-01-2025
Hợp nhất thư viện Vnstock3 và Vnstock Legacy, sử dụng chung tên gọi thư viện là vnstock từ hệ thống phân phối phần mềm pypi.org. Từ 2/1/2025, mọi cài đặt thư viện vnstock được mặc định hiểu là thư viện thế hệ 3, bắt đầu từ phiên bản 3.1.0
* Cập nhật thư viện lên trang phân phối pypi.org. Câu lệnh cài đặt mặc định: `pip install -U vnstock` sẽ luôn cài đặt phiên bản vnstock mới nhất vào máy của bạn. Câu lệnh `pip install vnstock3` sẽ vẫn có hiệu lực, chỉ cập nhật đến phiên bản 3.1.0. * Cập nhật tài liệu hướng dẫn trên website và file Demo. Tất cả lệnh sẽ sử dụng `vnstock` để chỉ định phiên bản hiện tại của Vnstock3.1.0.1. Tham khảo blog để biết thêm chi tiết [tại đây](/blog/chuyen-doi-sang-vnstock3-truoc-2025). ## 02-11-2024 > Phát hành chính thức phiên bản v3.0.9 qua PyPI. Cài đặt với câu lệnh: `pip install -U vnstock` trên máy của bạn. * Nâng cấp hàm truy xuất dữ liệu từ nguồn VCI cho báo cáo tài chính. Lọc các cột dữ liệu không liên quan, trùng lặp xuất hiện trong các phiên bản trước đó. Chỉ tập trung các giá trị dữ liệu cho đúng loại hình công ty của mã bạn tra cứu. Có 4 nhóm công ty bao gồm Công ty phổ thông, Ngân hàng, Chứng khoán, Bảo hiểm. * Sửa lỗi chuyển đổi nhanh mã cổ phiếu. Cho phép cài đặt tham số `symbol` khi gọi hàm với cú pháp `stock.finance(symbol='TCB')`. Việc này giúp bạn không cần phải cập nhật mã symbol khi khởi tạo class mà có thể thayd đổi trong method gọi dữ liệu cụ thể. Thay đổi này sau đó sẽ áp dụng cho class trong các hàm tiếp theo. * Bổ sung thêm tuỳ chọn tham số `show_log` trong các class của Vnstock, bạn có thể tắt log message (các hiển thị cảnh báo) bằng cách đặt `show_log=False`. * Khắc phục lỗi định dạng `NoneType Object` khi không nhập mã chứng khoán trong Listing class với câu lệnh: ``` from vnstock3 import Vnstock stock = Vnstock().stock(source='VCI') ``` * Khắc phục lỗi 404 khi truy cập dữ liệu giá từ module Quote của VCI do API url thay đổi. * Khắc phục lỗi không nhận diện các mã chỉ số khi tra cứu lịch sử giá từ module Quote.history. Các mã chỉ số chuẩn sử dụng cho tra cứu thị trường chứng khoán Việt Nam gồm: VNINDEX, HNXINDEX, UPCOMINDEX * Bổ sung khả năng lấy dữ liệu giá lịch sử cho Trái phiếu niêm yết & nâng cấp cơ chế nhận diện loại tài sản với khả năng nhận diện mã nhập vào là Trái phiếu. ## 15-10-2024 Cập nhật phiên bản mới, gỡ lỗi một số vấn đề phát sinh được báo lỗi: -Lỗi khi gọi lịch sử giá: [issue 147](https://github.com/thinh-vu/vnstock/issues/147) * Bổ sung cơ chế báo lỗi khi dữ liệu trả về không như mong muốn với BCTC: [issue 133](https://github.com/thinh-vu/vnstock/issues/133#issuecomment-2395270403) ## 12-08-2024 Cập nhật mã nguồn phiên bản 0.3.0.7 * Sửa lỗi mốc thời gian giá lịch sử không ổn định. Hiện tại có thể lấy thông tin giá lịch sử thuộc tất cả các khung thời gian với tham số `end` là ngày hiện tại. Mã báo lỗi 135: [tại đây](https://github.com/thinh-vu/vnstock/issues/135) * Bổ sung cơ chế xử lý lỗi khi thông tin `event_desc` trả về trong DataFrame không chứa thành phần HTML cần chuyển đổi thành văn bản. Mã báo lỗi 141 [tại đây](https://github.com/thinh-vu/vnstock/issues/141#issuecomment-2271610641) * Sửa lỗi & cải thiện phương thức lấy dữ liệu báo cáo tài chính từ VCI: * Sửa lỗi tên biến `UNIT_MAPPING` không khớp * Tự động loại bỏ dữ liệu N/A trong báo cáo tài chính. Việc này giúp loại bỏ các dữ liệu không có ý nghĩa và trùng lặp tên cột. Bạn có thể tuỳ chỉnh sử dụng tham số dropna=False để chỉ định giữ lại dữ liệu nguyên bản (có thể trùng lặp tên cột - khác ý nghĩa dữ liệu) và N/A. * Hỗ trợ API đặt lệnh từ Vnstock Python sử dụng bộ API từ DNSE. Mã nguồn được kế thừa từ phiên bản Vnstock Legacy. Chi tiết [tại đây](/docs/vnstock/api-dat-lenh-giao-dich-dnse) * Bổ sung thông tin gói phụ thuộc * Bổ sung phiên bản cố định cho các gói phụ thuộc vào file [requirements.txt](https://github.com/thinh-vu/vnstock/blob/main/requirements.txt) * Bổ sung `seaborn` vào danh sách gói phụ thuộc để loại bỏ lỗi khi cài đặt trên máy tính mới không có sẵn `seaborn`. ## 10-07-2024 Cập nhật mã nguồn phiên bản 0.3.0.6 * Chuyển đổi mã nguồn Vnstock Legacy sang Vnstock3 cho bộ công cụ gửi tin nhắn qua Telegram, Lark, Slack [tại đây](/docs/vnstock/gui-tin-nhan-telegram-slack-larksuite). * Chuyển đổi mã nguồn module `fund.py` từ Vnstock Legacy sang Vnstock3 [tại đây](/docs/vnstock/du-lieu-quy-mo). * Loại bỏ cơ chế bắt buộc người dùng chấp nhận điều khoản, điều kiện rõ ràng. Mặc định, bạn chấp nhận điều khoản & điều kiện khi tiếp tục sử dụng Vnstock3. * Sửa lỗi và cải thiện trải nghiệm: * Xác thực thông tin mã quỹ nhập vào [tại đây](https://github.com/thinh-vu/vnstock/issues/118) * Lỗi khi lấy giá lịch sử theo tháng [tại đây](https://github.com/thinh-vu/vnstock/issues/127) ## 21-06-2024 Cập nhật phiên bản 0.3.0.5 * Sửa lỗi không hiển thị đúng múi giờ trong thời gian của bảng giá lịch sử với khung thời gian giờ và phút, chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/131) * Sửa lỗi không cho phép truy xuất thông tin giá từ TCBS nếu `symbol` không phải là mã cổ phiếu. Chi tiết issue [tại đây](https://github.com/thinh-vu/vnstock/issues/128) * Bổ sung xác thực thông tin nhập liệu cho hàm `history` * Thời gian bắt đầu phải nhỏ hơn thời gian kết thúc. ## 03-06-2024 Cập nhật phiên bản 0.3.0.3 * Tích hợp khả năng biểu diễn dữ liệu của vnstock_ezchart trực tiếp vào thư viện. Chi tiết [tại đây](/docs/vnstock/bieu-dien-du-lieu) * Tách riêng notebook min hoạ theo chủ đề. Chi tiết [tại đây](https://github.com/thinh-vu/vnstock/tree/main/docs) * Cập nhật hàm truy xuất api_key từ nguồn dữ liệu MSN, khắc phục lỗi truy xuất dữ liệu các loại chứng khoán quốc tế. * Cập nhật nội dung phản ánh các thay đổi của dự án trên Website. ## 25-05-2024
Hoàn thiện tính năng, sửa lỗi và bổ sung tài liệu hướng dẫn.
* Sửa lỗi tự động ghi đè thông tin mã cổ phiếu theo mã báo lỗi [9547585](https://github.com/thinh-vu/vnstock/discussions/16#discussioncomment-9547585) * Hoàn thiện nhóm hàm chức năng truy xuất dữ liệu tài chính. Hiện tại có thể gọi thuộc tính `finance` từ lớp Vnstock() thay vì gọi hàm từ trực tiếp nguồn dữ liệu kiểu `vnstock3.explorer.vci.finance`. * Cập nhật hàm minh hoạ trong [Demo Notebook](https://colab.research.google.com/github/thinh-vu/vnstock/blob/main/docs/vnstock3_demo.ipynb). * Bổ sung tài liệu hướng dẫn chi tiết * [Thông tin niêm yết](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Thông tin công ty](/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference) * [Báo cáo tài chính](/docs/vnstock/bao-cao-tai-chinh) * Dành cho nhóm phát triển: * Bổ sung cấu trúc thư mục `tests` dùng cho việc kiểm thử gói phần mềm. ## 10-05-2024
Ra mắt phiên bản Vnstock thế hệ thứ 3 - Vnstock3.
![](/images/Hello_Vnstock3_10-05-2024-97749fc40c003ac445c205b3215bed4c.png) ## 23-01-2024
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app *
## 21-01-2024 * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ## 03-01-2024 * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ## 02-01-2024 * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. Chi tiết [tại đây](https://docs.vnstock.site/integrate/pytesseract-ocr-chuyen-doi-tai-lieu-tai-chinh-scan-sang-van-ban/) ## 24-12-2023 * Cập nhật tài liệu dự án * Tài liệu truy xuất [giá lịch sử](https://docs.vnstock.site/functions/technical/) * Hướng dẫn [truy xuất dữ liệu giao dịch nước ngoài/tự doanh](https://docs.vnstock.site/functions/market/#giao-dich-ntnn) sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ## 16-12-2023 * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data` [tại đây](https://docs.vnstock.site/integrate/ssi_fast_connect_api/) * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program [tại đây](https://docs.vnstock.site/insiders-program/gioi-thieu-chuong-trinh-vnstock-insiders-program) * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ## 14-12-2023 Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. Hướng dẫn [tại đây](https://docs.vnstock.site/functions/funds/) * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. Hướng dẫn [tại đây](https://docs.vnstock.site/integrate/OpenBBTerminal/) * Cập nhật tài liệu dự án ## 10-12-2023 * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ## 02-04-2024
Cập nhật tài liệu hướng dẫn và sửa đổi nhỏ cho hàm gửi tin nhắn Telegram.
## 23-01-2024
Cập nhật thay đổi từ ngày 16/12/2023 ở phiên bản `beta` sang `main` và phát hành chính thức phiên bản 0.2.8.8.
* Cập nhật mã nguồn hàm `financial_report` sửa lỗi triệt để lỗi sử dụng 'Excel file format cannot be determined, you must specify an engine manually' do dữ liệu trả về không phải định dạng Excel. * Nguồn dữ liệu từ Fiintrade của SSI sử dụng mã `OrganCode` để tra cứu thông tin công ty trong đó có báo cáo tài chính. Có khoảng > 600 mã cổ phiếu có mã symbol khác OrganCode do đó có nhiều mã khi tra cứu BCTC với mã symbol sẽ gây ra rỗi trong khi với các mã khác thì không. Ví dụ `YTC` có OrganCode là `YTECO` dùng để tra cứu BCTC. * Bổ sung `openpyxl` là gói phụ thuộc để đọc dữ liệu trả về từ API dưới dạng file Excel. Lỗi này xảy ra khi cài bản Python thuần. Không gặp lỗi với Google Colab hoặc Anaconda. * Sửa lỗi vnstock web app ## 21-1-2024 * Bổ sung tích hợp cho phép sử dụng các hàm gửi tin nhắn từ vnstock qua Telegram/Slack với các channel/group chat được cài đặt. * Cập nhật nội dung trang tài liệu * Khởi động dự án vnstock-next cho thế hệ phần mềm vnstock tiếp theo. ## 03-01-2024 * Cập nhật khung chương trình khóa học Python 5 khai giảng 21/1/2024 * Bổ sung tính năng hiện banner thông báo quan trọng trên trang tài liệu. ## 02-01-2024 * Bổ sung tính năng OCR sử dụng Pytesseract cho vnstock và vnstock-data-pro. Chi tiết [tại đây](https://docs.vnstock.site/integrate/pytesseract-ocr-chuyen-doi-tai-lieu-tai-chinh-scan-sang-van-ban/) ## 24-12-2023 * Cập nhật tài liệu dự án * Tài liệu truy xuất [giá lịch sử](https://docs.vnstock.site/functions/technical/) * Hướng dẫn [truy xuất dữ liệu giao dịch nước ngoài/tự doanh](https://docs.vnstock.site/functions/market/#giao-dich-ntnn) sử dụng gói phần mềm `vnstock-data-pro` * Hướng dẫn nhanh ## 16-12-2023 * Cập nhật tài liệu dự án * Bổ sung hướng dẫn sử dụng tích hợp SSI Fast Connect API trong gói `vnstock-pro-data` [tại đây](https://docs.vnstock.site/integrate/ssi_fast_connect_api/) * Bổ sung thông tin chi tiết chương trình Vnstock Insider Program [tại đây](https://docs.vnstock.site/insiders-program/gioi-thieu-chuong-trinh-vnstock-insiders-program) * Bổ sung `requirements.txt` cho trình tạo trang tĩnh MKDocs giúp cài đặt gói phụ thuộc để thiết lập trang tài liệu và xem trước dễ dàng. ## 14-12-2023 Chính thức phát hành các thay đổi từ nhánh Beta trong phiên bản 2.8.7. Chi tiết cập nhật qua blog: [tại đây](https://vnstocks.com/2023/12/15/ra-mat-vnstock-insider-program-cap-nhat-nhieu-tinh-nang-thu-vi/) * Ra mắt Vnstock Insiders Program cung cấp quyền truy cập tới các kho chứa mã nguồn riêng tư (private repo) * Ra mắt `vnstock-pro-data` trong chương trình Insiders, cung cấp khả năng truy cập dữ liệu chất lượng cao với độ trễ theo nguồn. * Tải dữ liệu giá OHLCV nhanh chóng, chính xác không cần xác thực qua Public API của SSI. * Tải và streaming dữ liệu qua SSI Fast Connect API chính thức (cần đăng ký và xác thực người dùng) * Chính thức phát hành tính năng truy cập dữ liệu quỹ mở. Hướng dẫn [tại đây](https://docs.vnstock.site/functions/funds/) * Hỗ trợ xuất dữ liệu time series cho OpenBB Terminal. Hướng dẫn [tại đây](https://docs.vnstock.site/integrate/OpenBBTerminal/) * Cập nhật tài liệu dự án ## 10-12-2023 * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ## 10-12-2023 * Bổ sung tính năng truy xuất dữ liệu quỹ mở từ fmarket.vn, phát triển từ mã nguồn do `andrey_jef` đóng góp. Tài liệu mô tả và demo notebook đã được cập nhật tương ứng. * Đưa `plotly` thành thư viện tùy chọn, chỉ phải import vào dự án nếu người dùng có nhu cầu sử dụng tính năng vẽ đồ thị. Việc này giúp vnstock chạy trên môi trường khác Google Colab không cần cài đặt thêm `plotly` theo mặc định. Mã nguồn được cập nhật lên bản beta trên Github, thay đổi sẽ được đẩy lên PyPI trong tuần tới. * Cập nhật tài liệu hướng dẫn cho nội dung lấy dữ liệu giá lịch sử. * Cập nhật tài liệu hướng dẫn cách cài đặt thư viện TA-Lib cho phân tích kỹ thuật trên máy tính Windows. ## 09-11-2023 > Phát hành phiên bản 0.2.8.5 * Cập nhật hàm `stock_intraday_data` * Bổ sung tham số `investor_segment`, mặc định nhận giá trị `True` cho phép trả về dữ liệu khớp lệnh theo phân nhóm nhà đầu tư (như các phiên bản trước), khi đặt là `False` cho phép trả về dữ liệu thô, không gộp thông tin lệnh theo phân nhóm. * Bổ sung hàm `amibroker_ohlc_export` cho phép xuất dữ liệu sang định dạng CSV để nạp dữ liệu cho Amibroker. Chi tiết [tại đây](http://docs.vnstock.site/integrate/amibroker/) * Bổ sung hướng dẫn tích hợp vnstock với dự án sử dụng thư viện phân tích kỹ thuật TA-lib python. Chi tiết [tại đây](http://docs.vnstock.site/integrate/ta_lib/) * Giới thiệu một số thư viện Backtesting trong python giúp kiểm thử chiến lược giao dịch. Chi tiết [tại đây](http://docs.vnstock.site/integrate/backtesting/) ## 08-11-2023 > Phát hành phiên bản 0.2.8.4 * Tùy biến hàm `stock_historical_data` giúp dễ dàng sử dụng với các thư viện phân tích kỹ thuật khác trong Python. * Thêm tham số `decor`, nhận giá trị mặc định là `False` (không thay đổi dữ liệu trả về với cách sử dụng hiện tại của người dùng). Khi đặt `decor=True`, áp dụng thay tên các cột trong DataFrame trả về dưới dạng Title Case tức `Open, High, Low, Close, Time, Ticker` thay vì `open, high, low, close, time, ticker` như hiện tại đồng thời đặt cột Time là index. Việc này giảm bớt cho người dùng phải viết thêm câu lệnh khi sử dụng dữ liệu vnstock kết hợp các thư viện phân tích kỹ thuật phổ biến vốn dùng thư viện Yahoo Finance làm nguồn cấp dữ liệu. * Bổ sung tham số `source` cho phép chọn nguồn tải dữ liệu là `TCBS` hay `DNSE`. Nguồn dữ liệu `TCBS` cho lấy dữ liệu lịch sử theo ngày (resolution = `1D`) trong thời gian dài, không hỗ trợ khung thời gian nhỏ hơn. Trong khi đó nguồn dữ liệu `DNSE` cho phép lấy dữ liệu với nhiều khung thời gian khác nhau, giới hạn 90 ngày gần nhất đối với dữ liệu phút, 10 năm gần nhất đối với dữ liệu ngày. * Cập nhật tcbs_headers sử dụng cho các request đến API của TCBS ## 05-11-2023 * Hoàn thiện tích hợp đầy đủ DNSE Lightspeed API vào mã nguồn vnstock. Phát hành phiên bản 0.2.8.2. Sử dụng lệnh `pip install -U vnstock` để cập nhật phiên bản. ## 29-10-2023 * Tích hợp API endpoints cơ bản của DNSE vào vnstock * Demo cho các nhà đầu tư cách tạo 1 request và kết nối hệ thống DNSE để lấy JWT token * Demo xuất thông tin tài khoản * Cập nhật tài liệu sử dụng ## 27-10-2023 * Bổ sung và hoàn thiện một số hàm cho vnstock * Hàm `listing_companies` nay được cung cấp thêm khả năng lấy danh sách công ty niêm yết từ SSI/FiinTrade. Việc này giúp người dùng có thể tham chiếu mã công ty từ mã cổ phiếu để lấy thông tin trong một số trường hợp đặc biệt FiinTrade sử dụng mã này thay cho mã cổ phiếu. Ví dụ, thay vì dùng mã cổ phiếu `BCM` gây ra lỗi cho hàm, bạn cần sử dụng mã công ty tương ứng là `BIDC` * Hàm `indices_listing` cho phép liệt kê tất cả mã chỉ số hiện có trên sàn. * Hàm `financial_ratio_compare` cho phép so sánh chỉ số tài chính của một danh sách các mã cổ phiếu. ## 26-10-2023 * Khôi phục các hàm lấy dữ liệu từ nguồn SSI gồm `financial_report`, `fr_trade_heatmap`, `market_top_mover` do SSI hiện tại đã gỡ bỏ mọi hạn chế về kỹ thuật áp dụng cho bot thực hiện web scraping. * Cập nhật tài liệu sử dụng kèm theo * Cập nhật Demo Notebook ## 25-10-2023 * Bổ sung hướng dẫn xuất dữ liệu sang các định dạng phổ biến bao gồm CSV, Excel, và dữ liệu cho Amibroker. * Thử nghiệm tính năng Blog của Mkdocs Matterial cho chuyên mục Kiến thức. ## 21-10-2023 * Giới thiệu cách sử dụng vnstock trong Google Sheets với Neptyne for Google Sheets. * Di chuyển mục nội dung vnstock cho Google Sheets sang tab `Ứng dụng & Tích hợp` ## 20-10-2023 * Chuyển đổi nền tảng tài liệu từ Pretty-Docs sang [MkDocs Matterial](https://squidfunk.github.io/mkdocs-material/) thân thiện và nhiều tính năng hữu ích hơn. * Cập nhật mô tả các hàm để tiện theo dõi bao gồm: * Xoay DataFrame kết quả trả về để có thể hiển thị đầy đủ tên các cột dữ liệu * Bổ sung mô tả tham số đầu vào của hàm ## 14-10-2023 > Phiên bản: 0.2.2: Đưa tính năng vẽ đồ thị chính thức vào phiên bản ổn định, cập nhật hàm truy xuất giá lịch sử * Cập nhật hàm `stock_historical_data` để trả về thông tin chính xác * Loại bỏ bước tính toán nhân chỉ số và mã phái sinh với 1000 khi trả về dữ liệu. Cách tính này làm sai lệch giá trị của chỉ số và mã phái sinh vì bản chất giá trị OHLC này khác với giá cổ phiếu. * Bổ sung thêm tham số **beautify**, đặt giá trị mặc định là True để giữ nguyên cách nhân 1000 cho giá cổ phiếu. Người dùng có thể chuyển về False để giữ nguyên giá trị OHLC dạng thập phân rút gọn. * Chính thức đưa các hàm vẽ đồ thị vào phiên bản chính thức của vnstock sau quá trình thử nghiệm * Hàm **candlestick_chart** cho phép vẽ đồ thị nến cùng các đường trung bình động, hỗ trợ, kháng cự cơ bản. ![candlestick](/images/VIC_candlestick.png) * Hàm **bollinger_bands_chart** cho phép vẽ đồ thị nến (hoặc đường) kèm các dải Bollinger Bands. Hàm này cần sử dụng kèm hàm **bollinger_bands** để chuyển đổi dữ liệu OHLC tiêu chuẩn sang dữ liệu Bollinger Bands. ![bollinger bands](/images/bollinger_bands_chart.png) ## 10-10-2023 * Hàm **listing_company** được điều chỉnh để hỗ trợ truy xuất danh sách mã cổ phiếu cập nhật trực tiếp qua API. * Bổ sung tham số **live** nhận giá trị True hoặc False, mặc định là False cho phép truy xuất danh sách cổ phiếu từ tệp csv lưu trữ trên Github. Cấu trúc của file dữ liệu cục bộ chứa thông tin đầy đủ hơn so với chế độ trực tiếp. * Loại bỏ tham số **path** ## 06-10-2023 > Thay đổi cấu trúc thư mục và tài liệu vnstock repo trên Github * Tái cấu trúc cây thư mục của vnstock repo trên Github * Chuyển toàn bộ file markdown vào thư mục **docs** trừ file README (Tiếng Việt). * Chuyển thư mục **src** vào bên trong thư mục **docs** và đổi tên thành **resources**. Các file ảnh đính kèm dự án được đưa vào sâu hơn 1 cấp bên trong thư mục **images**. * Đơn giản hóa nội dung file README của repo. Đưa tất cả tài liệu hướng dẫn vào vnstock docs. * Bổ sung cơ chế kiểm tra mã phản hồi (status_code) của API trước khi trả về dữ liệu cho hàm **stock_intraday_data** ## 05-10-2023 > vnstock docs Phiên bản 1.1 sử dụng Pretty-Docs theme Thử nghiệm thành công và ra mắt phiên bản thử nghiệm 1.0 cho trang tài liệu vnstock docs sử dụng pretty-docs theme. ## 22-08-2023 * Cập nhật tệp dữ liệu **listing_companies** lên phiên bản mới nhất. * Cập nhật hàm **financial flow** * Thêm tham số **get_all** để lấy tất cả dữ liệu có sẵn hoặc chỉ dữ liệu mới nhất (5 năm hoặc 10 quý). * Cập nhật Demo Notebook để minh họa các thay đổi mới nhất. ## 24-07-2023 * Bắt đầu triển khai hàm truy xuất dữ liệu chứng khoán phái sinh. * Kết hợp một hàm sàng lọc cổ phiếu từ TCBS vào thư viện. * Cải thiện hàm stock_historical_data với các cập nhật sau: * Khi độ khung thời gian (resolution) được đặt thành **1D**, cột thời gian sẽ hiển thị theo định dạng ngày **YYYY-mm-dd**. * Thêm một giá trị mới **derivative** cho tham số **type**, cho phép truy xuất dữ liệu phái sinh. * Các tham chiếu hàm trong tệp README đã được cấu trúc theo các tình huống sử dụng thực tế, như Phân tích Kỹ thuật, Phân tích Cơ bản, Sàng lọc Cổ phiếu, vv. Điều này giúp cho tài liệu thân thiện và có tổ chức hơn với người dùng. Phiên bản tiếng Anh của tệp README cũng đã được cập nhật để phù hợp với phiên bản tiếng Việt. ## 22-07-2023 * Bổ sung hướng dẫn vào [Demo Notebook](https://github.com/thinh-vu/vnstock/blob/legacy/demo/gen2_vnstock_demo_index_all_functions_testing_2023.ipynb) giúp người dùng xuất dữ liệu từ Google Colab ra Google Sheets. ## 14-07-2023 * Phát hành phiên bản 0.17 trên PyPI. * Những thay đổi trên nhánh **beta** sẽ được cập nhật vào nhánh **main** và phát hành qua PyPI hàng tháng từ bây giờ. * File README.md đã được cập nhật để đồng bộ hóa phiên bản tiếng Anh và tiếng Việt. * Dữ liệu file listing_companies_enhanced-2023.csv trong thư mục data của repo này được sử dụng để cung cấp dữ liệu công ty niêm yết cho hàm listing_companies. * Hàm mới, price_depth, đã được giới thiệu để lấy giá và khối lượng giao dịch cho danh sách các cổ phiếu. Hàm này có thể được sử dụng song song với hàm price_board. ## 13-07-2023 * Phân loại các tính năng của vnstock trong file Demo Jupyter Notebook theo 5 nhóm chính: 1. Thị trường (Market Watch) 2. Phân tích cơ bản (Fundamental Analysis) 3. Phân tích kỹ thuật (Technical Analysis) 4. Lựa chọn cổ phiếu (Stock Screening) 5. Trung tâm giao dịch (Trading Center) * Đã sửa lại file demo notebook để cập nhật các hàm mới. * Khôi phục giá đơn vị của stock_historical_data từ 1000 VND thành VND bằng cách nhân với 1000. * Hàm **price_board** đã được cập nhật. * Bổ sung hàm mới trong mô đun **utils.py** để trích xuất giá trị ngày tháng theo định dạng YYYY-mm-dd. ## 05-07-2023 * Cập nhật file README.md (áp dụng cho tiếng Việt trước). * Các hàm liên quan đến nguồn dữ liệu SSI không hoạt động đã bị loại bỏ. * Hàm **financial_ratio** đã được cải tiến với các cập nhật sau đây: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị (transpose), với năm/quý đóng vai trò là chỉ mục, giúp sử dụng thuận tiện hơn. * Tham số **is_all** đã trở thành tham số phụ tùy chọn. * Hàm **industry_analysis** và stock_ls_analysis đã được cải thiện: * DataFrame kết quả bây giờ có cấu trúc được chuyển vị, với tên mã cổ phiếu làm tiêu đề cột, giúp dễ sử dụng. * Thêm tham số **lang**, cho phép hiển thị cột DataFrame bằng nhãn tiếng Việt hoặc tiếng Anh. ## 29-06-2023 * Đã cập nhật hàm stock_intraday_data để cung cấp thêm dữ liệu chi tiết trả về bởi hàm và dễ sử dụng hơn * Cập nhật hàm stock_historical_data để hỗ trợ lấy dữ liệu lịch sử về các chỉ số. ## 22-06-2023 * Phát hành phiên bản 0.15 rên Pypi. * Giới thiệu một tính năng mới cho hàm stock_historical_data, cho phép lấy dữ liệu với nhiều độ phân giải thời gian khác nhau. Đã nâng cấp API tương ứng hỗ trợ hàm này. * Bao gồm tham số độ phân giải để cho phép người dùng lấy dữ liệu giá tại các khoảng thời gian 1 phút, 3 phút, 5 phút, 15 phút, 30 phút, 1 giờ hoặc 1 ngày. * Sửa tên cột trong bảng dữ liệu trả về từ tradingDate thành time. * Đã đánh dấu rõ các hàm không khả dụng cho các API liên quan tới SSI. * Tùy chọn **mode='live'** trong hàm listing_companies() đã được loại bỏ. Hàm này bây giờ chỉ đọc danh sách công ty từ tệp csv trên repo github này. * Cập nhật cây thư mục cho github repo, thêm thư mục dữ liệu và thêm tệp dữ liệu, thư mục demo để lưu trữ các tệp demo. ## 07-06-2023 Chính thức hỗ trợ hướng dẫn sử dụng bằng tiếng Việt cho tệp thư viện thông qua file README.md, giúp thúc đẩy khả năng tiếp cận với vnstock cho người dùng Việt Nam. ## 20-05-2023 * Nhánh **main** dành riêng cho các cập nhật quan trọng, trong khi nhánh **beta** được sử dụng cho các cập nhật nhỏ. Từ bây giờ, gói PyPI sẽ phản ánh nội dung của nhánh **main**. * Hàm listing_companies() bây giờ có thể đọc danh sách công ty từ tệp csv trên repo github này hoặc từ một yêu cầu API trực tiếp. * Hàm stock_intraday_data() bây giờ có một giới hạn mới là 100 cho tham số page_size do TCBS thiết lập. --- ## Document: Tự động nạp Agent Skills và tài liệu ## Tổng quan Cơ chế tải động[^1] cho phép các AI Agent trong môi trường lập trình tự động nạp trực tiếp các bộ kỹ năng[^2] và tài liệu hướng dẫn từ hệ thống máy chủ của Vnstock, thay vì phải lưu trữ các tệp tin tĩnh trên máy tính cá nhân. Mục đích của cơ chế này là khắc phục những hạn chế từ phiên bản hướng dẫn lưu trữ trên kho mã nguồn công khai trên GitHub [vnstock-agent-guide](http://github.com/vnstock-hq/vnstock-agent-guide/). Cách triển khai qua Github cho phép tải về toàn bộ tài liệu để nghiên cứu nhưng lại không thuận tiện trong việc cập nhật thường xuyên và tích hợp vào dự án Vibe Coding, dẫn đến tình trạng nội dung bị phân mảnh và không đồng bộ với tài liệu chính thức. Đáng chú ý, phiên bản trên GitHub đôi khi chứa các chỉ dẫn chưa chính xác do thiếu quy trình rà soát như phiên bản nền tảng web. Việc hợp nhất về một nguồn dữ liệu duy nhất[^3] giúp Vnstock kiểm soát chất lượng chặt chẽ hơn, đồng thời mang lại cho người dùng trải nghiệm đồng bộ dù làm việc ở bất kỳ môi trường lập trình nào. ## Cài đặt Để sử dụng tính năng này, bạn cần cài đặt hoặc cập nhật đồng thời cả hai thư viện `vnstock` và `vnai` lên các phiên bản tương thích mới nhất: ```bash pip install -U vnstock>=4.0.5 vnai>=2.5.6 ``` Hệ thống sử dụng thư viện `vnstock` làm công cụ trung gian để quản lý và tải nội dung kỹ năng chính thức. Mã [API Key](/account#api-key) từ tài khoản Vnstock của bạn sẽ được thư viện đọc từ môi trường máy tính của bạn (sau khi bạn đã đăng ký mã này trên máy) để tải các kỹ năng này. Bạn hoàn toàn có thể yêu cầu AI thực hiện bước thiết lập này. ## Kiến trúc hoạt động Hệ thống hoạt động dựa trên sự liên kết giữa máy chủ lưu trữ nền tảng web và thư viện Python ở phía người dùng, đảm bảo cung cấp ngữ cảnh chính xác cho AI. ### 1. Agent Skills Hub (Trung tâm Kỹ năng) Tất cả các bộ kỹ năng dành cho AI được quản lý tập trung tại **Agent Skills Hub**. Dựa vào Mã khóa cá nhân (API Key), hệ thống sẽ tự động phân quyền truy cập các nhóm kỹ năng phù hợp với hạng thành viên của bạn: * **Người dùng Miễn phí (Free):** Được quyền tiếp cận các bộ kỹ năng nền tảng. Nhóm kỹ năng này hướng dẫn AI cách vận hành thư viện `vnstock` bản Cộng đồng (mã nguồn công khai theo giấy phép riêng) để lấy dữ liệu thị trường cơ bản, thiết lập môi trường và cấu hình tự động hóa. * **Người dùng Tài trợ (Sponsor):** Tùy thuộc vào cấp độ gói tài trợ, hệ thống sẽ cung cấp thêm các kỹ năng phân tích chuyên sâu. Những kỹ năng nâng cao này giúp AI tương tác hiệu quả với các luồng dữ liệu mở rộng (như `vnstock_data`, `vnstock_ta`, `vnstock_news`), hỗ trợ bạn thực hiện các bài toán phân tích định lượng phức tạp. Bên cạnh các bộ kỹ năng, Agent Skills Hub cũng tự động cho phép AI Agent đọc trực tiếp toàn bộ tài liệu hướng dẫn chính thức trên web thông qua API, giúp AI luôn nắm bắt kịp thời những cập nhật mới nhất mà không cần bạn phải sao chép thủ công. ### 2. Trải nghiệm Tự động hóa với AI Thư viện `vnstock` đóng vai trò là cầu nối giữa bạn và Agent Skills Hub. Quá trình nạp kỹ năng diễn ra tự động ngầm thông qua các quy tắc đã được cài đặt sẵn (như file `AGENTS.md`) trên môi trường của bạn. Thay vì phải tự viết code hay quan tâm đến các hàm nạp dữ liệu nội bộ, **bạn chỉ cần ra lệnh bằng ngôn ngữ tự nhiên** để sử dụng các tính năng của thư viện: * Yêu cầu AI lấy dữ liệu thị trường, truy xuất báo cáo tài chính hoặc phân tích kỹ thuật. * Yêu cầu AI tự động tra cứu tài liệu hướng dẫn (docs) mới nhất của một hàm cụ thể. AI sẽ tự động duyệt danh mục để tìm đúng bộ kỹ năng cần thiết, nạp trực tiếp vào bộ nhớ đệm để làm bối cảnh xử lý tác vụ, và tự động giải phóng không gian này hoàn toàn khi bạn đóng phiên làm việc. ### 3. Cấu hình quy tắc tự động Khi bạn khởi tạo dự án và sử dụng thư viện `vnstock`, hệ thống sẽ tự động thiết lập các file chỉ dẫn AGENTS.md[^4] vào tệp tin cấu hình của những môi trường lập trình của bạn. File này định hướng AI ưu tiên sử dụng các hàm nạp dữ liệu động thay vì tự phỏng đoán thông tin.
Các file hướng dẫn được gắn kèm điều kiện kích hoạt[^5] cụ thể. Trí tuệ nhân tạo chỉ áp dụng các quy định khắt khe này khi phát hiện dự án đang tương tác trực tiếp với hệ sinh thái Vnstock, hoàn toàn không ảnh hưởng đến các dự án lập trình độc lập khác của bạn.
### 4. Tùy chỉnh bật/tắt cá nhân hóa Agent Mặc định, `vnstock` sẽ tự động cấu hình và nạp các kỹ năng để tối ưu hóa trải nghiệm sử dụng AI của bạn. Tuy nhiên, nếu bạn muốn toàn quyền kiểm soát môi trường làm việc hoặc không muốn hệ thống tự động can thiệp vào cấu hình Agent, bạn có thể vô hiệu hóa tính năng này bằng cách khai báo các biến môi trường sau (vnai>=2.5.9): - `VNSTOCK_DISABLE_AGENT_SETUP=1`: Vô hiệu hóa hoàn toàn quá trình tự động thiết lập và cập nhật cấu hình cho AI Agent trên máy của bạn. - `VNSTOCK_DISABLE_GLOBAL_AGENT=1`: Ngăn chặn việc tự động nạp (inject) các file cấu hình hướng dẫn Agent ở phạm vi toàn cục (global config). Bạn có thể thiết lập các biến môi trường này trong file `.env` của dự án hoặc khai báo trực tiếp trên cửa sổ dòng lệnh (terminal) trước khi khởi chạy dự án. ## Bản quyền và Sử dụng Toàn bộ nội dung các bộ kỹ năng (Agent Skills), tài liệu hướng dẫn và mã nguồn liên quan được cung cấp thông qua hệ thống này đều thuộc bản quyền sở hữu trí tuệ của Vnstock.

Người dùng được cấp quyền sử dụng và cá nhân hoá các tài nguyên này nhằm phục vụ trực tiếp cho quá trình học tập, nghiên cứu và phát triển dự án. Tuy nhiên, nghiêm cấm mọi hành vi sao chép, trích xuất dữ liệu trái phép nhằm mục đích vô hiệu hóa hoặc vượt qua cơ chế xác thực tài khoản của hệ thống.

Mọi hành động tái phân phối, chia sẻ công khai, hoặc thương mại hóa tài sản trí tuệ của Vnstock dưới mọi hình thức đều cấu thành hành vi vi phạm bản quyền và sẽ bị xử lý nghiêm ngặt theo các quy định hiện hành.

[^1]: **Tải động (Dynamic Loading):** Nạp dữ liệu trực tiếp từ máy chủ qua API khi cần, thay vì lưu trữ tệp tĩnh. [^2]: **Bộ kỹ năng (Agent Skills):** Các tập lệnh và hướng dẫn chuyên biệt giúp AI hiểu kiến trúc hệ thống và thực thi tác vụ Vnstock hiệu quả. [^3]: **Nguồn dữ liệu duy nhất (Single Source of Truth - SSOT):** Nguyên tắc lưu trữ và cập nhật thông tin từ một nền tảng thống nhất, tránh sai lệch. [^4]: **Tập luật khởi tạo (Bootstrap Instruction):** Các quy tắc nền tảng tự động nạp lúc khởi động để thiết lập hành vi và giới hạn cho AI. [^5]: **Điều kiện kích hoạt (Trigger Condition):** Tiêu chí xác định thời điểm một quy tắc hay chức năng cụ thể được phép thực thi. --- ## Document: Sao chép có định dạng, in và xuất PDF từ Markdown Không phải người nhận nào cũng làm việc trực tiếp với file `.md`. Markdown Live Editor giúp chuyển nội dung đã biên tập sang công cụ văn phòng hoặc bản in mà không phải dựng lại định dạng bằng tay. ## Sao chép tài liệu kèm định dạng Nút sao chép của chế độ trực quan ghi cả hai dạng dữ liệu vào bộ nhớ tạm: * HTML để ứng dụng hỗ trợ văn bản có định dạng giữ tiêu đề, chữ nhấn mạnh, danh sách, bảng và liên kết. * Plain text làm phương án tương thích với ứng dụng chỉ nhận văn bản. Bạn có thể dán nội dung vào Microsoft Word, Google Docs, email hoặc cửa sổ trò chuyện. Kết quả cuối cùng phụ thuộc vào khả năng xử lý HTML của ứng dụng đích; nên kiểm tra bảng, khối mã và hình ảnh sau khi dán. ## Khi nào nên sao chép kèm định dạng? * Gửi một phần tài liệu trong email mà người nhận không dùng Markdown. * Chuyển bản nháp sang Google Docs để cùng biên tập với nhóm nội dung. * Dán bảng và danh sách vào Word mà không dựng lại thủ công. * Đưa nội dung đã trình bày vào cửa sổ trò chuyện để giữ cấu trúc dễ đọc. Nếu người nhận cần tiếp tục làm việc bằng Git hoặc bảo toàn mã nguồn chính xác, hãy chia sẻ file Markdown thay vì văn bản có định dạng. ## Xem trước bản in Tính năng **Print** (In) mở bản xem trước được dàn trang bằng Paged.js[^pagedjs]. Từ cửa sổ trình duyệt, bạn có thể in hoặc chọn **Save as PDF** (Lưu thành PDF). Luồng thực tế gồm: 1. Rà soát tài liệu trong chế độ trực quan. 2. Mở bản xem trước khi in. 3. Kiểm tra ngắt trang, bảng, hình ảnh, đầu trang và chân trang. 4. Dùng hộp thoại in của trình duyệt để in hoặc lưu PDF. ## Cấu hình đầu trang, chân trang và số trang Các thiết lập chính: | Setting | Mặc định | Mục đích | | ------------------------------------ | ------------------------- | ------------------------------ | | `markdownLive.printHeaderFormat` | `{title}` | Nội dung đầu trang | | `markdownLive.printFooterFormat` | `{signature}` | Nội dung chân trang | | `markdownLive.printPageNumberFormat` | `{page}` | Đánh số trang; để trống để tắt | | `markdownLive.printFontFamily` | Phông chữ trình soạn thảo | Phông chữ dùng khi in | | `markdownLive.printAutoTOC` | `false` | Tạo mục lục ở đầu bản in | ## Dùng thông tin YAML làm biến khi in Bạn có thể khai báo thông tin mô tả ở đầu file: ```yaml --- title: Báo cáo kiến trúc author: Vnstock signature: Engineering Team website: https://vnstocks.com --- ``` Sau đó tham chiếu trong cấu hình: ```text Đầu trang: {title} — {author} Chân trang: {signature} · {website} ``` Biến không tồn tại sẽ không thể tạo ra nội dung mong muốn, vì vậy hãy kiểm tra phần thông tin YAML ở đầu file trước khi xuất bản. ## Tạo mục lục tự động Bật `markdownLive.printAutoTOC` để thêm mục lục dựa trên tiêu đề vào đầu bản in. Trước khi lưu PDF, hãy kiểm tra: * Mỗi tài liệu có một H1 rõ ràng. * Các phần con dùng H2/H3 đúng thứ bậc. * Heading ngắn và mô tả đúng nội dung. * Không nhảy cấp tiêu đề chỉ để thay đổi kích thước chữ. ## Checklist trước khi gửi tài liệu * Mermaid và công thức đã hiển thị đúng. * Bảng rộng không bị cắt ở mép trang. * Hình ảnh có độ phân giải phù hợp. * Liên kết nội bộ cần thiết đã được chuyển thành địa chỉ người nhận truy cập được. * Đầu trang và chân trang không chứa biến thay thế rỗng. * Mục lục và số trang đúng. * Không còn ghi chú rà soát chưa được xử lý. ## Tiếp tục khám phá * [Bắt đầu với Obsidian-style Markdown Editor](/docs/tien-ich/markdown-live-editor/gioi-thieu-va-cai-dat) * [Rà soát Markdown cùng AI](/docs/tien-ich/markdown-live-editor/review-markdown-cung-ai-agent) * [Giao diện và Thao tác Điều hướng](/docs/tien-ich/markdown-live-editor/giao-dien-va-thao-tac) * [Cú pháp Markdown được hỗ trợ](/docs/tien-ich/markdown-live-editor/cu-phap-markdown-ho-tro) * [Liên kết nội bộ, liên kết ngược và đồ thị](/docs/tien-ich/markdown-live-editor/wikilinks-backlinks-va-graph-view) * [Quản lý hình ảnh và mẫu tài liệu](/docs/tien-ich/markdown-live-editor/quan-ly-hinh-anh-va-template) [^pagedjs]: **Paged.js** là thư viện dàn nội dung web thành các trang phù hợp để in hoặc lưu thành PDF. --- ## Document: Cú pháp Markdown, Mermaid và LaTeX được hỗ trợ Khả năng render hoàn hảo các tài liệu kỹ thuật chính là nơi **Markdown Live Editor** tỏa sáng nhất. Kế thừa triết lý từ Obsidian và GitHub, tiện ích không chỉ dừng lại ở cú pháp Markdown cơ bản mà còn mở rộng hỗ trợ toàn diện các khối nội dung nâng cao như toán học LaTeX, sơ đồ Mermaid, khối lưu ý Admonitions, liên kết nội bộ Wikilink và hệ thống Template. ## 1. Cú pháp Markdown Chuẩn (GitHub Flavored Markdown) ![Cú pháp markdown cơ bản](/images/markdown-live-editor/basic-markdown-syntax.png) Tiện ích hỗ trợ đầy đủ các định dạng Markdown tiêu chuẩn phổ biến: * **Tiêu đề phân cấp**: Hỗ trợ từ H1 đến H6 (`#` đến `######`). * **Định dạng phông chữ**: In đậm (`**chữ đậm**`), in nghiêng (`*chữ nghiêng*`), gạch ngang (`~~gạch ngang~~`). * **Danh sách linh hoạt**: * Danh sách không thứ tự (`*` hoặc `-`). * Danh sách có thứ tự (`1.`, `2.`). * Danh sách công việc Task list (`- [ ] Chưa xong` và `- [x] Đã hoàn thành`). * **Khối trích dẫn (Blockquote)**: Bắt đầu bằng dấu `>`. * **Mã nguồn**: Mã trong dòng (Inline code `` `code` ``) và khối mã nguồn nhiều dòng (Code block ` ``` `) với tính năng tô màu cú pháp (Syntax Highlighting) chuyên nghiệp. * **Đường phân cách nội dung**: Sử dụng `---` hoặc `***`. *** ## 2. Bảng biểu Trực quan & Tùy biến Hiển thị Bảng trong Markdown thuần thường tốn nhiều công sức căn chỉnh thủ công. Với Live Editor: * **Chỉnh sửa trực quan qua chuột phải**: Nhấp chuột phải vào bảng để *Thêm hàng/cột*, *Xóa hàng/cột*, hoặc *Xóa bảng* mà không cần căn thủ công từng dấu gạch đứng `|`. ![Menu ngữ cảnh cho bảng](/images/markdown-live-editor/table-context-menu-markdown-live-editor.png) * **Tùy biến chế độ hiển thị**: Cấu hình thông qua thiết lập `markdownLive.tableDisplayMode`: ![Cài đặt chế độ hiển thị bảng](/images/markdown-live-editor/table-display-settings.png) * `scroll`: Giữ nguyên cấu trúc dữ liệu theo cột và cho phép cuộn ngang (rất thích hợp cho bảng dữ liệu tài chính nhiều cột). * `wrap`: Tự động xuống dòng nội dung ô để bảng luôn vừa vặn với độ rộng màn hình. *** ## 3. Khối Lưu ý & Cảnh báo (Admonitions / Callouts) ![Các dạng khối cảnh báo phổ biến được hỗ trọ](/images/markdown-live-editor/obsidian-style-callouts-markdown-live-editor.png) Tạo điểm nhấn thị giác cho tài liệu bằng các khối cảnh báo và ghi chú theo chuẩn Obsidian / GitHub: ```markdown > [!NOTE] > Đây là khối ghi chú cung cấp thêm thông tin hữu ích cho người đọc. > [!TIP] > Mẹo nhỏ giúp tối ưu hóa thao tác khi soạn thảo. > [!WARNING] > Cảnh báo quan trọng cần kiểm tra kỹ trước khi tiếp tục. ``` Các loại Admonition được hỗ trợ đầy đủ kèm màu sắc và icon đặc trưng bao gồm: * **Thông tin & Ghi chú:** `note`, `info` (Thông tin chung hoặc bổ sung). * **Mẹo & Hướng dẫn:** `tip` (Mẹo và gợi ý hữu ích). * **Quan trọng & Tóm tắt:** `important`, `abstract` (Điểm quan trọng hoặc tóm tắt nội dung). * **Cảnh báo & Rủi ro:** `warning`, `caution` (Cảnh báo rủi ro hoặc lưu ý mức độ cao). * **Trạng thái & Lỗi:** `success`, `done`, `error`, `bug`, `fail`, `danger` (Báo cáo thành công, hoàn thành hoặc lỗi nghiêm trọng). * **Khác:** `quote` (Trích dẫn), `example` (Ví dụ minh họa), `question`, `todo` (Câu hỏi hoặc việc cần làm). *** ## 4. Công thức Toán học LaTeX (KaTeX) ![Hiển thị công thức toán học](/images/markdown-live-editor/katex-cong-thuc-toan-hoc-markdown-live-editor.png) Được trợ lực bởi thư viện KaTeX hiệu năng cao, các công thức toán học đều được render sắc nét, chuẩn mực như trên tạp chí khoa học: * **Công thức trong dòng (Inline)**: Bao bọc công thức bằng một cặp dấu `$`, ví dụ `$E(R) = \sum p_i r_i$`. * **Công thức khối (Block)**: Tách thành khối độc lập bằng cặp dấu `$$`: ```markdown $$ \sigma^2 = \sum_{i=1}^{n} p_i (r_i - E(R))^2 $$ ``` Công thức được hiển thị trực tiếp ngay trong quá trình gõ, giúp bạn dễ dàng rà soát ký hiệu mà không phải đọc mã LaTeX thô. *** ## 5. Lưu đồ Mermaid Phác thảo kiến trúc hệ thống, quy trình nghiệp vụ hoặc luồng dữ liệu trực tiếp bằng mã Mermaid ngay trong tài liệu mà không cần phần mềm vẽ sơ đồ rời: ````markdown ```mermaid sequenceDiagram participant Alice participant Bob Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts
prevail! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good! ``` ```` sẽ hiển thị ![Lưu đồ Mermaid trong Markdown Live Editor](/images/markdown-live-editor/mermaid-diagram-markdown-live-editor.png) ### Tính năng tương tác trên sơ đồ Mermaid: * **Thanh công cụ nổi**: Phóng to (Zoom In), thu nhỏ (Zoom Out), đặt lại tỷ lệ (Reset) và xem toàn màn hình (Fullscreen). * **Chỉnh sửa nhanh**: Nhấp đúp vào sơ đồ trong Live Mode để mở khung chỉnh sửa mã Mermaid trực tiếp. * **Tự động thích ứng theme**: Màu sắc sơ đồ tự động đồng bộ theo giao diện Sáng / Tối (Light / Dark theme) của VS Code. *** ## 6. Thẻ HTML Tương tác HTML viết xen trong Markdown được hiển thị an toàn và chuẩn xác ở chế độ trực quan, tiêu biểu là các khối đóng/mở nội dung `
` và ``: ```html
Nhấp để xem giải thích chi tiết Nội dung chi tiết được ẩn bên trong khối có thể đóng/mở tương tác trực tiếp ngay khi đang soạn thảo.
``` Khi cần kiểm soát chi tiết từng thuộc tính HTML phức tạp, bạn có thể chuyển sang **Source Mode** bằng phím tắt `Alt + M` (hoặc `Opt + M` trên macOS). *** ## 7. Chú thích cuối trang & Thẻ * **Chú thích cuối trang (Footnotes)**: Giúp tài liệu học thuật và báo cáo nghiên cứu trở nên chuyên nghiệp: ```markdown Nhận định này dựa trên phân tích dữ liệu thị trường năm 2024.[^1] [^1]: Báo cáo phân tích định lượng dữ liệu chứng khoán Vnstock 2024. ``` * **Thẻ (Hashtags)**: Đặt các thẻ như `#nghien-cuu`, `#kien-truc` trong nội dung. Thẻ sẽ được nhận diện và hỗ trợ tìm kiếm, phân nhóm trong đồ thị liên kết Graph View. *** ## 8. Liên kết nội bộ & Nhúng Ghi chú * **Liên kết nội bộ (Wikilink[^wikilink])**: Cú pháp liên kết phong cách Obsidian giúp kết nối các tài liệu với nhau: ```markdown [[tong-quan-kien-truc]] [[tong-quan-kien-truc|Tài liệu Kiến trúc Hệ thống]] ``` Gõ `[[` để mở danh sách gợi ý tự động tìm file trong không gian làm việc. * **Nhúng toàn bộ nội dung file (Transclusion)**: ```markdown ![[gioi-thieu-chung]] ``` Tiện ích sẽ tự động đọc file được chỉ định, lược bỏ phần YAML Frontmatter ở đầu và nhúng trực tiếp nội dung vào vị trí đặt lệnh. File nguồn vẫn độc lập, rất tiện lợi khi tái sử dụng các đoạn văn mẫu, quy ước chung hoặc phần mở đầu. *** ## 9. Siêu dữ liệu YAML - thuộc tính YAML ghi chú Phần siêu dữ liệu ở đầu file (được bao bọc bởi `---`) được tách biệt thành bảng **Properties** hiện đại có thể thu gọn: ```yaml --- title: "Báo cáo Phân tích Kỹ thuật" author: "Vnstock Team" tags: - chung-khoan - phan-tich-dinh-luong color: "#6c8cff" --- ``` Các thuộc tính này hỗ trợ quản lý dữ liệu bài viết, tự động hiển thị tiêu đề khi xuất bản in/PDF, và trường `color` sẽ định hình màu sắc điểm nút đại diện cho file trên Graph View. *** ## 10. Hệ thống mẫu ghi chú **Markdown Live Editor** tích hợp sẵn hệ thống chèn mẫu tài liệu, tương thích ngược với các cú pháp phổ biến của **Templater** trong Obsidian: Để sử dụng, hãy thiết lập thư mục chứa file mẫu trong cài đặt `markdownLive.templateFolder` (mặc định: `.vscode/templates`). ### Các Placeholder thông dụng: | Cú pháp | Ý nghĩa & Hoạt động | | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `<% tp.file.title %>` | Tự động lấy tên file hiện tại (không kèm đuôi `.md`), hữu ích khi tạo tiêu đề H1 tự động (`# <% tp.file.title %>`). | | `<% tp.date.now() %>` | Chèn ngày hiện tại theo định dạng chuẩn `YYYY-MM-DD`. | | `<% tp.date.now("format") %>` | Chèn ngày tháng theo định dạng tùy chỉnh. Hỗ trợ các token `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`. Ví dụ: `<% tp.date.now("DD/MM/YYYY HH:mm") %>`. |
Nhấn Ctrl + Shift + E (hoặc Cmd + Shift + E trên macOS) để mở menu danh sách Template và chèn ngay vào vị trí con trỏ.
*** Tiếp theo: [Liên kết nội bộ, liên kết ngược và đồ thị](/docs/tien-ich/markdown-live-editor/wikilinks-backlinks-va-graph-view). [^wikilink]: **Wikilink** là cú pháp liên kết nội bộ dạng `[[ten-ghi-chu]]`, chuẩn phổ biến trong Obsidian và các hệ thống quản lý tri thức Zettelkasten. --- ## Document: Giao diện và Thao tác # Giao diện và Thao tác Điều hướng Sức mạnh lớn nhất của **Markdown Live Editor** nằm ở khả năng dung hòa sự thanh lịch của một ứng dụng ghi chú hiện đại với tính chính xác, chặt chẽ của một môi trường phát triển (IDE). Bạn không bao giờ bị khóa chặt vào một góc nhìn duy nhất mà có thể linh hoạt chuyển đổi theo từng tác vụ. ## 1. Kiến trúc Giao diện Kép (Live Preview & Source Mode) Tùy thuộc vào nhu cầu làm việc, bạn có thể chuyển đổi mượt mà giữa hai chế độ soạn thảo: * **Live Editor (Trực quan)**: Xây dựng trên nền tảng Milkdown[^milkdown], đây là chế độ xem và soạn thảo Markdown trực quan (WYSIWYG). Mọi cú pháp tiêu đề, in đậm, bảng biểu, công thức KaTeX hay sơ đồ Mermaid đều được hiển thị định dạng ngay lập tức. * *Phù hợp khi*: Đọc và biên tập tài liệu dài, rà soát nội dung AI tạo ra, tập trung vào câu chữ thay vì ký hiệu Markdown, kiểm tra bố cục trực quan, hoặc chọn đoạn văn bản để gửi ngữ cảnh sang AI. * **Source Mode (Mã nguồn)**: Sử dụng CodeMirror 6[^codemirror], cung cấp trải nghiệm highlight cú pháp chuẩn mực, quen thuộc với lập trình viên. * *Phù hợp khi*: Chỉnh sửa YAML Frontmatter ở đầu file, kiểm tra ký tự thoát/khoảng trắng, xử lý khối HTML phức tạp, hoặc dán các khối Markdown lớn.
Nhờ thuật toán đồng bộ cuộn dựa trên tỷ lệ tiến trình, khi bạn chuyển đổi qua lại giữa hai chế độ, màn hình luôn giữ nguyên vị trí ngữ cảnh đang làm việc. Thêm vào đó, nút Open in Text Editor cho phép bạn nhanh chóng mở file bằng trình soạn thảo văn bản mặc định của VS Code để sử dụng các extension khác hoặc tiếp tục quy trình Git quen thuộc.
*** ## 2. Thanh công cụ (Toolbar) ![Thanh công cụ của Markdown Live Edito](/images/markdown-live-editor/markdown-live-editor-toolbar.png) Được hiển thị tối giản ở phía trên cùng của giao diện, thanh công cụ giúp bạn truy cập nhanh tất cả các định dạng và tính năng mở rộng một cách trực quan: * **Lịch sử chỉnh sửa**: * **Menu Hoàn tác & Làm lại** (Chứa tính năng Undo và Redo) * **Cấu trúc tài liệu (Headings)**: * `¶ Paragraph` **Dropdown Heading**: Chuyển đổi linh hoạt giữa văn bản thường (Paragraph) và các cấp độ thẻ tiêu đề từ H1 đến H6. * **Định dạng văn bản cơ bản**: * **In đậm** (Bold) * **In nghiêng** (Italic) * **Gạch ngang** (Strikethrough) * **Trích dẫn** (Blockquote) * **Chú thích / Chỉ số trên** (Footnote / Superscript) * **Mã nguồn**: * **Mã nguồn nội tuyến / Khối mã nguồn** (Inline Code / Code block) * **Danh sách (Lists)**: * **Menu Danh sách**: Trình đơn thả xuống để chèn danh sách không thứ tự (Bullet), danh sách có thứ tự (Ordered), và danh sách công việc (Task list). * **Chèn Liên kết & Đa phương tiện**: * **Liên kết thường** (Link) * **Liên kết nội bộ Obsidian** (Wikilink `[[]]`) * **Chèn Hình ảnh** (Image) * **Chèn Bảng biểu** (Table) * **Chèn Mục lục** (Table of Contents) * **Hộp thông báo**: * **Menu Admonition**: Trình đơn thả xuống để chèn các khối cảnh báo (Note, Tip, Important, Warning, Caution). * **Tiện ích & Xuất bản**: * **Tìm kiếm & Thay thế** (Find & Replace) * **Xuất file PDF** (Export PDF) * **Sao chép Rich Text kèm định dạng** (Copy HTML Clipboard) * **Điều khiển giao diện**: * **Menu Thu/Phóng** (Zoom In / Zoom Out) * **Bật/Tắt chế độ Mã nguồn** (Toggle Source Mode) * **Mở bằng VS Code Text Editor** (Plain Text Editor) *** ## 3. Câu lệnh nhanh `/` (Slash Commands) Lấy cảm hứng từ Obsidian và Notion, bạn chỉ cần gõ dấu `/` khi soạn thảo, một menu lệnh sẽ xuất hiện. Không cần rời tay khỏi bàn phím, bạn có thể dùng các phím ↓, ↑ và Enter để chọn chèn nhanh các định dạng phổ biến: * Tiêu đề (H1 - H3) * Danh sách (Bullet, Ordered, Task List) * Thành phần phức tạp: Blockquote, Code Block, Table, Image * Cấu trúc đặc thù: YAML Frontmatter, Footnote *** ## 4. Tìm kiếm & Thay thế Nhấn phím tắt `Ctrl + F` (hoặc `Cmd + F` trên macOS) hoặc nhấp biểu tượng kính lúp trên Toolbar để mở thanh tìm kiếm nội tuyến: * **Tìm kiếm toàn diện**: Quét và làm nổi bật tất cả kết quả khớp trong tài liệu. * **Điều hướng nhanh**: Nhảy tới kết quả trước/sau tức thì. * **Bộ lọc chính xác**: Hỗ trợ phân biệt chữ hoa/chữ thường (Match Case). * **Thay thế linh hoạt**: Thay thế từng vị trí hoặc Thay thế tất cả (Replace All) mà không cần chuyển sang chế độ mã nguồn. ## 5. Mục lục nội dung (TOC) Mục lục nổi thông minh tự động theo dõi cấu trúc các thẻ tiêu đề H1–H4: * Nhấp vào từng mục tiêu đề để cuộn mượt mà đến phần tương ứng. * Tự động thu gọn khi không sử dụng để giải phóng không gian soạn thảo, hoặc ghim cố định khi làm việc với tài liệu dài. *** ## 6. Phím tắt (Shortcuts) Các phím tắt được thiết kế tinh tế giúp duy trì tốc độ gõ phím. Hệ thống tự động phân biệt giữa hệ điều hành Windows/Linux và macOS: | Lệnh / Hành động | Phím tắt (Windows/Linux) | Phím tắt (macOS) | | :------------------------------ | :----------------------- | :----------------------- | | **Mở Markdown Live Editor** | `Ctrl + Alt + Shift + M` | `Cmd + Ctrl + Shift + M` | | **Lưu file hiện tại** | `Ctrl + S` | `Cmd + S` | | **Gửi bối cảnh tới AI Agent** | `Ctrl + Shift + L` | `Cmd + Shift + L` | | **Chèn Template** | `Ctrl + Shift + E` | `Cmd + Shift + E` | | **Chèn Liên kết (Link)** | `Ctrl + K` | `Cmd + K` | | **Chèn Hình ảnh** | `Ctrl + Shift + I` | `Cmd + Opt + I` | | **Chèn Bảng biểu** | `Ctrl + Shift + T` | `Cmd + Opt + T` | | **Chèn Code Block** | `Ctrl + Shift + C` | `Cmd + Opt + C` | | **Chèn Trích dẫn (Blockquote)** | `Ctrl + Shift + Q` | `Cmd + Opt + Q` | | **In đậm (Bold)** | `Ctrl + Shift + B` | `Cmd + Opt + B` | | **In nghiêng (Italic)** | `Ctrl + I` | `Cmd + I` | | **Chèn Heading 1 -> 6** | `Ctrl + Shift + 1 -> 6` | `Cmd + Opt + 1 -> 6` | | **Bật/Tắt Graph View** | `Ctrl + Shift + G` | `Cmd + Shift + G` | | **Tìm kiếm (Find)** | `Ctrl + F` | `Cmd + F` | | **Bật/Tắt Live Mode** | `Alt + M` | `Opt + M` | | **Zoom In/Out** | `Ctrl + =` / `Ctrl + -` | `Cmd + =` / `Cmd + -` | *** ## 7. Tùy biến Cấu hình (Settings) ![Mở cài đặt tiện ích mở rộng Markdown Live Editor từ Extensions](/images/markdown-live-editor/mo-cai-dat-tien-ich-markdown-live-editor.png) Extension cung cấp các thiết lập tại **User / Workspace Settings** (nhấn phím tắt `Cmd + ,` trên macOS hoặc `Ctrl + ,` trên Windows/Linux và tìm kiếm từ khóa `Markdown Live`), cho phép bạn tinh chỉnh môi trường làm việc theo đúng nhu cầu: ![Giao diện tùy chỉnh cấu hình Markdown Live Editor trong Settings](/images/markdown-live-editor/user-settings-markdown-live-editor.png)
### Cấu hình chung (General) * **Language** (`markdownLive.language`): * **Mô tả:** Lựa chọn ngôn ngữ giao diện hiển thị cho Markdown Live Editor (menu ngữ cảnh, thanh công cụ, thông báo trạng thái). * **Giá trị nhận:** * `en` (Mặc định): Tiếng Anh. * `vi`: Tiếng Việt. * **Table Display Mode** (`markdownLive.tableDisplayMode`): * **Mô tả:** Chế độ hiển thị bảng biểu trong trình soạn thảo trực quan. * **Giá trị nhận:** * `scroll` (Mặc định): Bật thanh cuộn ngang khi bảng có nhiều cột hoặc dữ liệu dài, giúp bảo toàn cấu trúc cột mà không làm vỡ bố cục. * `wrap`: Tự động ngắt chữ xuống dòng trong các ô dữ liệu để toàn bộ bảng luôn hiển thị vừa vặn trong khung nhìn. ### Trình soạn thảo & Giao diện (Editor & UI) * **Font Family** (`markdownLive.fontFamily`): * **Mô tả:** Bộ phông chữ hiển thị trong chế độ soạn thảo trực quan (WYSIWYG). * **Giá trị nhận:** * `sans-serif` (Mặc định): Phông chữ không chân hiện đại, thanh thoát và dễ đọc. * `serif`: Phông chữ có chân phong cách báo chí truyền thống, mang lại trải nghiệm đọc viết trang nhã (tương tự Medium hoặc Substack). * **Enable Slash Command** (`markdownLive.enableSlashCommand`): * **Mô tả:** Bật hoặc tắt menu gợi ý lệnh nhanh khi gõ ký tự gạch chéo `/` trong trình soạn thảo. * **Giá trị nhận:** * `true` (Mặc định): Hiển thị menu gợi ý để chèn nhanh tiêu đề, danh sách, khối mã nguồn, hình ảnh hoặc bảng. * `false`: Tắt menu Slash command nếu bạn muốn gõ ký tự `/` tự do mà không làm xuất hiện popup. ### Không gian làm việc & Quản lý ghi chú (Workspace & Notes) * **Default Note Directory** (`markdownLive.defaultNoteDirectory`): * **Mô tả:** Thư mục mặc định để lưu trữ ghi chú mới khi bạn nhấn biểu tượng **New Note** trên thanh bên (Sidebar). Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc của workspace, ví dụ: `notes/journal` hoặc `content/docs`). Mặc định để trống `""` (sẽ tạo ghi chú mới ngay tại thư mục gốc workspace). * **Sidebar Scan Directory** (`markdownLive.sidebarScanDirectory`): * **Mô tả:** Thư mục chỉ định để thanh bên Markdown Live quét và hiển thị danh sách tài liệu. Giúp tối ưu hiệu năng và giữ thanh bên gọn gàng trong các dự án lớn, monorepo hoặc website có cấu trúc thư mục phức tạp. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Ví dụ: `content/docs` hoặc `notes`). Mặc định để trống `""` (quét toàn bộ workspace). * **Template Folder** (`markdownLive.templateFolder`): * **Mô tả:** Thư mục lưu trữ các file mẫu tài liệu Markdown (.md) dùng để chèn nhanh mẫu vào bài viết hiện tại hoặc tạo ghi chú mới từ template. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc, ví dụ: `templates` hoặc `.vscode/templates`). Mặc định để trống `""` (tắt tính năng template). * **Enable Graph View** (`markdownLive.enableGraphView`): * **Mô tả:** Bật hoặc tắt tính năng hiển thị Biểu đồ liên kết cục bộ (Local Graph View) trong thanh bên để theo dõi các liên kết hai chiều (Backlinks / Outlinks). * **Giá trị nhận:** * `true` (Mặc định): Kích hoạt biểu đồ liên kết cục bộ. * `false`: Tắt biểu đồ liên kết cục bộ. * **Graph Depth** (`markdownLive.graphDepth`): * **Mô tả:** Độ sâu quét liên kết mặc định hiển thị trên biểu đồ Local Graph (xác định số cấp bậc láng giềng liên kết mở rộng từ tài liệu hiện tại). * **Giá trị nhận:** `số nguyên từ 1 đến 10` (Mặc định: `2`). ### Quản lý Hình ảnh (Images) * **Image Directory** (`markdownLive.imageDirectory`): * **Mô tả:** Thư mục tự động lưu trữ file ảnh khi bạn dán (paste) trực tiếp từ clipboard vào tài liệu Markdown. Khuyến nghị cấu hình trong **Workspace Settings**. * **Giá trị nhận:** `chuỗi ký tự` (Đường dẫn tương đối từ thư mục gốc, ví dụ: `assets/images` hoặc `public/images`). Mặc định: `assets/images`. * **Image Public Path** (`markdownLive.imagePublicPath`): * **Mô tả:** Tiền tố thư mục áp dụng cho các đường dẫn ảnh tuyệt đối (bắt đầu bằng `/`) trong Markdown để trình soạn thảo hiển thị đúng ảnh cục bộ trong chế độ xem trước trực tiếp. Ví dụ: trong các framework web như Next.js hay Docusaurus, ảnh được viết dạng `![Ảnh](/images/banner.png)` nhưng file vật lý lưu tại `public/images/banner.png`, bạn điền `public` (hoặc `/public`) vào thiết lập này. * **Giá trị nhận:** `chuỗi ký tự` (Ví dụ: `public` hoặc `static`). Mặc định để trống `""` (phân giải trực tiếp từ thư mục gốc workspace). ### In ấn & Xuất bản PDF (Printing & Export) * **Print Header Format** (`markdownLive.printHeaderFormat`): * **Mô tả:** Định dạng nội dung tiêu đề đầu trang (Header) khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, hỗ trợ các biến YAML Frontmatter như `{title}`, `{author}`, `{date}`. Mặc định: `"{title}"`. * **Print Footer Format** (`markdownLive.printFooterFormat`): * **Mô tả:** Định dạng nội dung chân trang (Footer) khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, hỗ trợ các biến YAML Frontmatter như `{signature}`, `{website}`. Mặc định: `"{signature}"`. * **Print Page Number Format** (`markdownLive.printPageNumberFormat`): * **Mô tả:** Định dạng hiển thị số trang khi in hoặc xuất tài liệu ra file PDF. * **Giá trị nhận:** `chuỗi ký tự`, sử dụng biến `{page}` để hiển thị số trang hiện tại (ví dụ: `Trang {page}` hoặc `Page {page}`). Mặc định: `"{page}"`. Để trống `""` nếu muốn tắt đánh số trang. * **Print Font Family** (`markdownLive.printFontFamily`): * **Mô tả:** Bộ phông chữ tùy chỉnh áp dụng riêng khi in hoặc xuất bản tài liệu sang file PDF. * **Giá trị nhận:** `chuỗi tên font` (Ví dụ: `'Times New Roman, serif'` hoặc `'Arial, sans-serif'`). Mặc định để trống `""` (sử dụng phông chữ mặc định của trình soạn thảo). * **Print Auto TOC** (`markdownLive.printAutoTOC`): * **Mô tả:** Tự động tạo và chèn Mục lục (Table of Contents) ở đầu tài liệu khi in hoặc xuất file PDF. * **Giá trị nhận:** * `true`: Tự động chèn mục lục vào bản in/file PDF. * `false` (Mặc định): Không tự động chèn mục lục. *** Tiếp theo: [Cú pháp Markdown, Mermaid và LaTeX được hỗ trợ](/docs/tien-ich/markdown-live-editor/cu-phap-markdown-ho-tro). [^milkdown]: **Milkdown** là nền tảng mã nguồn mở dùng để xây trình soạn thảo Markdown trực quan (WYSIWYG) dạng Plugin-driven. [^codemirror]: **CodeMirror 6** là thành phần soạn thảo mã nguồn hiện đại, hiệu năng cao chạy trong môi trường web/webview. --- ## Document: Giới thiệu & Cài đặt # Obsidian-style Markdown Editor: Trải nghiệm viết liền mạch ngay trong VS Code **Obsidian-style Markdown Editor** (hay *Markdown Live Editor*) biến VS Code thành môi trường soạn thảo Markdown trực quan WYSIWYG[^wysiwyg], mang trải nghiệm ghi chú và quản lý tri thức của Obsidian vào Visual Studio Code và Antigravity IDE. ![Giao diện làm việc của Markdown Live Editor](/images/markdown-live-editor/giao-dien-lam-viec-obsidian-style-markdown-editor.png) ## Vấn đề và Giải pháp ### Nỗi đau của người dùng Markdown trong kỷ nguyên Agent-first Trong kỷ nguyên làm việc theo mô hình Agent-first[^agent-first], Markdown không chỉ là văn bản thô mà còn là phương tiện giao tiếp chính giữa lập trình viên và AI. Quy trình phát triển phần mềm hiện đại là một vòng lặp tương tác liên tục: 1. Bạn tạo file `README.md` hoặc `plan.md` để phác thảo bối cảnh và yêu cầu cốt lõi. 2. AI phát triển ý tưởng thành tài liệu chi tiết kèm bảng dữ liệu, sơ đồ kiến trúc hoặc lưu đồ. 3. Bạn đọc lại, rà soát và trực tiếp chỉnh sửa những điểm chưa chính xác. 4. Bạn bôi đen đoạn văn bản cụ thể đưa vào ngữ cảnh trò chuyện để giao nhiệm vụ tiếp theo cho Agent. Tuy nhiên, **trình soạn thảo code truyền thống làm đứt gãy quy trình này**: * **Đọc tài liệu bị gián đoạn:** Việc phải đọc các khối mã phức tạp như công thức LaTeX[^latex] hay sơ đồ Mermaid[^mermaid] dưới dạng mã thô khiến bạn mất thời gian hình dung cấu trúc thực tế. * **Màn hình bị chia cắt:** Chế độ chia đôi màn hình để xem trước mặc định vừa tốn diện tích hiển thị vừa gây phân tâm khi cuộn trang.
Xem ảnh giao diện chia đôi màn hình ![Giao diện chia đôi màn hình mặc định của Visual St](/images/markdown-live-editor/split-preview-giao-dien-chia-doi-man-hinh-vscode.png)
* **Đứt gãy luồng suy nghĩ:** Phải chuyển đổi qua lại giữa VS Code và ứng dụng ghi chú chuyên biệt như Obsidian làm chậm nhịp làm việc. ### Giải pháp từ Markdown Live Editor Tiện ích mang đến trải nghiệm soạn thảo trực quan mượt mà ngay trong VS Code: * **Chỉnh sửa trực tiếp:** Viết và sửa văn bản trực tiếp trên giao diện đã định dạng mà không cần mở cửa sổ xem trước phụ. * **Hiển thị trực quan tức thì:** Tự động hiển thị sơ đồ Mermaid, công thức LaTeX, khối mã nguồn, bảng biểu và định dạng văn bản rich text. * **Đồng bộ hai chế độ:** Dễ dàng chuyển sang chế độ mã nguồn CodeMirror 6[^codemirror] khi cần can thiệp cú pháp thô, vị trí con trỏ và cuộn trang luôn được đồng bộ chính xác. * **Tương thích đa nền tảng:** Hoạt động đồng nhất trên VS Code Desktop, Remote SSH Workspace và cả trình duyệt web `vscode.dev`. ## Tính năng quản lý tri thức chuẩn Obsidian Tiện ích mang trọn vẹn những công cụ quản lý tri thức mạnh mẽ của Obsidian vào không gian làm việc của bạn: * **Không gian làm việc linh hoạt:** Quản lý toàn bộ tài liệu trong workspace như một Vault[^vault] tri thức thông qua thanh Sidebar chuyên biệt. * **Wikilinks và liên kết hai chiều:** Hỗ trợ cú pháp liên kết `[[Tên bài viết]]`[^wikilink] và nhúng file `![[Tài liệu]]`, tự động đánh chỉ mục toàn bộ tài liệu để điều hướng và kết nối ngữ cảnh nhanh chóng. * **Biểu đồ liên kết Graph View:** Trực quan hóa cấu trúc và mối quan hệ giữa các tài liệu dự án qua Graph View[^graph-view] ở cả cấp độ cục bộ lẫn toàn cục. * **Hoạt động trọn vẹn trên Desktop và Web:** Khác với nhiều tiện ích phụ thuộc môi trường máy tính cục bộ khiến tính năng quét file bị vô hiệu hóa trên trình duyệt, Markdown Live Editor tối ưu cơ chế lập chỉ mục để hoạt động mượt mà ngay trên `vscode.dev`. Khi cần đọc lại tài liệu, chỉnh sửa nhẹ hay xem biểu đồ mạng lưới trên web, mọi tính năng đều sẵn sàng mà không gặp rào cản tài nguyên. * **Frontmatter và Templates:** Chuẩn hóa siêu dữ liệu với YAML Frontmatter[^frontmatter] và tự động chèn các mẫu tài liệu đã định sẵn với biến linh hoạt như `<% tp.file.title %>`. ## Hướng dẫn Cài đặt ![Cách cài đặt tiện ích mở rộng](/images/markdown-live-editor/obsidian-style-markdown-editor-install-extension.png) 1. Mở **Antigravity IDE** hoặc **VS Code**. 2. Mở mục **Extensions** bằng phím tắt `Cmd+Shift+X` (macOS) hoặc `Ctrl+Shift+X` (Windows/Linux). 3. Tìm kiếm từ khóa: `Obsidian-style Markdown Editor`. 4. Chọn **Install**. 5. Mở cài đặt tiện ích mở rộng này như dưới đây ![Mở cài đặt tiện ích mở rộng Markdown Live Editor từ Extensions](/images/markdown-live-editor/mo-cai-dat-tien-ich-markdown-live-editor.png) ## Cách khởi động và Lệnh Command Palette ### Các cách mở Live Editor * **Cách 1 - Phím tắt:** Mở file `.md` bất kỳ và nhấn `Cmd + Ctrl + Shift + M` (macOS) hoặc `Ctrl + Alt + Shift + M` (Windows/Linux). * **Cách 2 - Biểu tượng trên thanh tiêu đề:** Khi mở file Markdown ở chế độ code thô, nhấn biểu tượng **Markdown** ở góc trên bên phải. ![Mở Markdown Live Editor bằng biểu tượng trên thanh tiêu đề Editor](/images/markdown-live-editor/mo-markdown-live-editor-tu-thanh-tieu-de.png) * **Cách 3 - Menu chuột phải:** Trong thanh Explorer, nhấp chuột phải vào file `.md` và chọn **"Open in Markdown Live Editor"**. ![Mở Markdown Live Editor từ menu chuột phải trong Explorer](/images/markdown-live-editor/mo-markdown-live-editor-tu-menu-chuot-phai-explorer.png) ### Các lệnh Command Palette hữu ích ![Danh sách lệnh Markdown Live Editor trong Command Palette](/images/markdown-live-editor/cac-lenh-command-palette-markdown-live-editor.png)
Nhấn `Cmd+Shift+P` (macOS) hoặc `Ctrl+Shift+P` (Windows/Linux) và gõ `Markdown Live` để gọi nhanh: * `Markdown Live: Toggle Graph View`: Bật hoặc tắt biểu đồ liên kết cục bộ cho file hiện tại. * `Markdown Live: Show Global Graph`: Mở biểu đồ liên kết toàn cục cho toàn bộ workspace. * `Markdown Live: Insert Template`: Chèn mẫu Markdown đã thiết lập sẵn vào vị trí con trỏ. * `Markdown Live: Re-index Vault`: Quét và cập nhật lại chỉ mục liên kết toàn bộ tài liệu trong workspace. * `Markdown Live: Send to AI Agent Context`: Gửi đoạn văn bản đang chọn vào khung chat của AI Agent để xử lý tiếp. *** Tiếp theo: [Rà soát Markdown cùng AI trong VS Code](/docs/tien-ich/markdown-live-editor/review-markdown-cung-ai-agent). [^agent-first]: **Agent-first** là mô hình làm việc lấy các tác nhân AI làm trọng tâm trong việc hỗ trợ khởi tạo, xử lý và tự động hóa các tác vụ. [^wysiwyg]: **WYSIWYG** (*What You See Is What You Get*) là phương thức hiển thị nội dung trực quan giống kết quả xuất bản ngay trong lúc soạn thảo. [^latex]: **LaTeX** là hệ thống soạn thảo chuyên dùng để biểu diễn các biểu thức toán học và tài liệu khoa học phức tạp. [^mermaid]: **Mermaid** là công cụ vẽ biểu đồ và sơ đồ luồng tự động bằng cú pháp văn bản Markdown. [^codemirror]: **CodeMirror 6** là thư viện biên tập mã nguồn thế hệ mới trên nền web, tối ưu hiệu năng cao và hỗ trợ mở rộng linh hoạt. [^vault]: **Vault** là thuật ngữ trong Obsidian dùng để chỉ thư mục gốc lưu trữ toàn bộ hệ thống tài liệu và ghi chú cá nhân. [^wikilink]: **Wikilink** là cú pháp liên kết nội bộ dạng `[[Tên tài liệu]]`, chuẩn mực kết nối thông tin trong các hệ thống quản lý tri thức cá nhân (PKM). [^graph-view]: **Graph View** là tính năng biểu diễn trực quan mối quan hệ và các liên kết chéo giữa các bài viết dưới dạng đồ thị mạng lưới. [^frontmatter]: **YAML Frontmatter** là khối dữ liệu cấu hình đặt ở đầu file Markdown giữa hai cặp dấu `---`, dùng để lưu thuộc tính bài viết như tiêu đề, ngày tạo hay thẻ phân loại. --- ## Document: Quản lý hình ảnh và mẫu Markdown trong VS Code Hình ảnh và mẫu tài liệu thường tạo ra nhiều thao tác phụ khi viết Markdown: lưu file ở đâu, dùng đường dẫn nào, đổi tên có làm hỏng liên kết không và làm sao giữ cấu trúc tài liệu nhất quán. Markdown Live Editor xử lý các bước này trong thư mục làm việc hiện tại. ## Dán hoặc kéo thả hình ảnh Khi dán hoặc kéo một ảnh vào trình soạn thảo, tiện ích: 1. Đọc dữ liệu ảnh bằng API của trình duyệt. 2. Lưu file vào thư mục cấu hình bởi `markdownLive.imageDirectory`. 3. Tạo tên file dựa trên thời điểm lưu. 4. Chèn đường dẫn Markdown tương đối từ tài liệu hiện tại đến ảnh. Thư mục mặc định là `assets/images`. Ví dụ: ```markdown ![Sơ đồ kiến trúc](../../assets/images/image-1788061200000.png) ``` Ảnh được lưu thành file riêng thay vì chuỗi base64[^base64] dài trong Markdown, vì vậy kho mã nguồn dễ rà soát và quản lý hơn. ## Đổi tên và xoá ảnh từ trình soạn thảo Mở trình đơn chuột phải trên một ảnh cục bộ để: * **Rename** (Đổi tên): đổi tên file vật lý và cập nhật đường dẫn trong tài liệu hiện tại. * **Delete** (Xoá): xác nhận rồi xoá file ảnh khỏi thư mục làm việc. Tiện ích không áp dụng thao tác file cho ảnh nhúng bằng base64. Sau khi đổi tên ảnh được dùng ở nhiều tài liệu, nên tìm kiếm toàn bộ thư mục làm việc vì đường dẫn trong các file khác không nhất thiết được cập nhật tự động. ## Kiểm tra tài nguyên khi xoá ghi chú Khi xoá một file Markdown, tiện ích có thể rà các tài nguyên cục bộ được tham chiếu và cho phép chọn ảnh liên quan để chuyển vào thùng rác. Luôn kiểm tra xem ảnh có được ghi chú khác sử dụng không trước khi xác nhận. ## Cấu hình đường dẫn ảnh cho Next.js và Vite Website thường lưu file tại `public/images/chart.png` nhưng Markdown cần dùng địa chỉ `/images/chart.png`. Đặt: ```json { "markdownLive.imagePublicPath": "public" } ``` Khi gặp: ```markdown ![Biểu đồ](/images/chart.png) ``` Chế độ trực quan sẽ tìm file vật lý tại `public/images/chart.png` mà không sửa đường dẫn dùng khi website hiển thị. Tính năng này phù hợp với Next.js, Vite và các dự án có thư mục `public`. `imagePublicPath` chỉ là phần đầu được thêm vào khi tìm file; hãy đặt giá trị tương ứng với cấu trúc thật của kho mã nguồn. ## Duyệt ghi chú trong thanh bên Markdown Live Sidebar cung cấp các tab: * **Recent Files** (File gần đây): quay lại các tài liệu vừa mở. * **Vault Files** (File ghi chú): duyệt các file Markdown trong phạm vi đã chọn. * **Annotations** (Ghi chú): xem các đoạn đã đánh dấu và nhận xét khi rà soát. Danh sách ghi chú có thể hiển thị đoạn xem trước và ảnh thu nhỏ, giúp nhận diện nội dung trước khi mở file. ## Tạo ghi chú mới Đặt `markdownLive.defaultNoteDirectory` nếu muốn ghi chú mới luôn nằm trong một thư mục như `notes` hoặc `content/docs`. Nếu để trống, tiện ích tạo ghi chú tại thư mục gốc của dự án. ## Cấu hình thư mục mẫu Đặt thư mục mẫu theo đường dẫn tương đối từ thư mục làm việc: ```json { "markdownLive.templateFolder": "templates" } ``` Sau đó dùng **Markdown Live: Insert Template** (Chèn mẫu) hoặc `Cmd/Ctrl + Shift + E` để chèn mẫu vào tài liệu hiện tại. Bạn cũng có thể tạo ghi chú mới từ mẫu trong thanh bên. ## Các biến thay thế được hỗ trợ Khi chèn mẫu vào file hiện tại: ```markdown # <% tp.file.title %> Ngày tạo: <% tp.date.now("YYYY-MM-DD") %> ``` Extension hỗ trợ: * `<% tp.file.title %>` * `<% tp.date.now() %>` * `<% tp.date.now("FORMAT") %>` với các token ngày giờ cơ bản Khi tạo ghi chú từ thanh bên, `{{title}}` được thay bằng tên ghi chú mới. Cú pháp trên lấy cảm hứng từ tiện ích Obsidian Templater[^templater] nhưng chỉ hỗ trợ một số lệnh, không chạy JavaScript hoặc toàn bộ giao diện lập trình của Templater. Hãy kiểm tra các mẫu phức tạp trước khi chuyển từ Obsidian. Tiếp theo: [Sao chép có định dạng, in và xuất PDF](/docs/tien-ich/markdown-live-editor/copy-rich-text-in-va-xuat-pdf). [^base64]: **Base64** là cách biểu diễn dữ liệu ảnh thành một chuỗi ký tự dài để nhúng trực tiếp vào văn bản. [^templater]: **Templater** là tiện ích phổ biến của Obsidian dùng để tạo tài liệu từ mẫu và chèn nội dung động. --- ## Document: Rà soát Markdown cùng AI trong VS Code # Rà soát và soạn thảo tài liệu Markdown cùng AI Trong quy trình vibe coding[^vibe-coding], tốc độ tạo nội dung thường không còn là trở ngại chính. Công việc khó hơn là **đọc, kiểm tra và phản hồi chính xác**: sơ đồ có phản ánh đúng kiến trúc không, bảng có thiếu trường dữ liệu không, hay một yêu cầu có bị AI diễn giải sai không. Markdown Live Editor biến file Markdown thành nơi rà soát ngay trong VS Code. Bạn có thể đọc tài liệu ở dạng đã định dạng, chọn đúng đoạn cần xử lý và gửi đoạn đó cho AI mà không phải sao chép toàn bộ file. ## Phối hợp giữa người dùng và AI ngay trong tài liệu Một quy trình điển hình gồm năm bước: 1. Bạn hoặc tác nhân AI tạo đề cương, kế hoạch, README hay tài liệu đặc tả. 2. Chế độ trực quan trình bày bảng, mã, Mermaid, LaTeX và khối lưu ý để bạn đọc như một tài liệu hoàn chỉnh. 3. Bạn chỉnh trực tiếp những lỗi nhỏ hoặc thêm ghi chú cho phần cần xem lại. 4. Bạn chọn đúng đoạn liên quan và gửi nó sang AI làm ngữ cảnh. 5. Khi AI cập nhật file qua VS Code, nội dung mới được đồng bộ trở lại trình soạn thảo để tiếp tục rà soát. Quy trình này giữ vai trò của AI và người dùng rõ ràng: AI hỗ trợ tạo và sửa nội dung; bạn chịu trách nhiệm đánh giá ý nghĩa, tính đúng đắn và quyết định cuối cùng. ## Gửi một đoạn sang AI 1. Bôi đen đoạn văn bản trong chế độ trực quan. 2. Chọn **Send to AI Agent Context** (Gửi làm ngữ cảnh cho AI) trên thanh công cụ nổi, hoặc nhấn `Cmd + Shift + L` / `Ctrl + Shift + L`. ![Gửi đoạn văn bản đã chọn vào ngữ cảnh chat của AI Agent](/images/markdown-live-editor/send-to-agent-chat-markdown-live-editor.png) 3. Tiếp tục nhập yêu cầu trong cửa sổ chat, chẳng hạn: * “Đối chiếu đoạn này với implementation hiện tại.” * “Viết lại cho người dùng không có nền tảng kỹ thuật.” * “Tìm giả định chưa được chứng minh trong phần này.” * “Chuyển yêu cầu này thành tiêu chí chấp nhận.” Tiện ích ưu tiên gửi đoạn được chọn qua lệnh tích hợp của Antigravity AI Agent. Nếu lệnh này không khả dụng, nội dung được chép vào bộ nhớ tạm và cửa sổ trò chuyện của VS Code được mở để bạn tiếp tục. ## Vì sao nên gửi đoạn được chọn thay vì toàn bộ file? * Giảm phần ngữ cảnh không liên quan. * Làm rõ chính xác nội dung cần AI xử lý. * Hạn chế AI sửa lan sang những phần đã được duyệt. * Giúp prompt ngắn hơn nhưng vẫn gắn với tài liệu nguồn. * Phù hợp với quá trình rà soát nhiều bước trên tài liệu dài. ## Thêm ghi chú mà không sửa file Markdown Khi chưa muốn thay đổi nội dung ngay, chọn đoạn văn và nhấn **Add Annotation** (Thêm ghi chú). Bạn có thể ghi lại câu hỏi, nhận xét hoặc việc cần xác minh. ![Thêm ghi chú Annotation cho đoạn văn bản và quản lý trên thanh bên](/images/markdown-live-editor/them-va-quan-ly-ghi-chu-annotation-markdown-live-editor.png) Các ghi chú này: * Được xem trong thẻ **Annotations** (Ghi chú) của thanh bên Markdown Live. * Có thể chỉnh sửa hoặc xoá từ giao diện. * Không chèn lời bình vào tài liệu và không làm thay đổi nội dung Markdown gốc. * Được lưu trong `.tmp/bookmarks.json` của thư mục làm việc. Vì ghi chú được lưu ngoài tài liệu, hãy quyết định theo quy ước dự án xem `.tmp/bookmarks.json` nên được chia sẻ qua Git hay thêm vào `.gitignore`. ## Ba cách áp dụng thực tế ### Review kế hoạch triển khai Mở `plan.md`, đọc các bước ở dạng tài liệu, đánh dấu phần còn mơ hồ rồi gửi riêng đoạn đó cho AI để bổ sung phần phụ thuộc, rủi ro và điều kiện hoàn thành. ### Kiểm tra tài liệu kiến trúc Hiển thị Mermaid trực tiếp để kiểm tra luồng hệ thống. Nếu sơ đồ và phần mô tả không khớp, chọn đoạn giải thích liên quan và yêu cầu AI đối chiếu với mã nguồn. ### Biên tập nội dung website Rà soát tiêu đề, bảng và khối lưu ý trong chế độ trực quan; thêm ghi chú cho nhận định cần dẫn nguồn; gửi từng đoạn sang AI để cải thiện giọng văn hoặc SEO mà không viết lại toàn bài. ## Tiếp tục sử dụng Git và VS Code như bình thường Chế độ trực quan là một trình soạn thảo tùy chọn. File vẫn là Markdown thuần, vì vậy bạn có thể: * Mở lại bằng VS Code Text Editor. * Rà soát phần thay đổi bằng Git. * Để AI hoặc công cụ khác chỉnh cùng file. * Dùng formatter, linter và pipeline xuất bản hiện có. Tiếp theo: [Giao diện và Thao tác Điều hướng](/docs/tien-ich/markdown-live-editor/giao-dien-va-thao-tac). [^vibe-coding]: **Vibe coding** là cách phát triển phần mềm bằng cách mô tả mục tiêu cho AI, kiểm tra kết quả và liên tục điều chỉnh qua nhiều vòng trao đổi. --- ## Document: Quản lý Ghi chú, Liên kết, Tags và Properties Các file Markdown riêng lẻ trở nên hữu ích hơn khi bạn nhìn thấy mối quan hệ giữa chúng và quản lý dữ liệu một cách có hệ thống. Markdown Live Editor lập chỉ mục toàn bộ thư mục làm việc để hỗ trợ Wikilink, liên kết ngược (backlinks), đồ thị liên kết và quản lý tập trung siêu dữ liệu (Tags, Properties). Tất cả các tính năng này được gom nhóm trực quan vào **4 thẻ chức năng trên thanh bên (Sidebar)**. ## Thư mục làm việc và kho ghi chú (Vault) Trong Obsidian, Vault[^vault] là thư mục gốc chứa hệ thống ghi chú. Markdown Live Editor sử dụng **thư mục làm việc của VS Code** (Workspace) làm phạm vi tương đương, giúp bạn quản lý tài liệu mà không cần thay đổi cấu trúc kho mã nguồn hay di chuyển file sang một ứng dụng bên ngoài. Bạn có thể giới hạn phạm vi quét tài liệu bằng cấu hình **Sidebar Scan Directory**. Để trống nếu muốn tiện ích quét toàn bộ thư mục làm việc hiện tại. ## Bốn công cụ quản lý trên thanh bên Markdown Live Thanh bên (Sidebar) của tiện ích được chia thành 4 nhóm công cụ chính để phục vụ các nhu cầu quản trị tài liệu khác nhau. ### 1. Quản lý File và Liên kết (Notes) Chức năng **Notes** không chỉ liệt kê các file Markdown mà còn đóng vai trò là trung tâm quản lý liên kết. * **Tạo và mở liên kết nội bộ:** Gõ `[[` trong chế độ soạn thảo trực quan để tìm kiếm và chèn nhanh file khác. Tiện ích sẽ tự động tạo đường dẫn tương đối (Wikilink). Nhấp vào liên kết sẽ mở trực tiếp tài liệu đích trong Editor. * **Liên kết hai chiều (Backlinks & Outlinks):** Khi mở một file, mục **Links** ở thanh bên sẽ thống kê ngay lập tức: * **Incoming Links (Liên kết ngược):** Những ghi chú khác đang trỏ đến file hiện tại. * **Outgoing Links (Liên kết đi):** Những ghi chú mà file hiện tại đang nhắc tới. ### 2. Khám phá ngữ cảnh trực quan (Local Graph) Công cụ **Local Graph** (Đồ thị cục bộ) lấy tài liệu bạn đang mở làm điểm trung tâm, giúp hình dung nhanh các mối quan hệ lân cận. * Đồ thị hiển thị cả liên kết đến (Incoming) lẫn liên kết đi (Outgoing). * Bạn có thể tùy chỉnh độ sâu của đồ thị (số lớp kết nối) thông qua cấu hình **Graph Depth** (mặc định là 2). * Khi bạn chuyển sang đọc file khác, điểm trung tâm và tập liên kết liên quan sẽ tự động cập nhật theo tài liệu mới. Đồ thị cục bộ giúp trả lời nhanh các câu hỏi: *Tài liệu này tham chiếu đến những ghi chú nào? Ai đang trích dẫn nó? Ngữ cảnh gần nhất là gì?* ### 3. Quản lý Thẻ phân loại (Tags) Tiện ích tự động trích xuất các thẻ (tags) từ YAML Frontmatter (ví dụ: `tags: [ai, markdown]`) của toàn bộ file trong Vault. * **Thống kê tổng quan:** Mục **Tags** liệt kê tất cả các nhãn đang được sử dụng trong dự án kèm theo số lượng bài viết tương ứng (Count). * **Sắp xếp linh hoạt:** Hỗ trợ sắp xếp theo Tên (Alphabetical) hoặc theo Số lượng (By Count) thông qua các biểu tượng trên thanh tiêu đề của View. * **Lọc tìm kiếm (Filter):** Nhấn biểu tượng kính lúp để lọc nhanh các thẻ khi số lượng tags quá lớn. Tính năng này giúp bạn dễ dàng theo dõi hệ thống phân loại nội dung, phát hiện các thẻ bị sai chính tả hoặc trùng lặp ý nghĩa để quy hoạch lại cấu trúc blog/tài liệu. ### 4. Chuẩn hóa Siêu dữ liệu (Properties) Tương tự như Tags, công cụ **Properties** (Thuộc tính) quét toàn bộ các khóa (keys) được định nghĩa trong khối YAML Frontmatter (ví dụ: `title`, `description`, `author`, `date`) của mọi file. * Tính năng này thống kê tần suất xuất hiện của từng trường thuộc tính trong toàn bộ dự án. * Tích hợp sẵn các công cụ: Sắp xếp theo Tên, Sắp xếp theo Tần suất và Lọc tìm kiếm (Filter). * **Lợi ích thực tiễn:** Giúp các tác giả hoặc kỹ sư dữ liệu (Data Engineer) kiểm soát cấu trúc siêu dữ liệu. Bạn có thể nhanh chóng phát hiện nếu có bài viết nào đang dùng sai trường `featuredImage` thành `feature_image`. ## Đồ thị toàn cục (Global Graph): Nhìn toàn cảnh hệ thống Bên cạnh đồ thị cục bộ, bạn có thể chạy lệnh **Markdown Live: Show Global Graph** (Hiện đồ thị toàn cục) từ Command Palette (hoặc biểu tượng toàn cầu trên Local Graph) để mở giao diện đồ thị lớn cho toàn bộ thư mục làm việc. Đồ thị toàn cục rất hữu ích để: * Phát hiện các "cụm" (clusters) tài liệu có độ kết nối dày đặc (ví dụ: trung tâm tri thức). * Tìm các ghi chú chưa được kết nối với hệ thống (ghi chú mồ côi) bằng tùy chọn **Show Orphans**. * Quan sát hướng liên kết rõ ràng nhờ các mũi tên chỉ hướng. ## Nhãn và màu sắc điểm trên Đồ thị Để đồ thị dễ hiểu, tiện ích ưu tiên hiển thị nhãn theo thứ tự: 1. Trường thuộc tính YAML `title` (nếu có). 2. Thẻ tiêu đề Heading H1 đầu tiên trong bài. 3. Tên file vật lý. Bạn cũng có thể thêm thuộc tính `color` (mã hex màu) vào YAML Frontmatter để tô màu riêng cho từng điểm tài liệu. Nếu không được chỉ định, đồ thị có thể tự động phân biệt màu sắc dựa trên cấu trúc thư mục chứa file. ## Hiểu đúng vai trò của Đồ thị và Siêu dữ liệu Đồ thị liên kết và bảng thống kê Properties/Tags là các công cụ hỗ trợ khám phá cấu trúc, không tự động đánh giá chất lượng nội dung. Một đồ thị dày đặc chưa chắc đã tốt; điều quan trọng là mỗi liên kết đều mang lại ngữ cảnh hữu ích cho người đọc. Với tài liệu sản phẩm hoặc kho mã nguồn, hãy ưu tiên: * Liên kết từ trang Tổng quan (Overview) đến các hướng dẫn chi tiết. * Liên kết ngược (Backlink) từ trang tra cứu API về quy trình sử dụng chính. * Xây dựng bộ chuẩn Properties đồng nhất (ví dụ: bài viết nào cũng phải có `description` và `author`). * Tránh tạo Wikilink vô tội vạ chỉ để làm đồ thị trông phức tạp hơn. *** Tiếp theo: [Quản lý hình ảnh và mẫu tài liệu Markdown](/docs/tien-ich/markdown-live-editor/quan-ly-hinh-anh-va-template). [^vault]: **Vault** là thuật ngữ Obsidian dùng để gọi thư mục gốc chứa toàn bộ hệ thống ghi chú cá nhân. --- ## Document: Giới thiệu và Cài đặt Smart Data Viewer
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Smart Data Viewer là không gian làm việc dữ liệu (data workspace) tích hợp AI dành cho môi trường VS Code và Antigravity IDE. Tiện ích này giúp bạn mở, phân tích và trích xuất ngữ cảnh trực tiếp từ các file dữ liệu do con người hoặc AI sinh ra mà không cần chuyển sang ứng dụng khác. Tiện ích giải quyết bất cập khi môi trường IDE truyền thống thiếu khả năng tương tác với dữ liệu. Khi làm việc với AI, nếu cần mở các file dữ liệu (như `.parquet`, `.csv`, `.json`), việc dùng phần mềm bên ngoài sẽ làm gián đoạn mạch làm việc [^1] và khiến việc đưa dữ liệu bị lỗi trở lại cho AI phân tích trở nên bất tiện. Quy trình làm việc của Smart Data Viewer được thiết kế theo các bước: Mở dữ liệu -> Khám phá trực quan -> Phân tích -> Trích xuất phần dữ liệu quan trọng -> Gửi cho AI -> Ghi chú kết quả. ## Các định dạng dữ liệu hỗ trợ Smart Data Viewer hỗ trợ nhiều định dạng file thường gặp trong quy trình lập trình có AI hỗ trợ [^2]: * **Bảng dữ liệu & Text:** `.csv`, `.tsv` * **Dữ liệu có cấu trúc:** `.json`, `.jsonl`, `.ndjson` * **Tài liệu văn phòng:** `.xlsx`, `.xls`, `.docx` * **Định dạng dữ liệu lớn:** `.parquet` * **Cơ sở dữ liệu cục bộ:** `.duckdb`, `.sqlite`, `.sqlite3`, `.db` * **Lưu trữ nén:** `.zip` * **Web Preview:** `.html`, `.htm` Tùy theo định dạng, tiện ích sẽ điều chỉnh cách hiển thị phù hợp. Ví dụ: Parquet hiển thị kèm kiểu dữ liệu, JSON hỗ trợ dạng bảng và dạng cây, SQLite và DuckDB cho phép duyệt các bảng dữ liệu bên trong. ## Cài đặt và Khởi chạy ### Cách cài đặt 1. Mở phần quản lý Extensions trong VS Code (phím tắt `Ctrl+Shift+X` trên Windows/Linux hoặc `Cmd+Shift+X` trên macOS). 2. Tìm kiếm từ khoá **Smart Data Viewer** (ID: `vnstock.vscode-smart-data-viewer`). 3. Nhấn **Install** để cài đặt. ### Khởi chạy Sau khi cài đặt, bạn có thể khởi chạy tiện ích qua các cách sau: * **Trong File Explorer:** Nhấp chuột phải vào file được hỗ trợ (như `.csv` hoặc `.json`), chọn **"Open with Smart Data Viewer"**. * **Thanh Activity Bar:** Ở thanh bên trái của VS Code, chọn biểu tượng Smart Data Viewer. Khu vực **Quick Launch & Scratchpad** sẽ hiển thị để mở file nhanh. * **Trình chuyển đổi:** Khi đang mở file bằng Smart Data Viewer, bạn có thể bấm vào biểu tượng `< >` (Open with Text Editor) ở góc phải trên cùng để chuyển sang chế độ xem text thông thường. ## Cấu hình (Settings) Smart Data Viewer cung cấp cấu hình hiển thị: * `smartCsv.rowIndexStart`: Cài đặt số thứ tự bắt đầu cho hàng. * Đặt là `0`: Bắt đầu từ 0 (Chuẩn của Pandas DataFrame - mặc định). * Đặt là `1`: Bắt đầu từ 1 (Chuẩn của ứng dụng Spreadsheet). [^1]: Context switching: Trạng thái ngắt quãng khi phải chuyển đổi liên tục giữa các ngữ cảnh hoặc công cụ làm việc khác nhau. [^2]: Vibe coding: Phương pháp lập trình trong đó người dùng đưa ra chỉ thị để AI tạo và hoàn thiện code. --- ## Document: Khám phá dữ liệu và Phân tích Khám phá
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Khám phá dữ liệu là bước quan trọng trước khi bạn hoặc AI đưa ra các quyết định xử lý code. Smart Data Viewer tích hợp sẵn các công cụ như hiển thị dữ liệu dạng bảng với khả năng Lazy Load [^1], bảng điều khiển Phân tích Khám phá [^2], và tính năng tổng hợp dữ liệu Pivot ngay trong môi trường làm việc. ## DataGrid và xử lý file lớn Một khó khăn khi thao tác với các file dữ liệu lớn (như CSV hoặc TSV) trong IDE là hiện tượng treo ứng dụng. Smart Data Viewer giải quyết vấn đề này qua cơ chế Lazy Loading. * **Lập chỉ mục thông minh:** Thay vì nạp toàn bộ file vào bộ nhớ của giao diện Webview [^3], tiện ích sẽ đọc file trên ổ cứng và tạo chỉ mục (index) theo byte offset. * **Phân trang (Pagination):** Giao diện bảng dữ liệu (DataGrid) chỉ tải và hiển thị 100 dòng cho trang hiện tại. Khi người dùng chuyển trang, tiện ích mới trích xuất dữ liệu tương ứng dựa trên chỉ mục. * **Trải nghiệm mượt mà:** Cơ chế này giúp việc điều hướng qua lại trên các file dữ liệu lớn diễn ra nhanh chóng, giảm thiểu tiêu tốn RAM hoặc tình trạng treo trình soạn thảo. Bạn có thể Lọc (Filter) và Sắp xếp (Sort) dữ liệu trên trang hiện tại trực tiếp tại tiêu đề của các cột. ## Phân tích Khám phá Tự động (Insights) Khi nhấn vào nút **Insights** trên thanh Toolbar, hệ thống Phân tích Khám phá sẽ chạy ngầm (background) và cung cấp tổng quan về cấu trúc dữ liệu cũng như chất lượng dữ liệu. Bảng Insights cung cấp các thông tin: 1. **Metadata tổng quát:** Số lượng dòng (Row count) và thông tin file gốc. 2. **Kiểm tra tính vẹn toàn:** Đếm và tính toán tỷ lệ phần trăm dữ liệu khuyết thiếu (Missing-value percentages) cho từng cột. 3. **Thống kê mô tả:** Tính toán các chỉ số cơ bản cho cột số (Min, Max, Mean, Median, Q1, Q3). 4. **Trích mẫu:** Thu thập tối đa 100 giá trị duy nhất (unique values) của một cột để kiểm tra kiểu dữ liệu (categorical) hoặc xác định giá trị dị biệt (outliers). ## Tổng hợp dữ liệu với Pivot Tính năng Pivot trong Smart Data Viewer cho phép tổng hợp dữ liệu ngay trong IDE, tương tự Pivot Table trong Excel. Pivot Panel được hỗ trợ bởi DuckDB WebAssembly [^4], mang lại khả năng tính toán nhanh chóng. ### Cách sử dụng Data Pivot 1. Nhấn nút **Pivot** trên thanh Toolbar (áp dụng với file CSV, TSV, Parquet, DuckDB). 2. Khi giao diện hiện ra, chọn **Load Data & Initialize Engine** để nạp dữ liệu vào DuckDB. 3. Bảng cấu hình xuất hiện, cho phép chọn: * **Table:** Bảng dữ liệu cần thao tác (nếu dùng file DuckDB có nhiều bảng). * **Rows (Group By):** Chọn cột dùng để nhóm dữ liệu. * **Values:** Chọn cột chứa giá trị cần tính toán. * **Aggregation:** Lựa chọn hàm tổng hợp (hỗ trợ `SUM`, `AVG`, `COUNT`, `COUNT_DISTINCT`, `MIN`, `MAX`, `MEDIAN`, `STDDEV`, `VAR`). 4. Nhấn **Generate Pivot**. Kết quả tổng hợp sẽ hiển thị dưới dạng bảng ngay trong panel và được sắp xếp tự động theo giá trị giảm dần. Việc tích hợp DuckDB giúp quá trình nhóm dữ liệu và tính toán đạt hiệu suất cao ngay bên trong giao diện của VS Code. [^1]: Lazy Load: Kỹ thuật lập trình chỉ tải dữ liệu hoặc thành phần khi thực sự cần thiết, giúp tiết kiệm tài nguyên. [^2]: Phân tích Khám phá (Exploratory Data Analysis - EDA): Bước phân tích sơ bộ dữ liệu để nắm bắt các đặc điểm và cấu trúc chính. [^3]: Webview: Thành phần nhúng cho phép hiển thị nội dung web (HTML, CSS, JavaScript) bên trong một ứng dụng desktop hoặc mobile. [^4]: WebAssembly (WASM): Công nghệ cho phép chạy code hiệu năng cao (như C, C++, Rust) trực tiếp trên môi trường web hoặc trình duyệt. --- ## Document: Thao tác với JSON và Scratchpad
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Trong phát triển phần mềm, JSON (và các biến thể như JSONL, NDJSON) là định dạng dữ liệu thường gặp. Việc mở các file JSON lồng nhau (nested objects) bằng các trình soạn thảo code thông thường dưới dạng văn bản có thể làm giảm hiệu suất nắm bắt cấu trúc dữ liệu. Smart Data Viewer hiển thị file JSON thành các đối tượng trực quan, hỗ trợ tương tác, khám phá cấu trúc, và trích xuất một phần dữ liệu nhỏ (nhánh - subtree [^1]) để cung cấp ngữ cảnh cho AI. ## Các chế độ xem dữ liệu JSON Khi mở file `.json`, `.jsonl` hoặc `.ndjson`, tiện ích cung cấp 2 chế độ hiển thị: ### 1. JSON Tree Viewer (Chế độ Cây) Chế độ này phù hợp cho các file JSON có cấu trúc lồng nhau (ví dụ: dữ liệu cấu hình hoặc kết quả từ API). * **Mở rộng/Thu gọn:** Bạn có thể click để đóng hoặc mở các mảng (Array) và đối tượng (Object) để theo dõi cấu trúc. * **Biểu tượng trực quan:** Các giá trị chuỗi (string), số (number), boolean, hoặc null được hiển thị với màu sắc riêng, hỗ trợ phân loại bằng mắt nhanh chóng. * **Trích xuất nhánh dữ liệu:** Khi dùng chế độ Cây, nếu cần chọn một Object hoặc Array quan trọng để gửi cho AI, bạn có thể **chuột phải** (hoặc dùng nút thao tác) để gửi nhánh đó sang AI Context. Tiện ích sẽ đính kèm đường dẫn cấu trúc (object path) để AI nhận diện vị trí dữ liệu trong file gốc. ### 2. JSON Table View (Chế độ Bảng) Đối với các file `.jsonl` (JSON Lines), `.ndjson` hoặc mảng chứa nhiều đối tượng phẳng, chế độ hiển thị Bảng giúp dễ quan sát hơn. * Tính năng này sẽ làm phẳng (flatten [^2]) các khoá cấp 1 của JSON Objects thành cột (Columns), và mỗi Object sẽ hiển thị dưới dạng một hàng (Row). * Tại chế độ Bảng, bạn có thể dùng công cụ Lọc (Filtering), Sắp xếp (Sorting), hay Phân tích Khám phá (EDA) tương tự như với file CSV. * *Lưu ý:* Việc trích xuất Context tại chế độ Bảng sẽ xuất ra dạng Markdown Table, khác với dạng JSON tại chế độ Cây. ## Tính năng JSON Scratchpad Khi làm việc với Terminal hoặc API, bạn có thể nhận được dữ liệu JSON thô và cần phân tích nhanh cấu trúc mà không muốn tạo file mới trên máy tính. Tính năng **JSON Scratchpad** được thiết kế cho nhu cầu này. ### Cách sử dụng Scratchpad: 1. Sao chép đoạn văn bản JSON. 2. Từ VS Code, mở Command Palette (`Cmd+Shift+P` hoặc `Ctrl+Shift+P` trên Windows/Linux) và chạy lệnh: `Smart Data Viewer: New JSON Scratchpad`. 3. Hoặc nhấn biểu tượng **Data Hub Launcher** trên thanh Activity Bar và chọn Paste JSON. 4. Một bảng thông báo tên **PasteJsonModal** sẽ hiển thị. Dán mã JSON vào đó và nhấn xác nhận. 5. Tiện ích sẽ khởi tạo một môi trường xem bằng giao diện JSON Tree Viewer hoặc Table View để bạn khám phá. Tính năng này hỗ trợ quá trình lập trình liền mạch: Thử nghiệm API -> Copy kết quả -> Phân tích bằng Scratchpad -> Trích xuất dữ liệu quan trọng -> Gửi lại cho AI. [^1]: Subtree (Nhánh con): Một phần cấu trúc lồng nhau được trích xuất từ một cấu trúc dữ liệu dạng cây (tree) lớn hơn. [^2]: Flatten: Quá trình làm phẳng cấu trúc dữ liệu lồng nhau thành cấu trúc dữ liệu phẳng (một cấp). --- ## Document: Tích hợp AI Context và Quản lý Ghi chú
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan Smart Data Viewer được thiết kế để hoạt động như một không gian làm việc dữ liệu cho AI. Trong quy trình lập trình có AI hỗ trợ, việc chắt lọc thông tin quan trọng từ file dữ liệu lớn để làm ngữ cảnh (context) cho AI là rất cần thiết. Nếu gửi toàn bộ một file lớn cho AI xử lý, quá trình này có thể chậm, tốn nhiều chi phí Token và dễ gây ra hiện tượng ảo giác (hallucination) [^1]. Smart Data Viewer giúp giải quyết vấn đề này bằng cách đóng vai trò như một bộ lọc thông tin. ## Trích xuất ngữ cảnh cho AI (AI Context) Khi xem dữ liệu trên giao diện **DataGrid** hoặc **JSON Tree Viewer**, bạn có thể trích xuất ngữ cảnh thông qua các thao tác: 1. Bôi đen các ô, hàng, cột hoặc một vùng dữ liệu cần làm rõ (hỗ trợ chọn nhiều vùng rời rạc). 2. Nhấp chuột phải và chọn **Send to AI Context**. 3. Smart Data Viewer sẽ tự động: * Thu thập tiêu đề cột tương ứng. * Lấy số thứ tự hàng của dữ liệu gốc. * Chuyển đổi thành bảng định dạng Markdown. * Gửi dữ liệu này vào bộ nhớ tạm của AI thông qua API nội bộ `antigravity.addContext` (nếu sử dụng Antigravity IDE). Khi dùng môi trường khác, đoạn Markdown sẽ được lưu vào Clipboard hoặc ghi vào file `.tmp/data_context.md`. *Ví dụ:* Khi kiểm tra dữ liệu mô phỏng, bạn phát hiện một dòng có dữ liệu bất thường. Bạn bôi đen dòng đó, chọn "Send to AI Context" và yêu cầu AI sửa lỗi tương ứng. Cách làm này giúp cung cấp ngữ cảnh rõ ràng và ngắn gọn. ## Quản lý Ghi chú Dữ liệu (Data Annotations) Một yêu cầu khác trong quá trình làm việc là khả năng lưu lại các ghi chú, giả thuyết hoặc từ điển dữ liệu (Data Dictionary) mà không làm thay đổi file gốc (quy trình làm việc không phá huỷ - non-destructive workflow) [^2]. Nếu thêm cột ghi chú trực tiếp vào file CSV như khi dùng phần mềm bảng tính thông thường, cấu trúc dữ liệu sẽ bị thay đổi và có thể gây lỗi cho các đoạn mã xử lý sau này. Smart Data Viewer cung cấp tab **Notes** để giải quyết vấn đề này: * **Lưu trữ độc lập:** Khi tạo ghi chú cho dữ liệu, tiện ích sẽ tạo một file Markdown (.md) ẩn trong thư mục `.tmp/notes/`. * **Tích hợp đồng bộ:** Ghi chú hiển thị ngay cạnh giao diện xem file. Bạn có thể dùng Markdown để soạn thảo, chèn hình ảnh, hoặc lưu lại các đoạn lệnh (prompt). Ở những lần mở file tiếp theo, ghi chú sẽ tự động được tải lại. * **Duy trì bản gốc (Source of truth [^3]):** File dữ liệu gốc (`.csv`, `.parquet`, `.sqlite`...) không bị tác động. Tính năng ghi chú giúp theo dõi quá trình phân tích dữ liệu, thuận tiện cho việc làm việc nhóm hoặc khi làm việc với AI qua nhiều phiên khác nhau. [^1]: Ảo giác (Hallucination): Hiện tượng AI sinh ra thông tin sai lệch, không có thật hoặc không dựa trên dữ liệu đầu vào. [^2]: Non-destructive workflow: Quy trình xử lý không làm thay đổi hoặc phá huỷ dữ liệu gốc. [^3]: Source of truth: Nguồn dữ liệu đáng tin cậy duy nhất và nguyên bản. --- ## Document: Truy vấn SQL trực tiếp với DuckDB
Cài cho Antigravity IDE Cài cho VS Code


## Tổng quan SQL là ngôn ngữ phổ biến để thực hiện các phép lọc, kết nối (JOIN) [^1] và tổng hợp dữ liệu. Thay vì phải cài đặt các hệ quản trị cơ sở dữ liệu như PostgreSQL, MySQL hoặc chuyển dữ liệu vào Jupyter Notebook để dùng thư viện phân tích, Smart Data Viewer hỗ trợ sử dụng SQL trực tiếp trong VS Code thông qua DuckDB WebAssembly. ## DuckDB WebAssembly DuckDB là một hệ quản trị cơ sở dữ liệu phân tích nhúng. Việc tích hợp DuckDB WebAssembly vào Smart Data Viewer mang lại các lợi ích: * Truy vấn SQL được thực thi trực tiếp trên trình duyệt nội bộ của VS Code. * Không cần thiết lập máy chủ cơ sở dữ liệu bên ngoài. * Dữ liệu được xử lý cục bộ, không gửi qua máy chủ trung gian, giúp đảm bảo an toàn thông tin. Khi mở một file `.csv`, `.tsv`, `.parquet` hoặc `.duckdb`, bạn có thể chuyển sang tab **SQL** trên Toolbar. Tại đây, nút `Initialize Engine` sẽ tải thư viện WebAssembly vào môi trường làm việc. ## Viết truy vấn (SQL Query Panel) Sau khi DuckDB khởi tạo, giao diện **SQL Query Panel** sẽ hiển thị trình soạn thảo SQL. * **Tham chiếu bảng:** File đang mở (CSV, Parquet) tự động được ánh xạ thành một bảng ảo tên là `data` trong DuckDB. Bạn có thể truy vấn trực tiếp, ví dụ: `SELECT * FROM data LIMIT 10;`. * **Thực thi truy vấn:** Hỗ trợ các câu truy vấn phức tạp với `GROUP BY`, `HAVING`, hay hàm cửa sổ (Window functions) [^2]. Khi nhấn **Run Query**, kết quả sẽ được kết xuất dưới dạng bảng lưới ở nửa dưới màn hình. * **Trích xuất dữ liệu cho AI:** Nếu kết quả truy vấn cho thấy điểm dữ liệu bất thường (outlier) [^3], bạn có thể bôi đen kết quả đó và chọn **Send to AI Context**. Thao tác này giúp trích xuất và gửi phần dữ liệu cần thiết cho AI phân tích, thay vì gửi toàn bộ file gốc. ## Hỗ trợ DuckDB và SQLite cục bộ Smart Data Viewer cũng hoạt động như một trình duyệt cơ sở dữ liệu nhẹ cho các định dạng `.duckdb` và họ `.sqlite` (`.sqlite`, `.sqlite3`, `.db`). * **Với file `.duckdb`:** Mở file trực tiếp, hệ thống sẽ tự động quét (scan) tất cả các bảng có trong cơ sở dữ liệu. Bạn có thể xem trước tối đa 1.000 dòng của bất kỳ bảng nào, hoặc chuyển sang tab SQL để viết truy vấn kết nối giữa các bảng. * **Với file `.sqlite`:** Tiện ích sử dụng thư viện `sql.js` để mở file cơ sở dữ liệu ở chế độ chỉ đọc trên bộ nhớ RAM (Read-only in-memory snapshot) [^4]. Bạn có thể duyệt qua các bảng và View, thực hiện phân trang, lọc, và phân tích dữ liệu tương tự như thao tác với file CSV. > [!WARNING] > Lưu ý khi dùng SQLite: Vì cơ sở dữ liệu SQLite được tải toàn bộ vào RAM dưới dạng bản sao chép, lượng RAM tiêu thụ sẽ tương đương với kích thước file `.db`. Ngoài ra, nếu có kết nối khác đang ghi dữ liệu vào file `.db-wal` nhưng chưa đồng bộ (checkpoint), Smart Data Viewer có thể không hiển thị phần dữ liệu mới đó. Điểm lợi là file gốc của bạn không bị khoá hoặc bị chỉnh sửa ngoài ý muốn. [^1]: JOIN: Phép toán trong SQL dùng để kết hợp các hàng từ hai hay nhiều bảng dựa trên cột chung. [^2]: Window functions: Hàm trong SQL thực hiện tính toán trên một tập hợp các hàng có liên quan đến hàng hiện tại. [^3]: Outlier: Giá trị ngoại lai, khác biệt đáng kể so với các quan sát còn lại trong tập dữ liệu. [^4]: Snapshot: Bản sao trạng thái của một hệ thống hoặc cơ sở dữ liệu tại một thời điểm nhất định. --- ## Document: Thống Kê & Định Giá (Analytics)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
## 📌 Tổng Quan **Analytics Layer** là một layer chuyên biệt cung cấp góc nhìn **định giá thị trường tổng quan** bao gồm biểu đồ P/E, P/B vĩ mô, và đánh giá sức khoẻ cho các rổ chỉ số chứng khoán. Đây là Layer được tách riêng từ mô đun Insights nhằm phục vụ độc lập cho mục tiêu đánh giá định giá rổ chứng khoán ở mức độ toàn cảnh trước khi nhà đầu tư đi sâu vào việc phân tích các mã lẻ. ### 🏗️ Cấu Trúc Nhóm Lệnh ```python Analytics() └── .valuation(index) # Định giá thị trường ├── .pe(duration) # P/E ratio lịch sử ├── .pb(duration) # P/B ratio lịch sử └── .evaluation(duration) # Đánh giá tổng hợp P/E + P/B ``` ## Định giá thị trường & Chỉ số (Valuation) Cung cấp dữ liệu định giá chuẩn P/E, P/B trong quá khứ được tham chiếu theo các chỉ số thị trường vĩ mô (VNINDEX, HNX, UPCOM, v.v.) để phân tích mức độ đắt rẽ hiện tại so với bối cảnh lịch sử. **Source:** VND **Nhóm lệnh:** `insights.valuation` **Khởi Tạo** ```python from vnstock_data import Analytics ana = Analytics() val = ana.valuation("VNINDEX") # Cấu hình index mục tiêu (Mặc định: "VNINDEX") ``` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | -------------- | ---------- | ----------------------------- | --------- | | `pe()` | `duration` | P/E ratio lịch sử | DataFrame | | `pb()` | `duration` | P/B ratio lịch sử | DataFrame | | `evaluation()` | `duration` | Đánh giá tổng hợp (P/E + P/B) | DataFrame | **Parameters:** - `index` (str) khi khởi tạo: Có thể chọn `"VNINDEX"`, `"HNX"`, `"VN30"`. - `duration` (str) khi gọi method: Khoảng thời gian lịch sử cần lấy. Mặc định là `"5Y"`. Các giá trị tham chiếu: `"1Y"`, `"2Y"`, `"3Y"`, `"5Y"`. **Ví Dụ** ```python from vnstock_data import Analytics ana = Analytics() df_pe = ana.valuation("VNINDEX").pe(duration="1Y") print(df_pe.tail()) df_pe_hnx = ana.valuation("HNX").pe(duration="5Y") df_pb = ana.valuation("VNINDEX").pb(duration="1Y") df_eval = ana.valuation("VNINDEX").evaluation(duration="5Y") print(df_eval.head()) ``` --- ## ⚠️ Lưu Ý Quan Trọng 1. **Migration từ Market Layer**: Nếu trước đây bạn dùng `Market().pe()` trong phiên bản cũ, thiết kế mới bắt buộc bạn di chuyển sang `Analytics().valuation(index).pe()`. Hàm cũ dù vẫn còn hoạt động có thể sẽ hiển thị cảnh báo deprecation warning. 2. **Default Arguments**: Luôn ưu tiên truyền tham số rõ ràng thay vì ngầm định theo vị trí, ví dụ `.pe(duration="5Y")`). --- ## Document: Analytics ### Analytics().valuation('VNINDEX').evaluation(duration='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`reportDate`** | `datetime64[ns]` | Thời gian / Ngày tháng | `2025-07-28T00:00:00.000` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `14.8752873638` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.9811374401` | ### Analytics().valuation('VNINDEX').pb(duration='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`reportDate`** | `datetime64[ns]` | Thời gian / Ngày tháng | `2025-07-28T00:00:00.000` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.9811374401` | ### Analytics().valuation('VNINDEX').pe(duration='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`reportDate`** | `datetime64[ns]` | Thời gian / Ngày tháng | `2025-07-28T00:00:00.000` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `14.8752873638` | --- ## Document: Fundamental ## Phiên bản 3.2.8 Định dạng dữ liệu bảng dài (long format) với cột giá trị luôn là số `float`. Dưới đây là mẫu minh hoạ (15 tiêu chí đầu tiên) cho cấu trúc dữ liệu mới của từng loại báo cáo: **Lưu ý:** Tên cột của DataFrame trả về là dạng viết thường snake\_case. ### Fundamental().equity('TCB').balance\_sheet() (v3.2.8) | period | id | name | order | level | off\_balance | unit | value | | :----- | :----------------------------------------------------------- | :--------------------------------- | :---- | :---- | :----------- | :--- | :--------- | | 2018 | BS\_CASH\_AND\_PRECIOUS\_METALS | Tiền và các khoản tương đương tiền | 1 | 1 | False | VNĐ | 15000000.0 | | 2018 | BS\_FIXED\_ASSETS | Tài sản cố định | 2 | 2 | False | VNĐ | 14000000.0 | | 2018 | BS\_TANGIBLE\_FIXED\_ASSETS | Tài sản cố định hữu hình | 3 | 3 | False | VNĐ | 13000000.0 | | 2018 | BS\_TANGIBLE\_FIXED\_ASSETS\_COST | Nguyên giá | 4 | 1 | False | VNĐ | 12000000.0 | | 2018 | BS\_TANGIBLE\_FIXED\_ASSETS\_ACCUMULATED\_DEPRECIATION | Giá trị hao mòn luỹ kế | 5 | 2 | False | VNĐ | 11000000.0 | | 2018 | BS\_FINANCE\_LEASE\_FIXED\_ASSETS | Tài sản cố định thuê tài chính | 6 | 3 | False | VNĐ | 10000000.0 | | 2018 | BS\_FINANCE\_LEASE\_FIXED\_ASSETS\_COST | Nguyên giá | 7 | 1 | False | VNĐ | 9000000.0 | | 2018 | BS\_FINANCE\_LEASE\_FIXED\_ASSETS\_ACCUMULATED\_DEPRECIATION | Giá trị hao mòn luỹ kế | 8 | 2 | False | VNĐ | 8000000.0 | | 2018 | BS\_INTANGIBLE\_FIXED\_ASSETS | Tài sản cố định vô hình | 9 | 3 | False | VNĐ | 7000000.0 | | 2018 | BS\_INTANGIBLE\_FIXED\_ASSETS\_COST | Nguyên giá | 10 | 1 | False | VNĐ | 6000000.0 | | 2018 | BS\_INTANGIBLE\_FIXED\_ASSETS\_ACCUMULATED\_DEPRECIATION | Giá trị hao mòn luỹ kế | 11 | 2 | False | VNĐ | 5000000.0 | | 2018 | BS\_INVESTMENT\_PROPERTIES | Bất động sản đầu tư | 12 | 3 | False | VNĐ | 4000000.0 | | 2018 | BS\_INVESTMENT\_PROPERTIES\_COST | Nguyên giá | 13 | 1 | False | VNĐ | 3000000.0 | | 2018 | BS\_INVESTMENT\_PROPERTIES\_ACCUMULATED\_DEPRECIATION | Giá trị hao mòn luỹ kế | 14 | 2 | False | VNĐ | 2000000.0 | | 2018 | BS\_LONG\_TERM\_INVESTMENTS | Góp vốn, đầu tư dài hạn | 15 | 3 | False | VNĐ | 1000000.0 | ### Fundamental().equity('TCB').cash\_flow() (v3.2.8) | period | id | name | order | level | off\_balance | unit | value | | :----- | :----------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :---- | :---- | :----------- | :--- | :--------- | | 2018 | CF\_PROFIT\_BEFORE\_TAX | Lợi nhuận trước thuế | 1 | 1 | False | VNĐ | 15000000.0 | | 2018 | CF\_DEPRECIATION\_AND\_AMORTISATION | Khấu hao TSCĐ và BĐSĐT | 2 | 2 | False | VNĐ | 14000000.0 | | 2018 | CF\_PROVISIONS | Các khoản dự phòng | 3 | 3 | False | VNĐ | 13000000.0 | | 2018 | CF\_FOREIGN\_EXCHANGE\_LOSS\_GAIN | Lãi, lỗ chênh lệch tỷ giá hối đoái do đánh giá lại các khoản mục tiền tệ có gốc ngoại tệ | 4 | 1 | False | VNĐ | 12000000.0 | | 2018 | CF\_LOSS\_GAIN\_FROM\_DISPOSAL\_OF\_FIXED\_ASSETS | Lãi/(lỗ) từ thanh lý tài sản cố định | 5 | 2 | False | VNĐ | 11000000.0 | | 2018 | CF\_LOSS\_GAIN\_FROM\_INVESTMENT | Lãi, lỗ từ hoạt động đầu tư | 6 | 3 | False | VNĐ | 10000000.0 | | 2018 | CF\_INTEREST\_EXPENSE | Chi phí lãi vay | 7 | 1 | False | VNĐ | 9000000.0 | | 2018 | CF\_INTEREST\_AND\_DIVIDENDS\_RECEIVED | Thu lãi và cổ tức | 8 | 2 | False | VNĐ | 8000000.0 | | 2018 | CF\_OPERATING\_PROFIT\_BEFORE\_CHANGES\_IN\_WORKING\_CAPITAL | Lợi nhuận từ hoạt động kinh doanh trước thay đổi vốn lưu động | 9 | 3 | False | VNĐ | 7000000.0 | | 2018 | CF\_INCREASE\_DECREASE\_IN\_RECEIVABLES | Tăng, giảm các khoản phải thu | 10 | 1 | False | VNĐ | 6000000.0 | | 2018 | CF\_INCREASE\_DECREASE\_IN\_INVENTORY | Tăng, giảm hàng tồn kho | 11 | 2 | False | VNĐ | 5000000.0 | | 2018 | CF\_INCREASE\_DECREASE\_IN\_PAYABLES | Tăng, giảm các khoản phải thu | 12 | 3 | False | VNĐ | 4000000.0 | | 2018 | CF\_INCREASE\_DECREASE\_IN\_PREPAID\_EXPENSES | Tăng, giảm chi phí trả trước | 13 | 1 | False | VNĐ | 3000000.0 | | 2018 | CF\_INTEREST\_PAID | Tiền lãi vay đã trả | 14 | 2 | False | VNĐ | 2000000.0 | | 2018 | CF\_CORPORATE\_INCOME\_TAX\_PAID | Tiền thuế thu nhập thực nộp trong kỳ | 15 | 3 | False | VNĐ | 1000000.0 | ### Fundamental().equity('TCB').income\_statement() (v3.2.8) | period | id | name | order | level | off\_balance | unit | value | | :----- | :----------------------------------------------------------------- | :------------------------------------------------------- | :---- | :---- | :----------- | :--- | :--------- | | 2018 | IS\_PROFIT\_BEFORE\_TAX | Tổng lợi nhuận kế toán trước thuế | 1 | 1 | False | VNĐ | 15000000.0 | | 2018 | IS\_CURRENT\_CORPORATE\_INCOME\_TAX\_EXPENSES | Chi phí thuế TNDN hiện hành | 2 | 2 | False | VNĐ | 14000000.0 | | 2018 | IS\_DEFERRED\_INCOME\_TAX\_EXPENSES | Chi phí thuế TNDN hoãn lại | 3 | 3 | False | VNĐ | 13000000.0 | | 2018 | IS\_NET\_PROFIT\_AFTER\_TAX | Lợi nhuận sau thuế thu nhập doanh nghiệp | 4 | 1 | False | VNĐ | 12000000.0 | | 2018 | IS\_MINORITY\_INTEREST | Lợi ích của cổ đông không kiểm soát | 5 | 2 | False | VNĐ | 11000000.0 | | 2018 | IS\_PROFIT\_AFTER\_TAX\_FOR\_SHAREHOLDERS\_OF\_PARENT\_COMPANY | Lợi nhuận sau thuế của cổ đông công ty mẹ | 6 | 3 | False | VNĐ | 10000000.0 | | 2018 | IS\_INTEREST\_INCOME\_AND\_SIMILAR\_INCOME | Thu nhập lãi và các khoản thu nhập tương tự | 7 | 1 | False | VNĐ | 9000000.0 | | 2018 | IS\_NET\_INTEREST\_INCOME | Thu nhập lãi thuần | 8 | 2 | False | VNĐ | 8000000.0 | | 2018 | IS\_FEE\_AND\_COMMISSION\_INCOME | Thu nhập từ hoạt động dịch vụ | 9 | 3 | False | VNĐ | 7000000.0 | | 2018 | IS\_NET\_FEE\_AND\_COMMISSION\_INCOME | Lãi thuần từ hoạt động dịch vụ | 10 | 1 | False | VNĐ | 6000000.0 | | 2018 | IS\_NET\_GAIN\_LOSS\_FROM\_FOREIGN\_CURRENCIES\_AND\_GOLD\_TRADING | Lãi/(lỗ) thuần từ hoạt động kinh doanh ngoại hối và vàng | 11 | 2 | False | VNĐ | 5000000.0 | | 2018 | IS\_NET\_GAIN\_LOSS\_FROM\_TRADING\_SECURITIES | Lãi thuần từ mua bán chứng khoán kinh doanh | 12 | 3 | False | VNĐ | 4000000.0 | | 2018 | IS\_NET\_GAIN\_LOSS\_FROM\_INVESTMENT\_SECURITIES | Lãi thuần từ mua bán chứng khoán đầu tư | 13 | 1 | False | VNĐ | 3000000.0 | | 2018 | IS\_OTHER\_INCOME | Thu nhập khác | 14 | 2 | False | VNĐ | 2000000.0 | | 2018 | IS\_NET\_OTHER\_INCOME | Lãi thuần từ hoạt động khác | 15 | 3 | False | VNĐ | 1000000.0 | ### Fundamental().equity('TCB').ratio() (v3.2.8) | period | id | name | order | level | off\_balance | unit | value | | :----- | :--------------------------- | :-------------------------------- | :---- | :---- | :----------- | :--- | :---- | | 2018 | RT\_CAT\_INFO\_VALUATION | Định giá & Thông tin Doanh nghiệp | 1 | 1 | False | % | 15.0 | | 2018 | RT\_CAT\_PROFITABILITY | Hiệu quả hoạt động & Sinh lời | 2 | 2 | False | % | 14.0 | | 2018 | RT\_CAT\_LIQUIDITY\_SAFETY | Thanh khoản & An toàn tài chính | 3 | 3 | False | % | 13.0 | | 2018 | RT\_CAT\_FINANCIAL\_LEVERAGE | Đòn bẩy tài chính | 4 | 1 | False | % | 12.0 | | 2018 | RT\_CAT\_BANKING\_SPECIFICS | Đặc thù ngành Ngân hàng | 5 | 2 | False | % | 11.0 | | 2018 | RT\_VAL\_PE | P/E cơ bản | 6 | 3 | False | % | 10.0 | | 2018 | RT\_VAL\_PB | P/B | 7 | 1 | False | % | 9.0 | | 2018 | RT\_VAL\_PS | P/S | 8 | 2 | False | % | 8.0 | | 2018 | RT\_VAL\_EV\_EBITDA | EV/EBITDA | 9 | 3 | False | % | 7.0 | | 2018 | RT\_VAL\_DIV\_YIELD | Tỷ suất cổ tức | 10 | 1 | False | % | 6.0 | | 2018 | RT\_VAL\_MARKET\_CAP | Vốn hóa thị trường | 11 | 2 | False | % | 5.0 | | 2018 | RT\_VAL\_EPS | EPS cơ bản | 12 | 3 | False | % | 4.0 | | 2018 | RT\_VAL\_BETA | Hệ số beta | 13 | 1 | False | % | 3.0 | | 2018 | RT\_VAL\_BVPS | Giá trị sổ sách/một cổ phiếu | 14 | 2 | False | % | 2.0 | | 2018 | RT\_PRT\_ROE | ROE % | 15 | 3 | False | % | 1.0 | ### Fundamental().equity('TCB').note() (v3.2.8) | period | id | name | order | level | off\_balance | unit | value | | :----- | :------------------------------------------------------------------ | :----------------------------------------------- | :---- | :---- | :----------- | :--- | :--------- | | 2018 | NT\_BS\_TRADING\_SECURITIES | Chứng khoán thương mại | 1 | 1 | False | VNĐ | 15000000.0 | | 2018 | NT\_BS\_DEBT\_SECURITIES | Chứng khoán nợ | 2 | 2 | False | VNĐ | 14000000.0 | | 2018 | NT\_BS\_GOVERNMENT\_BONDS | Trái phiếu chính phủ | 3 | 3 | False | VNĐ | 13000000.0 | | 2018 | NT\_BS\_GOVERNMENT\_GUARANTEED\_BONDS | Trái phiếu chính phủ bảo lãnh | 4 | 1 | False | VNĐ | 12000000.0 | | 2018 | NT\_BS\_SECURITIES\_ISSUED\_BY\_LOCAL\_CREDIT\_INSTITUTIONS | Trái phiếu do các TCTD khác trong nước phát hành | 5 | 2 | False | VNĐ | 11000000.0 | | 2018 | NT\_BS\_SECURITIES\_ISSUED\_BY\_LOCAL\_ECONOMIC\_ENTITIES | Trái phiếu do các TCKT trong nước phát hành | 6 | 3 | False | VNĐ | 10000000.0 | | 2018 | NT\_BS\_FOREIGN\_DEBT\_SECURITIES | Chứng khoán Nợ nước ngoài | 7 | 1 | False | VNĐ | 9000000.0 | | 2018 | NT\_BS\_EQUITY\_SECURITIES | Chứng khoán vốn | 8 | 2 | False | VNĐ | 8000000.0 | | 2018 | NT\_BS\_EQUITY\_SECURITIES\_ISSUED\_BY\_LOCAL\_CREDIT\_INSTITUTIONS | Chứng khoán Vốn do các TCTD khác phát hành | 9 | 3 | False | VNĐ | 7000000.0 | | 2018 | NT\_BS\_EQUITY\_SECURITIES\_ISSUED\_BY\_LOCAL\_ECONOMIC\_ENTITIES | Chứng khoán Vốn do các TCKT trong nước phát hành | 10 | 1 | False | VNĐ | 6000000.0 | | 2018 | NT\_BS\_FOREIGN\_EQUITY\_SECURITIES | Chứng khoán Vốn nước ngoài | 11 | 2 | False | VNĐ | 5000000.0 | | 2018 | NT\_BS\_OTHER\_TRADING\_SECURITIES | Chứng khoán kinh doanh khác | 12 | 3 | False | VNĐ | 4000000.0 | | 2018 | NT\_BS\_PROVISION\_TRADING\_SECURITIES | Dự phòng rủi ro chứng khoán kinh doanh | 13 | 1 | False | VNĐ | 3000000.0 | | 2018 | NT\_BS\_PROVISION\_DEVALUATION\_TRADING\_SECURITIES | Dự phòng giảm giá | 14 | 2 | False | VNĐ | 2000000.0 | | 2018 | NT\_BS\_GENERAL\_ALLOWANCE | Dự phòng chung | 15 | 3 | False | VNĐ | 1000000.0 | ### Fundamental().equity('TCB').balance\_sheet() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------------------------------------------------------------------- | ------------ | ------------------- | ------------------ | | **`period`** | `object` | Kỳ | `2026-Q2` | | **`a_tai_san`** | `object` |
| None | | **`i_tien_mat_vang_bac_da_quy`** | `object` |
| `3909425000000` | | **`ii_tien_gui_tai_nhnn`** | `object` |
| `95127975000000` | | **`iii_tien_vang_gui_tai_cac_tctd_khac_va_cho_vay_cac_tctd_khac`** | `object` |
| `85416520000000` | | **`1_tien_vang_gui_tai_cac_tctd_khac`** | `object` |
| `72701055000000` | | **`2_cho_vay_cac_tctd_khac`** | `object` |
| `12896615000000` | | **`3_du_phong_rui_ro_cho_vay_cac_tctd_khac`** | `object` |
| `-181150000000` | | **`iv_chung_khoan_kinh_doanh`** | `object` |
| `342780000000` | | **`1_chung_khoan_kinh_doanh`** | `object` |
| `348048000000` | | **`2_du_phong_giam_gia_chung_khoan_kinh_doanh`** | `object` |
| `-5268000000` | | **`v_cac_cong_cu_tai_chinh_phai_sinh_va_cac_tai_san_tai_chinh_khac`** | `object` |
| None | | **`vi_cho_vay_khach_hang`** | `object` |
| `835813283000000` | | **`1_cho_vay_va_cho_thue_tai_chinh_khach_hang`** | `object` |
| `847335568000000` | | **`2_du_phong_rui_ro_cho_vay_va_cho_thue_tai_chinh_khach_hang`** | `object` |
| `-11522285000000` | | **`vii_hoat_dong_mua_no`** | `object` |
| `17800000000` | | **`1_mua_no`** | `object` |
| `19617000000` | | **`2_du_phong_rui_ro_hoat_dong_mua_no`** | `object` |
| `-1817000000` | | **`viii_chung_khoan_dau_tu`** | `object` |
| `179944154000000` | | **`1_chung_khoan_dau_tu_san_sang_de_ban`** | `object` |
| `180698281000000` | | **`2_chung_khoan_dau_tu_giu_den_ngay_dao_han`** | `object` |
| None | | **`3_du_phong_giam_gia_chung_khoan_dau_tu`** | `object` |
| `-754127000000` | | **`ix_gop_von_dau_tu_dai_han`** | `object` |
| `3076756000000` | | **`1_dau_tu_vao_cong_ty_con`** | `object` |
| None | | **`2_dau_tu_vao_cong_ty_lien_doanh_lien_ket`** | `object` |
| `27397000000` | | **`3_dau_tu_dai_han_khac`** | `object` |
| `3050508000000` | | **`4_du_phong_giam_gia_dau_tu_dai_han`** | `object` |
| `-1149000000` | | **`x_tai_san_co_dinh`** | `object` |
| `12324755000000` | | **`1_tai_san_co_dinh_huu_hinh`** | `object` |
| `6185743000000` | | **`nguyen_gia_tscd`** | `object` |
| `10546242000000` | | **`hao_mon_tscd`** | `object` |
| `-4407230000000` | | **`2_tai_san_co_dinh_thue_tai_chinh`** | `object` |
| None | | **`3_tai_san_co_dinh_vo_hinh`** | `object` |
| `6139012000000` | | **`a_nguyen_gia_bdsdt`** | `object` |
| None | | **`b_hao_mon_bdsdt`** | `object` |
| None | | **`xii_tai_san_co_khac`** | `object` |
| `57103475000000` | | **`1_cac_khoan_phai_thu`** | `object` |
| `43068933000000` | | **`2_cac_khoan_lai_phi_phai_thu`** | `object` |
| `11375555000000` | | **`3_tai_san_thue_tndn_hoan_lai`** | `object` |
| `45870000000` | | **`4_tai_san_co_khac`** | `object` |
| `2623560000000` | | **`trong_do_loi_the_thuong_mai`** | `object` |
| None | | **`5_cac_khoan_du_phong_rui_ro_cho_cac_tai_san_co_noi_bang_khac`** | `object` |
| `-10443000000` | | **`total_assets`** | `object` | Tổng tài sản | `1273076923000000` | | **`b_no_phai_tra_va_von_chu_so_huu`** | `object` |
| None | | **`i_cac_khoan_no_chinh_phu_va_nhnn`** | `object` |
| `8245783000000` | | **`ii_tien_gui_va_vay_cac_tctd_khac`** | `object` |
| `164019459000000` | | **`1_tien_gui_cua_cac_tctd_khac`** | `object` |
| `90685022000000` | | **`2_vay_cac_tctd_khac`** | `object` |
| `73334437000000` | | **`iii_tien_gui_cua_khach_hang`** | `object` |
| `662447730000000` | | **`iv_cac_cong_cu_tai_chinh_phai_sinh_va_cac_khoan_no_tai_chinh_khac`** | `object` |
| `2214942000000` | | **`v_von_tai_tro_uy_thac_dau_tu_cho_vay_ma_tctd_chiu_rui_ro`** | `object` |
| None | | **`vi_phat_hanh_giay_to_co_gia`** | `object` |
| `212079904000000` | | **`vii_cac_khoan_no_khac`** | `object` |
| `35071955000000` | | **`1_cac_khoan_lai_phi_phai_tra`** | `object` |
| `13509983000000` | | **`2_thue_tndn_hoan_lai_phai_tra`** | `object` |
| None | | **`3_cac_khoan_phai_tra_va_cong_no_khac`** | `object` |
| `21561972000000` | | **`4_du_phong_rui_ro_khac_du_phong_cho_cong_no_tiem_an_va_cam_ket_ngoai_bang`** | `object` |
| None | | **`liabilities`** | `object` | Nợ phải trả | `1084079773000000` | | **`viii_von_va_cac_quy`** | `object` |
| `188997150000000` | | **`1_von_cua_tctd`** | `object` |
| `82324295000000` | | **`a_von_dieu_le`** | `object` |
| `70862404000000` | | **`b_von_dau_tu_xdcb`** | `object` |
| None | | **`c_thang_du_von_co_phan`** | `object` |
| `-124000000` | | **`d_co_phieu_quy`** | `object` |
| None | | **`e_co_phieu_uu_dai`** | `object` |
| None | | **`g_von_khac`** | `object` |
| `11462015000000` | | **`2_quy_cua_tctd`** | `object` |
| `28659714000000` | | **`3_chenh_lech_ty_gia_hoi_doai`** | `object` |
| None | | **`4_chenh_lech_danh_gia_lai_tai_san`** | `object` |
| None | | **`5_loi_nhuan_chua_phan_phoi_lo_luy_ke`** | `object` |
| `68178258000000` | | **`6_loi_ich_co_dong_khong_kiem_soat`** | `object` |
| `9834883000000` | | **`ix_loi_ich_cua_co_dong_thieu_so`** | `object` |
| None | | **`total_liabilities_equity`** | `object` | Tổng cộng Nguồn vốn | `1273076923000000` | | **`vii_chung_khoan_dau_tu`** | `object` |
| None | | **`viii_gop_von_dau_tu_dai_han`** | `object` |
| None | | **`ix_tai_san_co_dinh`** | `object` |
| None | | **`x_bat_dong_san_dau_tu`** | `object` |
| None | | **`xi_tai_san_co_khac`** | `object` |
| None | ### Fundamental().equity('TCB').cash\_flow() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------- | ----------- | | **`adjustment_for_exchange_rate_changes`** | `object` | Adjustment For Exchange Tỷ lệ/Lãi suất Changes | None | | **`cash_and_cash_equivalents_at_beginning_of_period`** | `object` | Tiền và tương đương tiền đầu kỳ | None | | **`cash_and_cash_equivalents_at_end_of_period`** | `object` | Tiền và tương đương tiền cuối kỳ | None | | **`cash_from_debt_write_offs`** | `object` | Tiền From Debt Write Offs | None | | **`corporate_income_tax_paid`** | `object` | Corporate Thu nhập Tax Paid | None | | **`decrease_in_provisions_for_loss`** | `object` | Decrease in provisions for loss | None | | **`dividends_and_profit_from_long_term_investments`** | `object` | Dividends And Lợi nhuận From Long Term Đầu tư | None | | **`dividends_paid_to_shareholders`** | `object` | Dividends paid to shareholders | None | | **`increase_decrease_in_customer_deposits`** | `object` | Tăng/giảm customer deposits | None | | **`increase_decrease_in_debts_to_government_and_sbv`** | `object` | Tăng/giảm debts to government and sbv | None | | **`increase_decrease_in_deposits_and_borrowings_from_credit_institutions`** | `object` | Tăng/giảm deposits and borrowings from credit institutions | None | | **`increase_decrease_in_deposits_and_loans_to_other_credit_institutions`** | `object` | Tăng/giảm deposits and loans to other credit institutions | None | | **`increase_decrease_in_derivatives_and_other_financial_instruments`** | `object` | Tăng/giảm derivatives and other financial instruments | None | | **`increase_decrease_in_derivatives_and_other_financial_liabilities`** | `object` | Tăng/giảm derivatives and other financial liabilities | None | | **`increase_decrease_in_issued_valuable_papers`** | `object` | Tăng/giảm issued valuable papers | None | | **`increase_decrease_in_loans_to_customers`** | `object` | Tăng/giảm loans to customers | None | | **`increase_decrease_in_sponsored_capital`** | `object` | Tăng/giảm sponsored capital | None | | **`increase_decrease_in_trading_securities`** | `object` | Tăng/giảm trading securities | None | | **`increase_in_capital_from_contribution_and_or_share_issuance`** | `object` | Increase in capital from contribution and or share issuance | None | | **`interest_and_similar_expenses_paid`** | `object` | Interest and similar expenses paid | None | | **`interest_and_similar_income_received`** | `object` | Interest And Similar Thu nhập Received | None | | **`net_cash_flow_for_the_period`** | `object` | Lưu chuyển tiền thuần trong kỳ | None | | **`net_cash_flows_from_financing_activities`** | `object` | Lưu chuyển tiền thuần từ HĐTC | None | | **`net_cash_flows_from_investing_activities`** | `object` | Lưu chuyển tiền thuần từ HĐĐT | None | | **`net_cash_flows_from_operating_activities`** | `object` | Lưu chuyển tiền thuần từ HĐKD | None | | **`net_cash_from_operating_activities_before_working_capital_changes`** | `object` | Net Tiền From Operating Activities Before Working Capital Changes | None | | **`net_cash_from_trading_activities`** | `object` | Net Tiền From Trading Activities | None | | **`other_changes_in_operating_assets`** | `object` | Other Changes In Operating Tài sản | None | | **`other_changes_in_operating_liabilities`** | `object` | Other Changes In Operating Nợ | None | | **`other_income`** | `object` | Other Thu nhập | None | | **`payments_for_employees_and_management`** | `object` | Payments for employees and management | None | | **`payments_for_investment_in_other_entities`** | `object` | Payments for investment in other entities | None | | **`payments_for_long_term_valuable_papers_and_long_term_borrowings`** | `object` | Payments for long term valuable papers and long term borrowings | None | | **`payments_from_credit_institution_funds`** | `object` | Payments from credit institution funds | None | | **`payments_from_disposal_of_fixed_assets`** | `object` | Payments From Disposal Of Fixed Tài sản | None | | **`period`** | `object` | Kỳ | `2026-Q2` | | **`purchase_of_fixed_assets`** | `object` | Purchase Of Fixed Tài sản | None | | **`purchase_of_investment_properties`** | `object` | Purchase of investment properties | None | | **`receipts_from_disposal_of_fixed_assets`** | `object` | Receipts From Disposal Of Fixed Tài sản | None | | **`receipts_from_investment_in_other_entities`** | `object` | Receipts from investment in other entities | None | | **`receipts_from_long_term_valuable_papers_and_long_term_borrowings`** | `object` | Receipts from long term valuable papers and long term borrowings | None | | **`receipts_from_sale_of_investment_properties`** | `object` | Receipts from sale of investment properties | None | | **`receipts_from_treasury_shares`** | `object` | Receipts from treasury shares | None | | **`service_income_received`** | `object` | Service Thu nhập Received | None | ### Fundamental().equity('TCB').income\_statement() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------------------------------------------------------------------------------------------------------- | ------------ | ------- | ---------------- | | **`period`** | `object` | Kỳ | `2026-Q2` | | **`1_thu_nhap_lai_va_cac_khoan_thu_nhap_tuong_tu`** | `object` |
| `22861342000000` | | **`2_chi_phi_lai_va_cac_chi_phi_tuong_tu`** | `object` |
| `12098340000000` | | **`i_thu_nhap_lai_thuan`** | `object` |
| `10763002000000` | | **`3_thu_nhap_tu_hoat_dong_dich_vu`** | `object` |
| `5004364000000` | | **`4_chi_phi_hoat_dong_dich_vu`** | `object` |
| `1342166000000` | | **`ii_lai_lo_thuan_tu_hoat_dong_dich_vu`** | `object` |
| `3662198000000` | | **`iii_lai_lo_thuan_tu_hoat_dong_kinh_doanh_ngoai_hoi_va_vang`** | `object` |
| `-68527000000` | | **`iv_lai_lo_thuan_tu_mua_ban_chung_khoan_kinh_doanh`** | `object` |
| `28494000000` | | **`v_lai_lo_thuan_tu_mua_ban_chung_khoan_dau_tu`** | `object` |
| `81770000000` | | **`5_thu_nhap_tu_hoat_dong_khac`** | `object` |
| `2105280000000` | | **`6_chi_phi_hoat_dong_khac`** | `object` |
| `1635335000000` | | **`vi_lai_lo_thuan_tu_hoat_dong_khac`** | `object` |
| `469945000000` | | **`vii_thu_nhap_tu_gop_von_mua_co_phan`** | `object` |
| `4899000000` | | **`viii_chi_phi_hoat_dong`** | `object` |
| `4620127000000` | | **`ix_loi_nhuan_thuan_tu_hoat_dong_kinh_doanh_truoc_chi_phi_du_phong_rui_ro_tin_dung_i_ii_iii_iv_v_vi_vii_viii`** | `object` |
| `10321654000000` | | **`x_chi_phi_du_phong_rui_ro_tin_dung`** | `object` |
| `651638000000` | | **`xi_tong_loi_nhuan_truoc_thue_ix_x`** | `object` |
| `9670016000000` | | **`7_chi_phi_thue_tndn_hien_hanh`** | `object` |
| `1948060000000` | | **`8_chi_phi_thue_tndn_hoan_lai`** | `object` |
| `-4686000000` | | **`xii_chi_phi_thue_tndn`** | `object` |
| `1943374000000` | | **`xiii_loi_nhuan_sau_thue_xi_xii`** | `object` |
| `7726642000000` | | **`xiv_loi_ich_cua_co_dong_thieu_so`** | `object` |
| `376583000000` | | **`xv_loi_nhuan_sau_thue_cua_co_dong_cua_ngan_hang_me_xiii_xiv`** | `object` |
| `7350059000000` | ### Fundamental().equity('TCB').note() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------------------------------------------------------------------- | ------------ | ----------------------------------------- | ------------------- | | **`period`** | `object` | Kỳ | `2018` | | **`administration_activities_and_supportive_services`** | `object` |
| `201007000000.0` | | **`agriculture_and_forestry`** | `object` |
| `260998000000.0` | | **`allowances_for_available_for_sale_securities`** | `object` |
| `-189691000000.0` | | **`allowances_for_decline_in_value_of_available_for_sale_securities`** | `object` |
| `-3797000000.0` | | **`allowances_for_decline_in_value_of_held_to_maturity_investment_securities`** | `object` |
| `0.0` | | **`allowances_for_decline_in_value_of_trading_securities`** | `object` |
| `-317000000.0` | | **`allowances_for_held_to_maturity_investment_securities`** | `object` |
| `-159422000000.0` | | **`allowances_for_special_bonds`** | `object` |
| `0.0` | | **`allowances_for_trading_securities`** | `object` |
| `-10861000000.0` | | **`arts_and_entertainment`** | `object` |
| `127065000000.0` | | **`asset_expenses`** | `object` |
| `1020053000000.0` | | **`available_for_sale_investment_securities`** | `object` | Available For Sale Investment Chứng khoán | `66435570000000.0` | | **`bad`** | `object` |
| `1703181000000.0` | | **`car`** | `object` |
| `0.143` | | **`central`** | `object` |
| `0.0` | | **`community_activities`** | `object` |
| `0.0` | | **`construction`** | `object` |
| `8095573000000.0` | | **`current`** | `object` |
| `154548122000000.0` | | **`current_deposits`** | `object` |
| `54612613000000.0` | | **`debt_securities`** | `object` |
| `408110548000000.0` | | **`debt_securities_issued_by_other_local_credit_institutions`** | `object` |
| `0.0` | | **`debt_securities_issued_by_other_local_economic_entities`** | `object` |
| `20206200000000.0` | | **`denominated_in_fc`** | `object` |
| `13572795000000.0` | | **`denominated_in_fc_and_gold`** | `object` |
| `9352730000000.0` | | **`denominated_in_vnd`** | `object` |
| `676856448000000.0` | | **`deposit_interest_expenses`** | `object` |
| `8233723000000.0` | | **`deposits_by_currency`** | `object` |
| `201414532000000.0` | | **`deposits_by_type_of_customers`** | `object` |
| `201414532000000.0` | | **`deposits_by_type_of_deposits`** | `object` |
| `201414532000000.0` | | **`deposits_for_special_purposes`** | `object` |
| `0.0` | | **`depreciation`** | `object` |
| `259603000000.0` | | **`discounted_notes_and_valuable_papers`** | `object` |
| `361280000000.0` | | **`domestic_businesses_and_individuals`** | `object` |
| `158971627000000.0` | | **`doubtful`** | `object` |
| `862510000000.0` | | **`education_and_training`** | `object` |
| `154973000000.0` | | **`electricity_fuel_and_hot_water_generation_and_distribution`** | `object` |
| `2409681000000.0` | | **`equity_securities`** | `object` |
| `12000000.0` | | **`equity_securities_issued_by_other_local_credit_institutions`** | `object` |
| `0.0` | | **`equity_securities_issued_by_other_local_economic_entities`** | `object` |
| `8000000.0` | | **`estate_agents_and_consultants`** | `object` |
| `13554781000000.0` | | **`expenses_for_derivative_financial_instruments`** | `object` |
| `-1491146000000.0` | | **`expenses_for_foreign_exchange_spot_transactions`** | `object` |
| `-154420000000.0` | | **`expenses_for_gold_trading`** | `object` |
| `0.0` | | **`expenses_for_interest_rate_swap`** | `object` |
| `0.0` | | **`expenses_for_other_credit_activities`** | `object` |
| `0.0` | | **`expenses_for_other_derivative_financial_instruments`** | `object` |
| `-1228491000000.0` | | **`expenses_for_trading_securities`** | `object` |
| `-187865000000.0` | | **`expenses_from_trading_investment_securities`** | `object` |
| `-389655000000.0` | | **`expenses_on_agency_services`** | `object` |
| `0.0` | | **`expenses_on_brokerage_service`** | `object` |
| `-30526000000.0` | | **`expenses_on_guarantee_activities`** | `object` |
| `0.0` | | **`expenses_on_insurance_activities`** | `object` |
| `0.0` | | **`expenses_on_other_services`** | `object` |
| `-309329000000.0` | | **`expenses_on_settlement_services`** | `object` |
| `-517780000000.0` | | **`expenses_on_treasury_activities`** | `object` |
| `-58102000000.0` | | **`finance_lease`** | `object` |
| `0.0` | | **`financial_reserve_fund`** | `object` |
| `2975083000000.0` | | **`financial_services`** | `object` |
| `9468647000000.0` | | **`foreign_companies`** | `object` |
| `9876622000000.0` | | **`foreign_debt_securities`** | `object` |
| `0.0` | | **`foreign_equity_securities`** | `object` |
| `0.0` | | **`frozen_and_awaiting_resolution_loans`** | `object` |
| `0.0` | | **`gain_from_foreign_currency_revaluation`** | `object` |
| `0.0` | | **`gain_from_realization_of_other_long_term_investment`** | `object` |
| `0.0` | | **`general_allowance`** | `object` |
| `-1067580000000.0` | | **`government_bonds`** | `object` |
| `37550592000000.0` | | **`government_guaranteed_bonds`** | `object` |
| `38568198000000.0` | | **`hanoi`** | `object` |
| `0.0` | | **`hcm_city`** | `object` |
| `0.0` | | **`healthcare_and_social_work`** | `object` |
| `37304000000.0` | | **`held_to_maturity_investment_securities`** | `object` | Held To Maturity Investment Chứng khoán | `20076778000000.0` | | **`hotels_and_restaurants`** | `object` |
| `927745000000.0` | | **`household_supporting_activities`** | `object` |
| `95172000000.0` | | **`income_from_agency_services`** | `object` |
| `212520000000.0` | | **`income_from_brokerage_service`** | `object` |
| `118572000000.0` | | **`income_from_derivative_financial_instruments`** | `object` |
| `848966000000.0` | | **`income_from_foreign_exchange_spot_transactions`** | `object` |
| `1030351000000.0` | | **`income_from_gold_trading`** | `object` |
| `0.0` | | **`income_from_guarantee_activities`** | `object` |
| `1160413000000.0` | | **`income_from_insurance_activities`** | `object` |
| `722481000000.0` | | **`income_from_loans_disbursed_by_the_risk_reserve_fund`** | `object` |
| `1422895000000.0` | | **`income_from_other_services`** | `object` |
| `208754000000.0` | | **`income_from_settlement_services`** | `object` |
| `1763054000000.0` | | **`income_from_trading_investment_securities`** | `object` |
| `1303955000000.0` | | **`income_from_trading_securities`** | `object` |
| `350135000000.0` | | **`income_from_treasury_activities`** | `object` |
| `2523000000.0` | | **`individuals`** | `object` |
| `428880278000000.0` | | **`information_and_communications`** | `object` |
| `147061000000.0` | | **`insurance_and_deposit_insurance_fees`** | `object` |
| `193813000000.0` | | **`interest_and_seminal_income`** | `object` |
| `21413626000000.0` | | **`interest_and_similar_expenses`** | `object` |
| `10023687000000.0` | | **`interest_bearing_liabilities`** | `object` |
| `0.0` | | **`interest_earning_assets`** | `object` |
| `0.0` | | **`interest_expense_for_issuance_of_valuable_papers`** | `object` |
| `1353122000000.0` | | **`interest_income_from_debt_securities`** | `object` |
| `4140607000000.0` | | **`interest_income_from_deposits`** | `object` |
| `606159000000.0` | | **`interest_income_from_finance_leases`** | `object` |
| `0.0` | | **`interest_income_from_investments_securities`** | `object` |
| `4140607000000.0` | | **`interest_income_from_loans_to_customers`** | `object` |
| `15460433000000.0` | | **`interest_income_from_trading_securities`** | `object` |
| `0.0` | | **`international_organization_activities`** | `object` |
| `0.0` | | **`investment_and_development_fund`** | `object` |
| `0.0` | | **`investment_securities`** | `object` | Investment Chứng khoán | `86512348000000.0` | | **`limited_and_joint_stock_companies`** | `object` |
| `77809083000000.0` | | **`listed`** | `object` |
| `16305525000000.0` | | **`listing_status_of_trading_securities`** | `object` |
| `7583090000000.0` | | **`loan_interest_expenses`** | `object` |
| `436842000000.0` | | **`loans_and_advances_by_currency`** | `object` |
| `159939217000000.0` | | **`loans_and_advances_by_geography`** | `object` |
| `0.0` | | **`loans_and_advances_by_grading`** | `object` |
| `159939217000000.0` | | **`loans_and_advances_by_industry`** | `object` |
| `159939217000000.0` | | **`loans_and_advances_by_maturity`** | `object` |
| `159939217000000.0` | | **`loans_and_advances_by_type_of_customers`** | `object` |
| `159939217000000.0` | | **`loans_and_advances_by_types_of_customers`** | `object` |
| `159939217000000.0` | | **`loans_funded_by_gov_and_int_l_institutions`** | `object` |
| `472609000000.0` | | **`loans_instructed_by_the_gov`** | `object` |
| `0.0` | | **`loans_to_foreign_businesses_and_individuals`** | `object` |
| `39228000000.0` | | **`local_and_private_companies`** | `object` |
| `804018000000.0` | | **`long_term_loans`** | `object` |
| `62782363000000.0` | | **`loss_from_foreign_currency_revaluation`** | `object` |
| `0.0` | | **`loss_from_realization_of_other_long_term_investment`** | `object` |
| `0.0` | | **`manufacturing`** | `object` |
| `23099727000000.0` | | **`manufacturing_and_processing`** | `object` |
| `19076386000000.0` | | **`margin_deposits`** | `object` |
| `3188540000000.0` | | **`medium_term_loans`** | `object` |
| `36774904000000.0` | | **`mekong_delta`** | `object` |
| `0.0` | | **`mining`** | `object` |
| `1590134000000.0` | | **`net_gain_from_gold_trading_and_foreign_currencies`** | `object` |
| `233751000000.0` | | **`net_gain_from_investment_securities`** | `object` |
| `756585000000.0` | | **`net_gain_from_trading_securities`** | `object` |
| `168433000000.0` | | **`net_profit_from_services`** | `object` |
| `3272580000000.0` | | **`net_profits_from_other_activities`** | `object` |
| `1633777000000.0` | | **`operating_expenses`** | `object` | Chi phí hoạt động | `5842507000000.0` | | **`other_asset_payment`** | `object` |
| `760450000000.0` | | **`other_expenses`** | `object` |
| `-284901000000.0` | | **`other_incomes`** | `object` |
| `180185000000.0` | | **`other_incomes_from_credit_activities`** | `object` |
| `1206427000000.0` | | **`other_loans`** | `object` |
| `0.0` | | **`other_operating_expenses`** | `object` |
| `519142000000.0` | | **`other_services`** | `object` |
| `6568616000000.0` | | **`other_trading_securities`** | `object` |
| `0.0` | | **`others`** | `object` |
| `626615195000000.0` | | **`others_fund`** | `object` |
| `474000000.0` | | **`party_unions_compulsory_social_security`** | `object` |
| `0.0` | | **`payment_for_company_affairs`** | `object` |
| `770133000000.0` | | **`payment_on_behalf_of_customers`** | `object` |
| `94473000000.0` | | **`payments_for_debt_selling`** | `object` |
| `0.0` | | **`payments_for_disposals_of_assets`** | `object` |
| `0.0` | | **`personal_and_commodity_activities`** | `object` |
| `0.0` | | **`personal_and_public_services`** | `object` |
| `7029164000000.0` | | **`proceeds_from_debt_trading_activities`** | `object` |
| `0.0` | | **`proceeds_from_disposals_of_fixed_assets`** | `object` |
| `0.0` | | **`proceeds_from_liquidation_of_vamc_bonds`** | `object` |
| `0.0` | | **`proceeds_from_other_derivative_financial_instruments`** | `object` |
| `1544089000000.0` | | **`profession_science_and_technology`** | `object` |
| `791378000000.0` | | **`provision_for_diminution_in_long_term_investment_and_bad_debts`** | `object` |
| `-3195000000.0` | | **`report_period`** | `object` | Kỳ báo cáo tài chính | `2018.0` | | **`reserves`** | `object` |
| `3867846000000.0` | | **`reversal_of_provision_for_impairment_of_available_for_sale_securities`** | `object` |
| `-169734000000.0` | | **`reversal_of_provision_for_impairment_of_held_to_maturity_securities`** | `object` |
| `12019000000.0` | | **`reversal_of_provision_for_impairment_of_trading_securities`** | `object` |
| `6163000000.0` | | **`salary_and_allowances`** | `object` |
| `3239958000000.0` | | **`saving_deposits`** | `object` |
| `0.0` | | **`securities_issued_by_other_local_credit_institutions`** | `object` |
| `18831082000000.0` | | **`securities_issued_by_other_local_economic_entities`** | `object` |
| `78899752000000.0` | | **`severance_allowance`** | `object` |
| `0.0` | | **`short_term_loans`** | `object` |
| `60381950000000.0` | | **`social_insurance_and_security`** | `object` |
| `0.0` | | **`special_bonds_issued_by_vamc`** | `object` |
| `0.0` | | **`special_mentioned`** | `object` |
| `2587646000000.0` | | **`specific_allowance`** | `object` |
| `0.0` | | **`spending_on_social_works`** | `object` |
| `0.0` | | **`staff_costs`** | `object` |
| `3239958000000.0` | | **`staff_subsidies`** | `object` |
| `0.0` | | **`state_owned_companies`** | `object` |
| `21649694000000.0` | | **`substandard`** | `object` |
| `237758000000.0` | | **`supplement_capital_reserves`** | `object` |
| `892289000000.0` | | **`taxes_and_fees`** | `object` |
| `102603000000.0` | | **`term_deposits`** | `object` |
| `143613379000000.0` | | **`ticker`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`trading`** | `object` |
| `21171980000000.0` | | **`trading_securities`** | `object` | Trading Chứng khoán | `7572229000000.0` | | **`training_and_education`** | `object` |
| `946351000000.0` | | **`transport_and_warehouse`** | `object` |
| `2853511000000.0` | | **`unlisted`** | `object` |
| `6443745000000.0` | | **`warehousing_transportation_and_communication`** | `object` |
| `3000572000000.0` | | **`water_supply_waste_and_wastewater_treatments`** | `object` |
| `23526000000.0` | ### Fundamental().equity('TCB').ratio() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | -------------------------- | ------------ | ----------------------------------- | ----------- | | **`period`** | `object` | Kỳ | `2026-Q2` | | **`trailing_eps`** | `object` | Trailing eps | `3828` | | **`book_value_per_share`** | `object` | Giá trị sổ sách trên cổ phần (BVPS) | `26671` | | **`pe`** | `object` | Hệ số Giá / Lợi nhuận (P/E) | `8.75` | | **`pb`** | `object` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.26` | | **`dividend_yield`** | `object` | Tỷ suất cổ tức | `0.05` | | **`beta`** | `object` | Hệ số Beta | `1.16` | --- ## Document: Giới thiệu

Hướng dẫn này tập trung vào Unified UI - kiến trúc mới và định tuyến sử dụng mặc định của Vnstock. Nếu bạn là nhà phát triển muốn can thiệp sâu, ép nguồn hoặc tuỳ biến dữ liệu chi tiết, vui lòng tham khảo Tính Năng Nâng Cao.

# Cấu Trúc Dữ Liệu (Data Schema) Tài liệu này quy chuẩn hóa cấu trúc dữ liệu trả về cho toàn bộ hệ thống Unified UI của `vnstock_data`. Mỗi bảng dữ liệu đầu ra đều được định nghĩa đầy đủ, bao gồm tên cột, kiểu dữ liệu (`Dtype`), ý nghĩa nghiệp vụ tài chính (`Meaning`), và dữ liệu mẫu (`Sample`). > **Mục Đích**: Đóng vai trò là Cấu trúc Dữ liệu chuẩn mực, giúp các chuyên gia dữ liệu, nhà phân tích định lượng và hệ thống AI Agent dễ dàng nắm bắt định dạng của hàm để xây dựng ứng dụng hoặc tích hợp mô hình một cách chính xác. Tài liệu về cấu trúc dữ liệu được phân chia theo từng nhóm nghiệp vụ trong kiến trúc Unified UI. Vui lòng tham khảo các liên kết chi tiết dưới đây: - [**Reference**](/docs/vnstock-data/cau-truc-du-lieu/reference) - [**Market**](/docs/vnstock-data/cau-truc-du-lieu/market) - [**Fundamental**](/docs/vnstock-data/cau-truc-du-lieu/fundamental) - [**Analytics**](/docs/vnstock-data/cau-truc-du-lieu/analytics) - [**Macro**](/docs/vnstock-data/cau-truc-du-lieu/macro) - [**Insights**](/docs/vnstock-data/cau-truc-du-lieu/insights) --- ## Document: Insights ### Insights().equity('ACB').order_flow() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`match_price`** | `int64` | Giá khớp lệnh | `22350` | | **`active_buy_volume`** | `int64` | Active Buy Khối lượng | `12600` | | **`active_sell_volume`** | `int64` | Active Sell Khối lượng | `1163300` | | **`unknown_volume`** | `int64` | Khối lượng không xác định | `0` | ### Insights().equity('ACB').order_flow_history() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | | **`time`** | `object` | Thời gian giao dịch | `3/23/2026 00:00:00` | | **`outstanding_shares`** | `int64` | Cổ phiếu lưu hành | `5136656599` | | **`listed_shares`** | `int64` | Khối lượng cổ phiếu niêm yết | `5136656599` | | **`free_float`** | `int64` | Tỷ lệ cổ phiếu tự do chuyển nhượng | `4622990939` | | **`market_cap`** | `float64` | Vốn hóa thị trường | `115574.77348` | | **`reference_price`** | `int64` | Giá tham chiếu | `23000` | | **`avg_price`** | `int64` | Avg Giá | `22650` | | **`ceiling_price`** | `int64` | Giá trần | `24600` | | **`floor_price`** | `int64` | Giá sàn | `21400` | | **`open_price`** | `int64` | Giá mở cửa | `22950` | | **`close`** | `int64` | Giá đóng cửa | `22500` | | **`price_change_percent_1d`** | `int64` | Giá Change Percent 1d | `23000` | | **`close_index`** | `float64` | Close index | `1591.17` | | **`high_52w`** | `float64` | Giá cao nhất 52 tuần | `25436.79` | | **`low_52w`** | `float64` | Giá thấp nhất 52 tuần | `17339.04` | | **`foreign_held_volume`** | `int64` | Foreign Held Khối lượng | `1408392804` | | **`foreign_room`** | `int64` | Foreign room | `132604175` | | **`volume`** | `int64` | Khối lượng giao dịch | `17218400` | | **`total_value`** | `float64` | Tổng giá trị | `391968.445` | | **`put_through_volume`** | `int64` | Put Through Khối lượng | `1360000` | | **`put_through_value`** | `int64` | Giá trị giao dịch thỏa thuận | `32640000000` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `6429310` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `5125300` | | **`proprietary_buy_volume`** | `int64` | Proprietary Buy Khối lượng | `1252800` | | **`proprietary_sell_volume`** | `int64` | Proprietary Sell Khối lượng | `2453900` | | **`remain_buy_volume`** | `int64` | Remain Buy Khối lượng | `9459167` | | **`remain_sell_volume`** | `int64` | Remain Sell Khối lượng | `5332471` | | **`foreign_net_buy_volume`** | `int64` | Foreign Net Buy Khối lượng | `1304010` | | **`foreign_net_buy_value`** | `int64` | Giá trị khối ngoại mua ròng | `29725921500` | | **`proprietary_net_buy_volume`** | `int64` | Proprietary Net Buy Khối lượng | `-1201100` | | **`proprietary_net_buy_value`** | `int64` | Giá trị tự doanh mua ròng | `-27022655000` | | **`rs_1m`** | `float64` | Sức mạnh giá (RS) 1 tháng | `-5.69456` | | **`rs_3m`** | `float64` | Sức mạnh giá (RS) 3 tháng | `-10.71237` | | **`rs_1y`** | `float64` | Sức mạnh giá (RS) 1 năm | `-26.09893` | | **`avg_volume_10d`** | `int64` | Avg Khối lượng 10d | `14879180` | | **`avg_volume_5d`** | `int64` | Avg Khối lượng 5d | `13320520` | | **`avg_volume_20d`** | `int64` | Avg Khối lượng 20d | `15823500` | | **`vol_10d_vs_3m`** | `float64` | Khối lượng | `-1.26056` | | **`vol_10d_vs_6m`** | `float64` | Khối lượng | `16.51705` | | **`avg_price_5d`** | `int64` | Avg Giá 5d | `23320` | | **`avg_price_10d`** | `float64` | Avg Giá 10d | `23300.0` | | **`avg_price_20d`** | `float64` | Avg Giá 20d | `23482.5` | | **`avg_price_50d`** | `float64` | Avg Giá 50d | `23945.0` | | **`avg_price_200d`** | `float64` | Avg Giá 200d | `24285.75` | | **`bid_price`** | `object` | Bid Giá | `22500\|22450\|22400` | | **`bid_size`** | `object` | Bid size | `1005700\|374300\|171900` | | **`ask_price`** | `object` | Ask Giá | `22550\|22600\|22650` | | **`ask_size`** | `object` | Ask size | `900\|15800\|1900` | | **`daily_return`** | `float64` | Lợi nhuận hàng ngày | `-2.17395` | | **`return_mean`** | `float64` | Return mean | `0.0627` | | **`std_return`** | `float64` | Độ lệch chuẩn lợi nhuận | `1.51802` | | **`var_5percent`** | `float64` | Var 5percent | `-1.98675` | | **`adj_close_price`** | `float64` | Adj Close Giá | `19400.94` | | **`active_buy_value`** | `float64` | Giá trị mua chủ động | `192485935000.0` | | **`active_sell_value`** | `float64` | Giá trị bán chủ động | `103693495000.0` | | **`active_buy_volume`** | `float64` | Active Buy Khối lượng | `8477600.0` | | **`active_sell_volume`** | `float64` | Active Sell Khối lượng | `4576900.0` | ### Insights().equity('ACB').peer_compare() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | | **`icb_code`** | `object` | Mã chuẩn phân ngành ICB | `8350` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `8.34855` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.31793` | | **`ev_ebitda`** | `object` | Ev ebitda | None | | **`eps`** | `float64` | Thu nhập trên mỗi cổ phần (EPS) | `2701.06827` | | **`bvps`** | `float64` | Giá trị sổ sách trên mỗi cổ phần (BVPS) | `17110.14787` | | **`ebitda_per_share`** | `int64` | Ebitda per share | `0` | | **`industry_pe`** | `float64` | Industry pe | `8.64546` | | **`industry_pb`** | `float64` | Industry pb | `1.36263` | | **`industry_ev_ebitda`** | `object` | Industry ev ebitda | None | | **`market_pe`** | `float64` | Market pe | `12.71838` | | **`market_pb`** | `float64` | Market pb | `1.84131` | | **`market_ev_ebitda`** | `object` | Market ev ebitda | None | | **`related_securities`** | `object` | Related Chứng khoán | `[{'symbol': 'VPB', 'pe': 6.54599, 'pb': 1.02071, 'ev_ebitda': None}, {'symbol': 'TCB', 'pe': 7.57857, 'pb': 1.08732, 'ev_ebitda': None}, {'symbol': 'CTG', 'pe': 6.00318, 'pb': 1.21222, 'ev_ebitda': None}, {'symbol': 'BID', 'pe': 8.58567, 'pb': 1.39015, 'ev_ebitda': None}, {'symbol': 'VCB', 'pe': 12.71789, 'pb': 1.95297, 'ev_ebitda': None}]` | | **`free_cash_flow_to_equity`** | `object` | Dòng tiền tự do cho vốn chủ (FCFE) | `[{'time': '20251231', 'free_cash_flow_to_equity': None}, {'time': '20241231', 'free_cash_flow_to_equity': None}, {'time': '20231231', 'free_cash_flow_to_equity': None}, {'time': '20221231', 'free_cash_flow_to_equity': None}, {'time': '20211231', 'free_cash_flow_to_equity': None}]` | | **`sustainable_growth_rate`** | `object` | Tốc độ tăng trưởng bền vững | None | | **`cost_of_equity`** | `object` | Chi phí vốn chủ sở hữu | None | | **`outstanding_shares`** | `int64` | Cổ phiếu lưu hành | `5804421957` | | **`avg_index_return_5y`** | `float64` | Avg index return 5y | `13.62465` | | **`avg_bank_interest_12m`** | `float64` | Avg bank interest 12m | `5.9` | | **`beta_1y`** | `float64` | Hệ số Beta 1 năm | `0.9025758988` | | **`roe`** | `float64` | Tỷ suất lợi nhuận trên vốn chủ sở hữu (ROE) | `16.33136` | | **`industry_roe`** | `float64` | Industry roe | `16.98266` | | **`market_roe`** | `float64` | Market roe | `15.97531` | ### Insights().equity('ACB').rrg() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | | **`time`** | `object` | Thời gian giao dịch | `20250724` | | **`price`** | `float64` | Giá giao dịch | `20.00453` | | **`index_price`** | `float64` | Index Giá | `1521.02` | | **`rrg_rs_mid`** | `float64` | Sức mạnh tương đối trung hạn (RRG) | `0.0` | | **`rrg_rm_mid`** | `float64` | Momentum tương đối trung hạn (RRG) | `0.0` | | **`rrg_rs_standard`** | `float64` | Sức mạnh tương đối tiêu chuẩn (RRG) | `0.0` | | **`rrg_rm_standard`** | `float64` | Momentum tương đối tiêu chuẩn (RRG) | `0.0` | | **`rrg_rs_short`** | `float64` | Sức mạnh tương đối ngắn hạn (RRG) | `0.0` | | **`rrg_rm_short`** | `float64` | Momentum tương đối ngắn hạn (RRG) | `0.0` | | **`rsi_14`** | `float64` | Chỉ báo RSI | `0.0` | | **`stoch_rsi_14`** | `float64` | Chỉ báo Stochastic RSI 14 | `0.0` | | **`draw_down_status`** | `object` | Draw down status | None | | **`draw_down_value`** | `float64` | Draw Down Giá trị | `-0.01277` | ### Insights().flow.active() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`volume_1d`** | `int64` | Khối lượng 1d | `2100` | | **`value_1d`** | `int64` | Giá trị 1 ngày | `1775000` | | **`volume_10d`** | `int64` | Khối lượng 10d | `27100` | | **`value_10d`** | `int64` | Giá trị 10 ngày | `20186000` | | **`value_1m`** | `float64` | Giá trị 1 tháng | None | | **`volume_1m`** | `float64` | Khối lượng 1m | None | | **`volume_3m`** | `float64` | Khối lượng 3m | None | | **`value_3m`** | `float64` | Giá trị 3 tháng | None | | **`volume_6m`** | `float64` | Khối lượng 6m | None | | **`value_6m`** | `float64` | Giá trị 6 tháng | None | | **`status`** | `object` | Trạng thái (Ví dụ: CLOSED, OPEN) | `None` | ### Insights().flow.foreign() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `CTCB2607` | | **`volume_1d`** | `int64` | Khối lượng 1d | `0` | | **`value_1d`** | `int64` | Giá trị 1 ngày | `0` | | **`volume_10d`** | `int64` | Khối lượng 10d | `0` | | **`value_10d`** | `int64` | Giá trị 10 ngày | `0` | | **`value_1m`** | `float64` | Giá trị 1 tháng | None | | **`volume_1m`** | `float64` | Khối lượng 1m | None | | **`volume_3m`** | `float64` | Khối lượng 3m | None | | **`value_3m`** | `float64` | Giá trị 3 tháng | None | | **`volume_6m`** | `float64` | Khối lượng 6m | None | | **`value_6m`** | `float64` | Giá trị 6 tháng | None | ### Insights().flow.proprietary() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `CTCB2607` | | **`volume_1d`** | `int64` | Khối lượng 1d | `0` | | **`value_1d`** | `int64` | Giá trị 1 ngày | `0` | | **`volume_10d`** | `int64` | Khối lượng 10d | `9800` | | **`value_10d`** | `int64` | Giá trị 10 ngày | `11767000` | | **`value_1m`** | `float64` | Giá trị 1 tháng | None | | **`volume_1m`** | `float64` | Khối lượng 1m | None | | **`volume_3m`** | `float64` | Khối lượng 3m | None | | **`value_3m`** | `float64` | Giá trị 3 tháng | None | | **`volume_6m`** | `float64` | Khối lượng 6m | None | | **`value_6m`** | `float64` | Giá trị 6 tháng | None | ### Insights().ranking.deal() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ITD` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`last_price`** | `float64` | Last Giá | `14.65` | | **`last_updated`** | `object` | Thời gian / Ngày tháng | `2026-07-24 15:15` | | **`price_change_1d`** | `float64` | Giá Change 1d | `-0.15` | | **`price_change_percent_1d`** | `float64` | Giá Change Percent 1d | `-1.0135135135` | | **`total_value`** | `float64` | Tổng giá trị | `1054595000.0` | | **`deal_volume_spike_20d_percent`** | `float64` | Deal Khối lượng Spike 20d Percent | `1321.752265861` | ### Insights().ranking.foreign_buy() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `MSN` | | **`date`** | `object` | Ngày giao dịch / Dấu thời gian | `2026-05-25` | | **`net_value`** | `float64` | Net Giá trị | `145318424000.0` | ### Insights().ranking.foreign_sell() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `MSB` | | **`date`** | `object` | Ngày giao dịch / Dấu thời gian | `2026-05-25` | | **`net_value`** | `float64` | Net Giá trị | `-1483883396550.0` | ### Insights().ranking.gainer() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `HII` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`last_price`** | `float64` | Last Giá | `6.12` | | **`last_updated`** | `object` | Thời gian / Ngày tháng | `2026-07-24 15:15` | | **`price_change_1d`** | `float64` | Giá Change 1d | `0.4` | | **`price_change_percent_1d`** | `float64` | Giá Change Percent 1d | `6.993006993` | | **`total_value`** | `float64` | Tổng giá trị | `6840794000.0` | | **`avg_volume_20d`** | `float64` | Avg Khối lượng 20d | `172165.1` | | **`volume_spike_20d_percent`** | `float64` | Khối lượng Spike 20d Percent | `651.2353549006` | ### Insights().ranking.loser() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACC` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`last_price`** | `float64` | Last Giá | `5.21` | | **`last_updated`** | `object` | Thời gian / Ngày tháng | `2026-07-24 15:15` | | **`price_change_1d`** | `float64` | Giá Change 1d | `-0.39` | | **`price_change_percent_1d`** | `float64` | Giá Change Percent 1d | `-6.9642857143` | | **`total_value`** | `float64` | Tổng giá trị | `108368000.0` | ### Insights().ranking.value() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `PNJ` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`last_price`** | `float64` | Last Giá | `30.75` | | **`last_updated`** | `object` | Thời gian / Ngày tháng | `2026-07-24 15:15` | | **`price_change_1d`** | `float64` | Giá Change 1d | `-2.3` | | **`price_change_percent_1d`** | `float64` | Giá Change Percent 1d | `-6.9591527988` | | **`total_value`** | `float64` | Tổng giá trị | `1271818560000.0` | ### Insights().ranking.volume() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ITD` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`last_price`** | `float64` | Last Giá | `14.65` | | **`last_updated`** | `object` | Thời gian / Ngày tháng | `2026-07-24 15:15` | | **`price_change_1d`** | `float64` | Giá Change 1d | `-0.15` | | **`price_change_percent_1d`** | `float64` | Giá Change Percent 1d | `-1.0135135135` | | **`total_value`** | `float64` | Tổng giá trị | `1054595000.0` | | **`avg_volume_20d`** | `float64` | Avg Khối lượng 20d | `11447.8` | | **`volume_spike_20d_percent`** | `float64` | Khối lượng Spike 20d Percent | `653.4006534007` | ### Insights().screener.criteria() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`category`** | `object` | Phân loại | `general` | | **`field_name`** | `object` | Tên trường | `sectorLv1` | | **`column_name`** | `object` | Tên cột | `sector_lv1` | | **`readable_name`** | `object` | Tên hiển thị | `sectorLv1` | | **`select_type`** | `object` | Select type | `multiple` | ### Insights().screener.filter() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `DVP` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `float64` | Giá tham chiếu | `74500.0` | | **`ceiling_price`** | `float64` | Giá trần | `79700.0` | | **`price`** | `float64` | Giá giao dịch | `75300.0` | | **`floor_price`** | `float64` | Giá sàn | `69300.0` | | **`accumulated_value`** | `float64` | Accumulated Giá trị | `736060000.0` | | **`accumulated_volume`** | `float64` | Accumulated Khối lượng | `9800.0` | | **`market_cap`** | `float64` | Vốn hóa thị trường | `3012000000000.0` | | **`price_change_percent`** | `float64` | Giá Change Percent | `1.0738255` | | **`avg_value_30d`** | `float64` | TB giá trị 30 ngày | `737879526.6666666` | | **`avg_value_10d`** | `float64` | TB giá trị 10 ngày | `-33.51568602` | | **`avg_volume_30d`** | `float64` | Avg Khối lượng 30d | `10216.1666666667` | | **`est_volume`** | `float64` | Est Khối lượng | `9117.1105434` | | **`volume_breakout_30d`** | `float64` | Khối lượng Breakout 30d | `-10.75800894` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `8.1787874153` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `2.3554950846` | | **`roe`** | `float64` | Tỷ suất lợi nhuận trên vốn chủ sở hữu (ROE) | `26.03136692` | | **`profit_growth_yoy`** | `float64` | Tăng trưởng lợi nhuận (YoY) | `42.21078203` | | **`revenue_growth_yoy`** | `float64` | Tăng trưởng doanh thu (YoY) | `22.74696655` | | **`net_margin`** | `float64` | Biên lợi nhuận ròng (%) | `59.24466909` | | **`gross_margin`** | `float64` | Biên lợi nhuận gộp (%) | `56.82777358` | | **`match_price_time`** | `object` | Match Giá Time | `2026-07-24T08:19:06.909` | | **`rs_3m`** | `int64` | Sức mạnh giá (RS) 3 tháng | `83` | | **`ema_time`** | `object` | Thời gian / Ngày tháng | `1784764800` | | **`ema_20`** | `float64` | Đường trung bình hàm mũ (EMA) 20 | `72854.268350489` | | **`price_ema_20`** | `float64` | Giá Ema 20 | `3.35701903` | | **`ema_20_ema_50`** | `float64` | Độ lệch EMA 20 và EMA 50 | `1.9062055` | | **`ema_50_ema_200`** | `float64` | Độ lệch EMA 50 và EMA 200 | `3.94712912` | | **`macd_signal`** | `float64` | Đường tín hiệu MACD | `736.5301647343` | | **`macd`** | `float64` | Chỉ báo MACD | `1033.340275072` | | **`histogram`** | `float64` | Biểu đồ Histogram | `296.8101103377` | | **`outperforms_index_3m`** | `float64` | Hiệu suất vượt trội chỉ số (3 tháng) | `17.95213632` | | **`price_return_3m`** | `float64` | Giá Return 3m | `8.93142181` | | **`price_fluctuation_30d`** | `float64` | Giá Fluctuation 30d | `7.26495726` | | **`prev_rsi`** | `object` | Prev rsi | `{'avgGain': 250.5903361201, 'avgLoss': 75.899474676, 'rsi': 76.7528810498, 'closePrice': 74500.0, 'latestDay': True}` | | **`rsi`** | `float64` | Chỉ báo RSI | `80.4397050196` | | **`last_modified_date`** | `object` | Last Modified Ngày | `2026-07-24T08:22:51.465` | | **`company_name_en`** | `object` | Tên công ty (Tiếng Anh) | `Dinh Vu Port Investment & Development Joint Stock Company` | | **`short_name_en`** | `object` | Tên viết tắt (Tiếng Anh) | `Dinh Vu Port Investment` | | **`company_name`** | `object` | Tên công ty | `Công ty Cổ phần Đầu tư và Phát triển Cảng Đình Vũ` | | **`short_name`** | `object` | Tên viết tắt | `ĐT và PT Cảng Đình Vũ` | | **`icb_code2`** | `object` | Mã phân ngành ICB cấp 2 | `2700` | | **`industry_en`** | `object` | Ngành nghề (Tiếng Anh) | `Industrial Goods & Services` | | **`vi_sector`** | `object` | Vi sector | `Hàng & Dịch vụ Công nghiệp` | | **`icb_code4`** | `object` | Icb code4 | `2777` | | **`stock_strength`** | `int64` | Sức mạnh cổ phiếu | `88` | | **`stock_trend`** | `object` | Xu hướng cổ phiếu | `STRONG_UPTREND` | | **`adx`** | `float64` | Chỉ báo sức mạnh xu hướng (ADX) | `36.3375328276` | | **`ao`** | `float64` | Chỉ báo Awesome Oscillator (AO) | `2620.8823529412` | | **`ao_trend`** | `object` | Xu hướng AO | `ABOVE_ZERO` | ### Insights().sector('bank').flow_intraday() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-06-28T09:00:00.000` | | **`net_active_buy_value`** | `int64` | Giá trị mua chủ động ròng | `1240000` | ### Insights().sector('bank').index_intraday() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-06-28T09:00:00.000` | | **`index_value`** | `float64` | Index Giá trị | `368.32538` | ### Insights().sector('bank').members() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ABB` | | **`company_name`** | `object` | Tên công ty | `ABBank` | | **`company_name_en`** | `object` | Tên công ty (Tiếng Anh) | `ABBank` | | **`reference_price`** | `int64` | Giá tham chiếu | `16900` | | **`floor_price`** | `int64` | Giá sàn | `14400` | | **`ceiling_price`** | `int64` | Giá trần | `19400` | | **`percent_change`** | `float64` | Biến động giá (%) | `2.36686` | | **`total_value`** | `float64` | Tổng giá trị | `12122524600.0` | | **`market_cap`** | `int64` | Vốn hóa thị trường | `27797000000000` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `6.83001` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.23012` | | **`eps`** | `float64` | Thu nhập trên mỗi cổ phần (EPS) | None | | **`bvps`** | `float64` | Giá trị sổ sách trên mỗi cổ phần (BVPS) | None | | **`beta`** | `float64` | Hệ số Beta | `0.47257` | | **`dividend_yield`** | `float64` | Tỷ suất cổ tức | None | | **`roe`** | `float64` | Tỷ suất lợi nhuận trên vốn chủ sở hữu (ROE) | `21.252` | | **`roa`** | `float64` | Tỷ suất lợi nhuận trên tổng tài sản (ROA) | `1.661` | | **`eps_growth`** | `float64` | Tăng trưởng EPS (%) | `164.957` | | **`revenue_growth`** | `float64` | Tăng trưởng doanh thu (%) | `58.672` | | **`total_equity`** | `float64` | Tổng vốn chủ sở hữu | None | | **`total_assets`** | `int64` | Tổng tài sản | `260563000000000` | ### Insights().sector('bank').rrg() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-25T00:00:00.000` | | **`index_price`** | `float64` | Index Giá | `1531.13` | | **`rsi_14`** | `float64` | Chỉ báo RSI | `0.0` | | **`stoch_rsi_14`** | `float64` | Chỉ báo Stochastic RSI 14 | `0.0` | ### Insights().sentiment.breadth() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2023-07-26T00:00:00.000` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `12.23072` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.4339` | | **`position_line`** | `float64` | Position line | `0.48346` | ### Insights().sentiment.contribution() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `BSR` | | **`value`** | `float64` | Giá trị giao dịch | `0.04024` | | **`point`** | `float64` | Điểm số | `0.68383` | | **`type`** | `object` | Loại hình (Ví dụ: corporate, STOCK) | `up` | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-24T00:00:00.000` | ### Insights().sentiment.heatmap() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `CTCB2607` | | **`icb_code`** | `object` | Mã chuẩn phân ngành ICB | | | **`market_cap`** | `float64` | Vốn hóa thị trường | `0.0` | | **`price_change`** | `float64` | Biến động giá | `-0.1` | | **`price_change_status`** | `object` | Giá Change Status | `D` | | **`volume_1d`** | `float64` | Khối lượng 1d | `2100.0` | | **`value_1d`** | `float64` | Giá trị 1 ngày | `1775000.0` | | **`volume_10d`** | `float64` | Khối lượng 10d | `125400.0` | | **`value_10d`** | `float64` | Giá trị 10 ngày | `133399000.0` | | **`value_1m`** | `float64` | Giá trị 1 tháng | None | | **`volume_1m`** | `float64` | Khối lượng 1m | None | --- ## Document: Macro ### Macro().commodity().corn() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `419.0` | | **`high`** | `float64` | Giá cao nhất | `419.75` | | **`low`** | `float64` | Giá thấp nhất | `412.75` | | **`close`** | `float64` | Giá đóng cửa | `414.0` | | **`volume`** | `int64` | Khối lượng giao dịch | `160905` | ### Macro().commodity().fertilizer_ure() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `467.75` | | **`high`** | `float64` | Giá cao nhất | `467.75` | | **`low`** | `float64` | Giá thấp nhất | `467.75` | | **`close`** | `float64` | Giá đóng cửa | `467.75` | | **`volume`** | `float64` | Khối lượng giao dịch | `0.0` | ### Macro().commodity().gas() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-26T00:00:00.000` | | **`ron95`** | `float64` | Ron95 | None | | **`ron92`** | `float64` | Ron92 | `19.27` | | **`oil_do`** | `float64` | Oil do | None | ### Macro().commodity().gold() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`buy`** | `float64` | Mua | `119600.0` | | **`sell`** | `float64` | Bán | `121100.0` | ### Macro().commodity().listing() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`item_id`** | `object` | ID khoản mục | `3938` | | **`commo_type`** | `object` | Loại hàng hóa | `01` | | **`commo_name_vn`** | `object` | Tên hàng hóa (Tiếng Việt) | `Dầu WTI ` | | **`commo_name_en`** | `object` | Tên hàng hóa (Tiếng Anh) | `Crude Oil WTI` | | **`commo_desc_vn`** | `object` | Mô tả hàng hóa (Tiếng Việt) | `Hợp Đồng Tương Lai Dầu Thô WTI` | | **`commo_desc_en`** | `object` | Mô tả hàng hóa (Tiếng Anh) | `Crude Oil WTI Futures ` | | **`commo_unit`** | `object` | Đơn vị tính hàng hóa | `USD` | | **`item_code`** | `object` | Mã khoản mục | `COM_CMICET` | | **`close_value`** | `object` | Close Giá trị | `85.1500015258789` | | **`diff_value`** | `object` | Diff Giá trị | `-1.86` | ### Macro().commodity().oil_crude() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-27T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `65.18` | | **`high`** | `float64` | Giá cao nhất | `65.34` | | **`low`** | `float64` | Giá thấp nhất | `65.1` | | **`close`** | `float64` | Giá đóng cửa | `65.29` | | **`volume`** | `int64` | Khối lượng giao dịch | `2764` | ### Macro().commodity().pork() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-27T00:00:00.000` | | **`close`** | `float64` | Giá đóng cửa | `60900.0` | ### Macro().commodity().soybean() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `998.0` | | **`high`** | `float64` | Giá cao nhất | `999.5` | | **`low`** | `float64` | Giá thấp nhất | `991.0` | | **`close`** | `float64` | Giá đóng cửa | `992.5` | | **`volume`** | `int64` | Khối lượng giao dịch | `51995` | ### Macro().commodity().steel() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `int64` | Giá mở cửa | `873` | | **`high`** | `int64` | Giá cao nhất | `873` | | **`low`** | `int64` | Giá thấp nhất | `873` | | **`close`** | `int64` | Giá đóng cửa | `873` | | **`volume`** | `int64` | Khối lượng giao dịch | `0` | ### Macro().commodity().sugar() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `470.9` | | **`high`** | `float64` | Giá cao nhất | `476.4` | | **`low`** | `float64` | Giá thấp nhất | `469.0` | | **`close`** | `float64` | Giá đóng cửa | `474.8` | | **`volume`** | `int64` | Khối lượng giao dịch | `8078` | ### Macro().currency().deposit_rate() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`bank_code`** | `object` | Mã ngân hàng | `ABB` | | **`bank_name`** | `object` | Tên ngân hàng | `ABBank` | | **`bank_name_en`** | `object` | Tên ngân hàng (EN) | `ABBank` | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-03T00:00:00.000` | | **`interest_1m`** | `float64` | Interest 1m | `3.6` | | **`interest_3m`** | `float64` | Interest 3m | `3.8` | | **`interest_6m`** | `float64` | Interest 6m | `6.05` | | **`interest_13m`** | `float64` | Interest 13m | `6.05` | | **`interest_36m`** | `float64` | Interest 36m | `5.6` | ### Macro().currency().exchange_rate() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2020-01-02T00:00:00.000` | | **`center_rate`** | `float64` | Center Tỷ lệ/Lãi suất | `23150.0` | | **`vcb_rate`** | `float64` | Lãi suất Vietcombank | None | | **`market_rate`** | `int64` | Lãi suất thị trường liên ngân hàng | `23180` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | `966.67` | ### Macro().currency().interest_rate() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`report_time`** | `datetime64[ns]` | Thời gian / Ngày tháng | `2026-04-01T00:00:00.000` | | **`time`** | `object` | Thời gian giao dịch | `2026-03-31T00:00:00.000` | | **`group_name`** | `object` | Tên nhóm | `Doanh số` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Qua đêm` | | **`value`** | `float64` | Giá trị giao dịch | `800145.0` | | **`unit`** | `object` | Đơn vị | `Tỷ VNĐ` | | **`source`** | `object` | Nguồn dữ liệu | `Ngân hàng Nhà nước Việt Nam` | ### Macro().currency().omo() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2016-01-11T00:00:00.000` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | `557.87` | | **`inflow_amount`** | `float64` | Inflow amount | `1300.0` | | **`outflow_amount`** | `float64` | Outflow amount | `3182.0` | | **`netflow_amount`** | `float64` | Netflow amount | `-1882.0` | | **`cumulative_flow_amount`** | `float64` | Cumulative flow amount | `-1882.0` | ### Macro().currency().policy_rate() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2021-01-04T00:00:00.000` | | **`refinance`** | `float64` | Lãi suất tái cấp vốn | `4.0` | | **`discount`** | `float64` | Lãi suất chiết khấu | `2.5` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | `1120.47` | ### Macro().economy().cpi() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2016-01-31T00:00:00.000` | | **`cpi_total`** | `float64` | Chỉ số giá tiêu dùng (CPI) tổng hợp | `0.8` | | **`cpi_core`** | `float64` | Chỉ số giá tiêu dùng (CPI) cơ bản | `1.72` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | `545.25` | ### Macro().economy().credit() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2014-03-31T00:00:00.000` | | **`credit_growth`** | `float64` | Tăng trưởng tín dụng | None | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | None | ### Macro().economy().fdi() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2014-01-31T00:00:00.000` | | **`register_value`** | `float64` | Register Giá trị | `397.15` | | **`realized_value`** | `int64` | Realized Giá trị | `465` | | **`realized_percent`** | `float64` | Realized percent | `117.08423` | ### Macro().economy().gdp() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2015-03-31T00:00:00.000` | | **`agriculture`** | `float64` | Nông nghiệp | None | | **`industry`** | `float64` | Ngành nghề | None | | **`services`** | `float64` | Services | None | | **`tax`** | `float64` | Tax | None | | **`gdp`** | `float64` | Tổng sản phẩm quốc nội (GDP) | None | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | None | ### Macro().economy().import_export() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2014-01-31T00:00:00.000` | | **`export_value`** | `float64` | Giá trị xuất khẩu | `10300.0` | | **`import_value`** | `float64` | Giá trị nhập khẩu | `10400.0` | | **`balance_value`** | `float64` | Balance Giá trị | `-100.0` | | **`export_growth`** | `float64` | Tăng trưởng xuất khẩu | `0.0` | | **`import_growth`** | `float64` | Tăng trưởng nhập khẩu | `0.0` | | **`vnindex`** | `int64` | Chỉ số VN-INDEX | `0` | ### Macro().economy().industry_prod() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`report_time`** | `object` | Thời gian / Ngày tháng | `2016-07-31T00:00:00.000` | | **`time`** | `object` | Thời gian giao dịch | `2016-07-31T00:00:00.000` | | **`group_name`** | `object` | Tên nhóm | `Tăng trưởng` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Toàn ngành công nghiệp` | | **`value`** | `float64` | Giá trị giao dịch | `2.1` | | **`unit`** | `object` | Đơn vị | `%` | | **`source`** | `object` | Nguồn dữ liệu | None | ### Macro().economy().money_supply() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2016-03-31T00:00:00.000` | | **`total`** | `int64` | Tổng cộng | `6267958` | | **`institutional`** | `float64` | Institutional | `2102752.0` | | **`private`** | `float64` | Tư nhân | `3206498.0` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | `561.22` | ### Macro().economy().population_labor() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`report_time`** | `object` | Thời gian / Ngày tháng | `2016` | | **`time`** | `object` | Thời gian giao dịch | `2017-01-03T00:00:00.000` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Số lượng lao động` | | **`value`** | `float64` | Giá trị giao dịch | `53.29` | | **`unit`** | `object` | Đơn vị | `Triệu người` | | **`source`** | `object` | Nguồn dữ liệu | `ADB` | ### Macro().economy().retail() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`report_time`** | `object` | Thời gian / Ngày tháng | `2016-07-31T00:00:00.000` | | **`time`** | `object` | Thời gian giao dịch | `2016-07-31T00:00:00.000` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `TỔNG SỐ:` | | **`value`** | `float64` | Giá trị giao dịch | `295690.8` | | **`unit`** | `object` | Đơn vị | `Tỷ VNĐ` | | **`source`** | `object` | Nguồn dữ liệu | `Tổng cục thống kê` | ### Macro().economy().state_budget() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2013-03-31T00:00:00.000` | | **`budget_in`** | `int64` | Thu ngân sách | `167709880` | | **`budget_out`** | `int64` | Chi ngân sách | `204785` | | **`budget_net`** | `int64` | Cân đối ngân sách | `-37075120` | ### Macro().economy().total_investment() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2014-03-31T00:00:00.000` | | **`public`** | `float64` | Đại chúng | `76.13` | | **`private`** | `float64` | Tư nhân | None | | **`fdi`** | `float64` | Vốn đầu tư trực tiếp nước ngoài (FDI) | `58.9` | | **`other`** | `float64` | Khác | `2.3` | | **`vnindex`** | `float64` | Chỉ số VN-INDEX | None | ### getattr(Macro(), 'global').bond_yield() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `3.43` | | **`high`** | `float64` | Giá cao nhất | `3.43` | | **`low`** | `float64` | Giá thấp nhất | `3.43` | | **`close`** | `float64` | Giá đóng cửa | `3.43` | | **`volume`** | `int64` | Khối lượng giao dịch | `0` | ### getattr(Macro(), 'global').fed_rate() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-08-01T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `4.33` | | **`high`** | `float64` | Giá cao nhất | `4.33` | | **`low`** | `float64` | Giá thấp nhất | `4.33` | | **`close`** | `float64` | Giá đóng cửa | `4.33` | | **`volume`** | `int64` | Khối lượng giao dịch | `0` | ### getattr(Macro(), 'global').index() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-27T00:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `97.57` | | **`high`** | `float64` | Giá cao nhất | `97.64` | | **`low`** | `float64` | Giá thấp nhất | `97.53` | | **`close`** | `float64` | Giá đóng cửa | `97.61` | | **`volume`** | `int64` | Khối lượng giao dịch | `0` | --- ## Document: Market ### Market().equity('TCB').foreign_flow() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-24T00:00:00.000` | | **`buy_vol`** | `float64` | Khối lượng mua | `1655531.0` | | **`buy_val`** | `float64` | Giá trị mua | `47666981250.0` | | **`sell_vol`** | `float64` | Khối lượng bán | `4292400.0` | | **`sell_val`** | `float64` | Giá trị bán | `123751680000.0` | | **`net_vol`** | `float64` | Khối lượng ròng | `-2636869.0` | | **`net_val`** | `float64` | Giá trị ròng | `-76084698750.0` | ### Market().equity('TCB').history(length='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T07:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `33.63` | | **`high`** | `float64` | Giá cao nhất | `34.21` | | **`low`** | `float64` | Giá thấp nhất | `33.59` | | **`close`** | `float64` | Giá đóng cửa | `33.97` | | **`volume`** | `int64` | Khối lượng giao dịch | `30577800` | ### Market().equity('TCB').intraday() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`index`** | `int64` | Mã chỉ số | `999` | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-24T13:51:07.000` | | **`price`** | `float64` | Giá giao dịch | `28.95` | | **`volume`** | `int64` | Khối lượng giao dịch | `200` | | **`match_type`** | `object` | Loại lệnh khớp (Buy/Sell) | `Buy` | | **`id`** | `object` | Mã ID hệ thống | `2026-07-24_135107_289500_200` | ### Market().equity('TCB').matched_by_price() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`price`** | `int64` | Giá giao dịch | `28500` | | **`buy_volume`** | `int64` | Khối lượng mua | `15500` | | **`sell_volume`** | `int64` | Khối lượng bán | `93100` | | **`unknown_volume`** | `int64` | Khối lượng không xác định | `0` | | **`total_volume`** | `int64` | Tổng khối lượng | `108600` | ### Market().equity('TCB').odd_lot() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `29250` | | **`high_price`** | `int64` | Giá cao nhất | `29400` | | **`low_price`** | `int64` | Giá thấp nhất | `28600` | | **`match_price`** | `int64` | Giá khớp lệnh | `28800` | | **`match_vol`** | `int64` | Khối lượng khớp lệnh | `12` | | **`total_volume`** | `int64` | Tổng khối lượng | `13249` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28800.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `1815` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28750` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `1308` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28700` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `1971` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28850.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `99` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `29000` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `13` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `29100` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `1` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `0` | ### Market().equity('TCB').ohlcv(length='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T07:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `33.63` | | **`high`** | `float64` | Giá cao nhất | `34.21` | | **`low`** | `float64` | Giá thấp nhất | `33.59` | | **`close`** | `float64` | Giá đóng cửa | `33.97` | | **`volume`** | `int64` | Khối lượng giao dịch | `30577800` | ### Market().equity('TCB').order_book() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | ### Market().equity('TCB').price_board() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `28900` | | **`high_price`** | `int64` | Giá cao nhất | `29200` | | **`low_price`** | `int64` | Giá thấp nhất | `28500` | | **`close_price`** | `int64` | Giá đóng cửa | `28600` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `4292400` | ### Market().equity('TCB').price_depth() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | ### Market().equity('TCB').proprietary_flow() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-24T00:00:00.000` | | **`buy_vol`** | `float64` | Khối lượng mua | `2156600.0` | | **`buy_val`** | `float64` | Giá trị mua | `62179195000.0` | | **`sell_vol`** | `float64` | Khối lượng bán | `2976400.0` | | **`sell_val`** | `float64` | Giá trị bán | `85667165000.0` | | **`net_vol`** | `float64` | Khối lượng ròng | `-819800.0` | | **`net_val`** | `float64` | Giá trị ròng | `-23487970000.0` | ### Market().equity('TCB').quote() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `28900` | | **`high_price`** | `int64` | Giá cao nhất | `29200` | | **`low_price`** | `int64` | Giá thấp nhất | `28500` | | **`close_price`** | `int64` | Giá đóng cửa | `28600` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `4292400` | ### Market().equity('TCB').session_stats() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`average_match_volume`** | `float64` | Trung bình KL khớp lệnh | `8927028.728255529` | | **`average_match_value`** | `float64` | Trung bình GT khớp lệnh | `312600000553.7346` | | **`average_deal_volume`** | `float64` | Trung bình KL thỏa thuận | `2853441.062899263` | | **`average_deal_value`** | `float64` | Trung bình GT thỏa thuận | `87868547666.69681` | | **`average_volume`** | `float64` | Khối lượng trung bình | `11780469.79115479` | | **`average_value`** | `float64` | Giá trị trung bình | `400468548220.43146` | | **`total_match_volume`** | `float64` | Tổng khối lượng khớp lệnh | `18166503462.0` | | **`total_match_value`** | `float64` | Tổng giá trị khớp lệnh | `636141001126850.0` | | **`total_deal_volume`** | `float64` | Tổng khối lượng thỏa thuận | `5806752563.0` | | **`total_deal_value`** | `float64` | Tổng giá trị thỏa thuận | `178812494501728.0` | | **`total_volume`** | `float64` | Tổng khối lượng | `23973256025.0` | | **`total_value`** | `float64` | Tổng giá trị | `814953495628578.0` | | **`fr_buy_volume_total`** | `float64` | Tổng KL khối ngoại mua | `1787901938.0` | | **`fr_buy_value_total`** | `float64` | Tổng GT khối ngoại mua | `56211301699998.0` | | **`fr_sell_volume_total`** | `float64` | Tổng KL khối ngoại bán | `1873995282.0` | | **`fr_sell_value_total`** | `float64` | Tổng GT khối ngoại bán | `59270092237248.0` | | **`fr_net_volume_total`** | `float64` | KL ròng khối ngoại | `-86093344.0` | | **`fr_net_value_total`** | `float64` | GT ròng khối ngoại | `-3058790537250.0` | | **`fr_buy_volume_matched`** | `float64` | KL khớp lệnh khối ngoại mua | `564003306.0` | | **`fr_buy_value_matched`** | `float64` | GT khớp lệnh khối ngoại mua | `16711447532400.0` | | **`fr_sell_volume_matched`** | `float64` | KL khớp lệnh khối ngoại bán | `673562536.0` | | **`fr_sell_value_matched`** | `float64` | GT khớp lệnh khối ngoại bán | `20470531031850.0` | | **`fr_buy_volume_deal`** | `float64` | KL thỏa thuận khối ngoại mua | `1223898632.0` | | **`fr_buy_value_deal`** | `float64` | GT thỏa thuận khối ngoại mua | `39499854167598.0` | | **`fr_sell_volume_deal`** | `float64` | KL thỏa thuận khối ngoại bán | `1200432794.0` | | **`fr_sell_value_deal`** | `float64` | GT thỏa thuận khối ngoại bán | `38799562583748.0` | | **`fr_buy_volume_total_avg`** | `float64` | TB tổng KL khối ngoại mua | `878575.8909090909` | | **`fr_buy_value_total_avg`** | `float64` | TB tổng GT khối ngoại mua | `27622261277.640293` | | **`fr_sell_volume_total_avg`** | `float64` | TB tổng KL khối ngoại bán | `920882.2024570025` | | **`fr_sell_value_total_avg`** | `float64` | TB tổng GT khối ngoại bán | `29125352450.73612` | | **`fr_net_volume_total_avg`** | `float64` | Trung bình KL ròng khối ngoại | `-42306.3115479116` | | **`fr_net_value_total_avg`** | `float64` | Trung bình GT ròng khối ngoại | `-1503091173.095827` | | **`fr_buy_volume_matched_avg`** | `float64` | TB KL khớp lệnh khối ngoại mua | `277151.5017199017` | | **`fr_buy_value_matched_avg`** | `float64` | TB GT khớp lệnh khối ngoại mua | `8212013529.43489` | | **`fr_sell_volume_matched_avg`** | `float64` | TB KL khớp lệnh khối ngoại bán | `330988.9611793612` | | **`fr_sell_value_matched_avg`** | `float64` | TB GT khớp lệnh khối ngoại bán | `10059229008.280098` | | **`fr_buy_volume_deal_avg`** | `float64` | TB KL thỏa thuận khối ngoại mua | `601424.3891891892` | | **`fr_buy_value_deal_avg`** | `float64` | TB GT thỏa thuận khối ngoại mua | `19410247748.205406` | | **`fr_sell_volume_deal_avg`** | `float64` | TB KL thỏa thuận khối ngoại bán | `589893.2648648649` | | **`fr_sell_value_deal_avg`** | `float64` | TB GT thỏa thuận khối ngoại bán | `19066124119.777885` | | **`fr_net_volume_matched`** | `float64` | KL khớp lệnh ròng khối ngoại | `-109559230.0` | | **`fr_net_value_matched`** | `float64` | GT khớp lệnh ròng khối ngoại | `-3759083499450.0` | | **`fr_net_volume_matched_avg`** | `float64` | TB KL khớp lệnh ròng khối ngoại | `-53837.4594594594` | | **`fr_net_value_matched_avg`** | `float64` | TB GT khớp lệnh ròng khối ngoại | `-1847215478.845208` | | **`fr_net_volume_deal`** | `float64` | KL thỏa thuận ròng khối ngoại | `23465838.0` | | **`fr_net_value_deal`** | `float64` | GT thỏa thuận ròng khối ngoại | `700291583850.0` | | **`fr_net_volume_deal_avg`** | `float64` | TB KL thỏa thuận ròng khối ngoại | `11531.1243243243` | | **`fr_net_value_deal_avg`** | `float64` | TB GT thỏa thuận ròng khối ngoại | `344123628.427521` | | **`total_buy_trade_volume`** | `float64` | Tổng khối lượng lệnh mua | `31400494665.0` | | **`total_sell_trade_volume`** | `float64` | Tổng khối lượng lệnh bán | `32564549439.0` | | **`total_buy_trade_volume_avg`** | `float64` | TB khối lượng lệnh mua | `15430218.508599509` | | **`total_sell_trade_volume_avg`** | `float64` | TB khối lượng lệnh bán | `16002235.596560197` | | **`total_buy_trade`** | `float64` | Tổng số lệnh mua | `10383400.0` | | **`total_sell_trade`** | `float64` | Tổng số lệnh bán | `8452946.0` | | **`total_buy_trade_avg`** | `float64` | | `5102.4078624079` | | **`total_sell_trade_avg`** | `float64` | | `4153.7818181818` | | **`total_buy_unmatched_volume_avg`** | `float64` | TB khối lượng mua chưa khớp | `6503189.78034398` | | **`total_sell_unmatched_volume_avg`** | `float64` | TB khối lượng bán chưa khớp | `7075206.868304668` | | **`total_net_trade_volume`** | `float64` | Tổng KL giao dịch ròng | `-1164054774.0` | | **`total_net_trade_volume_avg`** | `float64` | | `-572017.087960688` | | **`total_buy_unmatched_volume`** | `float64` | Tổng khối lượng mua chưa khớp | `13233991203.0` | | **`total_sell_unmatched_volume`** | `float64` | Tổng khối lượng bán chưa khớp | `14398045977.0` | | **`average_buy_volume_per_trade`** | `float64` | | `3024.1052704317` | | **`average_sell_volume_per_trade`** | `float64` | | `3852.4497185952` | ### Market().equity('TCB').summary() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`high_52w`** | `int64` | Giá cao nhất 52 tuần | `40450` | | **`low_52w`** | `int64` | Giá thấp nhất 52 tuần | `28109` | | **`dividend`** | `int64` | Cổ tức | `1700` | | **`beta`** | `float64` | Hệ số Beta | `0.97` | | **`eps`** | `int64` | Thu nhập trên mỗi cổ phần (EPS) | `3828` | | **`bvps`** | `int64` | Giá trị sổ sách trên mỗi cổ phần (BVPS) | `26671` | | **`market_cap`** | `int64` | Vốn hóa thị trường | `202666475840400` | | **`pe`** | `object` | Hệ số Giá / Lợi nhuận (P/E) | `7.64` | | **`pb`** | `object` | Hệ số Giá / Giá trị sổ sách (P/B) | `1.10` | | **`roe`** | `float64` | Tỷ suất lợi nhuận trên vốn chủ sở hữu (ROE) | `15.85` | | **`change_1m`** | `object` | Biến động giá 1 tháng (%) | `-14.37` | | **`change_1y`** | `object` | Biến động giá 1 năm (%) | `-14.85` | | **`dividend_yield`** | `float64` | Tỷ suất cổ tức | `0.0594405594` | | **`foreign_ownership_pct`** | `float64` | Tỷ lệ sở hữu nước ngoài (%) | `21.336` | ### Market().equity('TCB').trade_history() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`trading_date`** | `datetime64[ns]` | Ngày giao dịch | `2026-07-24T00:00:00.000` | | **`end_trading_date`** | `object` | Ngày kết thúc giao dịch | `2026-07-24T00:00:00` | | **`market_cap`** | `float64` | Vốn hóa thị trường | `202666475840400.0` | | **`total_shares`** | `float64` | Tổng số cổ phần nắm giữ | `7086240414.0` | | **`ceiling_price`** | `float64` | Giá trần | `31250.0` | | **`floor_price`** | `float64` | Giá sàn | `27250.0` | | **`reference_price`** | `float64` | Giá tham chiếu | `29250.0` | | **`open`** | `float64` | Giá mở cửa | `28900.0` | | **`close`** | `float64` | Giá đóng cửa | `28600.0` | | **`match_price`** | `float64` | Giá khớp lệnh | `28600.0` | | **`price_change`** | `float64` | Biến động giá | `-650.0` | | **`percent_price_change`** | `float64` | Biến động giá (%) | `-0.02222222` | | **`high`** | `float64` | Giá cao nhất | `29200.0` | | **`low`** | `float64` | Giá thấp nhất | `28500.0` | | **`average_price`** | `float64` | Giá trung bình | `28792.0126927937` | | **`average_price_adjusted`** | `float64` | | `28792.0126927937` | | **`matched_volume`** | `float64` | Khối lượng khớp lệnh | `10708349.0` | | **`matched_value`** | `float64` | Giá trị khớp lệnh | `308334961850.0` | | **`deal_volume`** | `float64` | Khối lượng thỏa thuận | `120000.0` | | **`deal_value`** | `float64` | Giá trị thỏa thuận | `3435000000.0` | | **`total_volume`** | `float64` | Tổng khối lượng | `10828349.0` | | **`total_value`** | `float64` | Tổng giá trị | `311769961850.0` | | **`total_buy_trade`** | `float64` | Tổng số lệnh mua | `9145.0` | | **`total_buy_trade_volume`** | `float64` | Tổng khối lượng lệnh mua | `15760419.0` | | **`total_sell_trade`** | `float64` | Tổng số lệnh bán | `6072.0` | | **`total_sell_trade_volume`** | `float64` | Tổng khối lượng lệnh bán | `14080083.0` | | **`reference_price_adjusted`** | `float64` | Giá tham chiếu điều chỉnh | `29250.0` | | **`open_price_adjusted`** | `float64` | Giá mở cửa điều chỉnh | `28900.0` | | **`close_price_adjusted`** | `float64` | Giá đóng cửa điều chỉnh | `28600.0` | | **`price_change_adjusted`** | `float64` | Biến động giá điều chỉnh | `-650.0` | | **`percent_price_change_adjusted`** | `float64` | Biến động giá điều chỉnh (%) | `-0.02222222` | | **`highest_price_adjusted`** | `float64` | Giá cao nhất điều chỉnh | `29200.0` | | **`lowest_price_adjusted`** | `float64` | Giá thấp nhất điều chỉnh | `28500.0` | | **`total_net_trade_volume`** | `float64` | Tổng KL giao dịch ròng | `1680336.0` | | **`total_buy_unmatched_volume`** | `float64` | Tổng khối lượng mua chưa khớp | `5052070.0` | | **`total_sell_unmatched_volume`** | `float64` | Tổng khối lượng bán chưa khớp | `3371734.0` | | **`price_change_value`** | `object` | Giá trị biến động | `-650 (-2.2%)` | | **`average_buy_trade_volume`** | `float64` | Trung bình KL mỗi lệnh mua | `1723.3919081465` | | **`average_sell_trade_volume`** | `float64` | Trung bình KL mỗi lệnh bán | `2318.8542490119` | ### Market().equity('TCB').trades() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`index`** | `int64` | Mã chỉ số | `999` | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2026-07-24T13:51:07.000` | | **`price`** | `float64` | Giá giao dịch | `28.95` | | **`volume`** | `int64` | Khối lượng giao dịch | `200` | | **`match_type`** | `object` | Loại lệnh khớp (Buy/Sell) | `Buy` | | **`id`** | `object` | Mã ID hệ thống | `2026-07-24_135107_289500_200` | ### Market().equity('TCB').trading_stats() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`average_match_volume`** | `float64` | Trung bình KL khớp lệnh | `8927028.728255529` | | **`average_match_value`** | `float64` | Trung bình GT khớp lệnh | `312600000553.7346` | | **`average_deal_volume`** | `float64` | Trung bình KL thỏa thuận | `2853441.062899263` | | **`average_deal_value`** | `float64` | Trung bình GT thỏa thuận | `87868547666.69681` | | **`average_volume`** | `float64` | Khối lượng trung bình | `11780469.79115479` | | **`average_value`** | `float64` | Giá trị trung bình | `400468548220.43146` | | **`total_match_volume`** | `float64` | Tổng khối lượng khớp lệnh | `18166503462.0` | | **`total_match_value`** | `float64` | Tổng giá trị khớp lệnh | `636141001126850.0` | | **`total_deal_volume`** | `float64` | Tổng khối lượng thỏa thuận | `5806752563.0` | | **`total_deal_value`** | `float64` | Tổng giá trị thỏa thuận | `178812494501728.0` | | **`total_volume`** | `float64` | Tổng khối lượng | `23973256025.0` | | **`total_value`** | `float64` | Tổng giá trị | `814953495628578.0` | | **`fr_buy_volume_total`** | `float64` | Tổng KL khối ngoại mua | `1787901938.0` | | **`fr_buy_value_total`** | `float64` | Tổng GT khối ngoại mua | `56211301699998.0` | | **`fr_sell_volume_total`** | `float64` | Tổng KL khối ngoại bán | `1873995282.0` | | **`fr_sell_value_total`** | `float64` | Tổng GT khối ngoại bán | `59270092237248.0` | | **`fr_net_volume_total`** | `float64` | KL ròng khối ngoại | `-86093344.0` | | **`fr_net_value_total`** | `float64` | GT ròng khối ngoại | `-3058790537250.0` | | **`fr_buy_volume_matched`** | `float64` | KL khớp lệnh khối ngoại mua | `564003306.0` | | **`fr_buy_value_matched`** | `float64` | GT khớp lệnh khối ngoại mua | `16711447532400.0` | | **`fr_sell_volume_matched`** | `float64` | KL khớp lệnh khối ngoại bán | `673562536.0` | | **`fr_sell_value_matched`** | `float64` | GT khớp lệnh khối ngoại bán | `20470531031850.0` | | **`fr_buy_volume_deal`** | `float64` | KL thỏa thuận khối ngoại mua | `1223898632.0` | | **`fr_buy_value_deal`** | `float64` | GT thỏa thuận khối ngoại mua | `39499854167598.0` | | **`fr_sell_volume_deal`** | `float64` | KL thỏa thuận khối ngoại bán | `1200432794.0` | | **`fr_sell_value_deal`** | `float64` | GT thỏa thuận khối ngoại bán | `38799562583748.0` | | **`fr_buy_volume_total_avg`** | `float64` | TB tổng KL khối ngoại mua | `878575.8909090909` | | **`fr_buy_value_total_avg`** | `float64` | TB tổng GT khối ngoại mua | `27622261277.640293` | | **`fr_sell_volume_total_avg`** | `float64` | TB tổng KL khối ngoại bán | `920882.2024570025` | | **`fr_sell_value_total_avg`** | `float64` | TB tổng GT khối ngoại bán | `29125352450.73612` | | **`fr_net_volume_total_avg`** | `float64` | Trung bình KL ròng khối ngoại | `-42306.3115479116` | | **`fr_net_value_total_avg`** | `float64` | Trung bình GT ròng khối ngoại | `-1503091173.095827` | | **`fr_buy_volume_matched_avg`** | `float64` | TB KL khớp lệnh khối ngoại mua | `277151.5017199017` | | **`fr_buy_value_matched_avg`** | `float64` | TB GT khớp lệnh khối ngoại mua | `8212013529.43489` | | **`fr_sell_volume_matched_avg`** | `float64` | TB KL khớp lệnh khối ngoại bán | `330988.9611793612` | | **`fr_sell_value_matched_avg`** | `float64` | TB GT khớp lệnh khối ngoại bán | `10059229008.280098` | | **`fr_buy_volume_deal_avg`** | `float64` | TB KL thỏa thuận khối ngoại mua | `601424.3891891892` | | **`fr_buy_value_deal_avg`** | `float64` | TB GT thỏa thuận khối ngoại mua | `19410247748.205406` | | **`fr_sell_volume_deal_avg`** | `float64` | TB KL thỏa thuận khối ngoại bán | `589893.2648648649` | | **`fr_sell_value_deal_avg`** | `float64` | TB GT thỏa thuận khối ngoại bán | `19066124119.777885` | | **`fr_net_volume_matched`** | `float64` | KL khớp lệnh ròng khối ngoại | `-109559230.0` | | **`fr_net_value_matched`** | `float64` | GT khớp lệnh ròng khối ngoại | `-3759083499450.0` | | **`fr_net_volume_matched_avg`** | `float64` | TB KL khớp lệnh ròng khối ngoại | `-53837.4594594594` | | **`fr_net_value_matched_avg`** | `float64` | TB GT khớp lệnh ròng khối ngoại | `-1847215478.845208` | | **`fr_net_volume_deal`** | `float64` | KL thỏa thuận ròng khối ngoại | `23465838.0` | | **`fr_net_value_deal`** | `float64` | GT thỏa thuận ròng khối ngoại | `700291583850.0` | | **`fr_net_volume_deal_avg`** | `float64` | TB KL thỏa thuận ròng khối ngoại | `11531.1243243243` | | **`fr_net_value_deal_avg`** | `float64` | TB GT thỏa thuận ròng khối ngoại | `344123628.427521` | | **`total_buy_trade_volume`** | `float64` | Tổng khối lượng lệnh mua | `31400494665.0` | | **`total_sell_trade_volume`** | `float64` | Tổng khối lượng lệnh bán | `32564549439.0` | | **`total_buy_trade_volume_avg`** | `float64` | TB khối lượng lệnh mua | `15430218.508599509` | | **`total_sell_trade_volume_avg`** | `float64` | TB khối lượng lệnh bán | `16002235.596560197` | | **`total_buy_trade`** | `float64` | Tổng số lệnh mua | `10383400.0` | | **`total_sell_trade`** | `float64` | Tổng số lệnh bán | `8452946.0` | | **`total_buy_trade_avg`** | `float64` | | `5102.4078624079` | | **`total_sell_trade_avg`** | `float64` | | `4153.7818181818` | | **`total_buy_unmatched_volume_avg`** | `float64` | TB khối lượng mua chưa khớp | `6503189.78034398` | | **`total_sell_unmatched_volume_avg`** | `float64` | TB khối lượng bán chưa khớp | `7075206.868304668` | | **`total_buy_unmatched_volume`** | `float64` | Tổng khối lượng mua chưa khớp | `13233991203.0` | | **`total_sell_unmatched_volume`** | `float64` | Tổng khối lượng bán chưa khớp | `14398045977.0` | | **`total_net_trade_volume`** | `float64` | Tổng KL giao dịch ròng | `-1164054774.0` | | **`total_net_trade_volume_avg`** | `float64` | | `-572017.087960688` | | **`average_buy_volume_per_trade`** | `float64` | | `3024.1052704317` | | **`average_sell_volume_per_trade`** | `float64` | | `3852.4497185952` | ### Market().equity('TCB').volume_profile() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`price`** | `int64` | Giá giao dịch | `28500` | | **`buy_volume`** | `int64` | Khối lượng mua | `15500` | | **`sell_volume`** | `int64` | Khối lượng bán | `93100` | | **`unknown_volume`** | `int64` | Khối lượng không xác định | `0` | | **`total_volume`** | `int64` | Tổng khối lượng | `108600` | ### Market().index('VNINDEX').ohlcv(length='1Y') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`time`** | `datetime64[ns]` | Thời gian giao dịch | `2025-07-28T07:00:00.000` | | **`open`** | `float64` | Giá mở cửa | `1541.82` | | **`high`** | `float64` | Giá cao nhất | `1558.12` | | **`low`** | `float64` | Giá thấp nhất | `1531.13` | | **`close`** | `float64` | Giá đóng cửa | `1557.42` | | **`volume`** | `int64` | Khối lượng giao dịch | `1788192102` | ### Market().index('VNINDEX').stock_influence() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `BSR` | | **`close_price`** | `int64` | Giá đóng cửa | `24000` | | **`price_change`** | `float64` | Biến động giá | `650.0` | | **`percent_change`** | `float64` | Biến động giá (%) | `2.78` | | **`outstanding_shares`** | `int64` | Cổ phiếu lưu hành | `5007299686` | | **`market_cap`** | `int64` | Vốn hóa thị trường | `120175192464000` | | **`weight`** | `float64` | Trọng số | `1.5031` | | **`basic_index`** | `float64` | Chỉ số cơ sở | `1699.38` | | **`influence_percent`** | `float64` | Tỷ lệ ảnh hưởng (%) | `0.0418` | | **`influence_point`** | `float64` | Điểm ảnh hưởng | `0.7101` | | **`influence_type`** | `int64` | Loại ảnh hưởng | `1` | | **`rank`** | `int64` | Xếp hạng | `1` | ### Market().index('VNINDEX').trade_history() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `VNINDEX` | | **`trading_date`** | `datetime64[ns]` | Ngày giao dịch | `2026-07-24T00:00:00.000` | | **`price_change`** | `float64` | Biến động giá | `-13.27` | | **`percent_price_change`** | `float64` | Biến động giá (%) | `-0.00780873` | | **`reference_price`** | `float64` | Giá tham chiếu | `1699.38` | | **`open`** | `float64` | Giá mở cửa | `1683.23` | | **`close`** | `float64` | Giá đóng cửa | `1686.11` | | **`high`** | `float64` | Giá cao nhất | `1696.78` | | **`low`** | `float64` | Giá thấp nhất | `1674.64` | | **`matched_volume`** | `float64` | Khối lượng khớp lệnh | `499069288.0` | | **`matched_value`** | `float64` | Giá trị khớp lệnh | `11912420930840.0` | | **`deal_volume`** | `float64` | Khối lượng thỏa thuận | `92944831.0` | | **`deal_value`** | `float64` | Giá trị thỏa thuận | `2056607522780.0` | | **`total_volume`** | `float64` | Tổng khối lượng | `592014119.0` | | **`total_value`** | `float64` | Tổng giá trị | `13969028453620.0` | | **`total_stock_up_price`** | `float64` | Số mã tăng giá | `88.0` | | **`total_stock_down_price`** | `float64` | Số mã giảm giá | `227.0` | | **`total_stock_no_change_price`** | `float64` | Số mã đứng giá | `58.0` | | **`total_stock_ceiling`** | `float64` | Số mã tăng trần | `5.0` | | **`total_stock_floor`** | `float64` | Số mã giảm sàn | `9.0` | | **`total_up_volume`** | `float64` | Tổng KL các mã tăng | `89525744.0` | | **`total_down_volume`** | `float64` | Tổng KL các mã giảm | `432765744.0` | | **`total_no_change_volume`** | `float64` | Tổng KL các mã đứng giá | `67318746.0` | | **`total_trade`** | `float64` | Tổng số lệnh giao dịch | `355474.0` | | **`total_buy_trade`** | `float64` | Tổng số lệnh mua | `366397.0` | | **`total_buy_trade_volume`** | `float64` | Tổng khối lượng lệnh mua | `1035340646.0` | | **`total_sell_trade`** | `float64` | Tổng số lệnh bán | `294075.0` | | **`total_sell_trade_volume`** | `float64` | Tổng khối lượng lệnh bán | `1082564125.0` | | **`total_shares`** | `float64` | Tổng số cổ phần nắm giữ | `224902576315.0` | | **`market_cap`** | `float64` | Vốn hóa thị trường | `8015596682177170.0` | | **`total_net_trade_volume`** | `float64` | Tổng KL giao dịch ròng | `-47223479.0` | | **`total_buy_unmatched_volume`** | `float64` | Tổng khối lượng mua chưa khớp | `536271358.0` | | **`total_sell_unmatched_volume`** | `float64` | Tổng khối lượng bán chưa khớp | `583494837.0` | | **`average_buy_trade_volume`** | `float64` | Trung bình KL mỗi lệnh mua | `2825.7345065598` | | **`average_sell_trade_volume`** | `float64` | Trung bình KL mỗi lệnh bán | `3681.2518065119` | | **`price_change_value`** | `object` | Giá trị biến động | `-13.27 (-0.8%)` | ### Market().odd_lot(['TCB', 'SSI']) | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `29250` | | **`high_price`** | `int64` | Giá cao nhất | `29400` | | **`low_price`** | `int64` | Giá thấp nhất | `28600` | | **`match_price`** | `int64` | Giá khớp lệnh | `28800` | | **`match_vol`** | `int64` | Khối lượng khớp lệnh | `12` | | **`total_volume`** | `int64` | Tổng khối lượng | `13249` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28800.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `1815` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28750` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `1308` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28700` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `1971` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28850.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `99` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `29000` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `13` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `29100` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `1` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `0` | ### Market().price_board(['TCB', 'SSI']) | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `28900` | | **`high_price`** | `int64` | Giá cao nhất | `29200` | | **`low_price`** | `int64` | Giá thấp nhất | `28500` | | **`close_price`** | `int64` | Giá đóng cửa | `28600` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `4292400` | ### Market().quote(['TCB', 'SSI']) | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --- | --- | --- | --- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `TCB` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HOSE` | | **`reference_price`** | `int64` | Giá tham chiếu | `29250` | | **`ceiling_price`** | `int64` | Giá trần | `31250` | | **`floor_price`** | `int64` | Giá sàn | `27250` | | **`open_price`** | `int64` | Giá mở cửa | `28900` | | **`high_price`** | `int64` | Giá cao nhất | `29200` | | **`low_price`** | `int64` | Giá thấp nhất | `28500` | | **`close_price`** | `int64` | Giá đóng cửa | `28600` | | **`bid_price_1`** | `object` | Giá Mua 1 | `28600.0` | | **`bid_vol_1`** | `int64` | Khối lượng Mua 1 | `32400` | | **`bid_price_2`** | `int64` | Giá Mua 2 | `28550` | | **`bid_vol_2`** | `int64` | Khối lượng Mua 2 | `189200` | | **`bid_price_3`** | `int64` | Giá Mua 3 | `28500` | | **`bid_vol_3`** | `int64` | Khối lượng Mua 3 | `654400` | | **`ask_price_1`** | `object` | Giá Bán 1 | `28650.0` | | **`ask_vol_1`** | `int64` | Khối lượng Bán 1 | `500` | | **`ask_price_2`** | `int64` | Giá Bán 2 | `28750` | | **`ask_vol_2`** | `int64` | Khối lượng Bán 2 | `400` | | **`ask_price_3`** | `int64` | Giá Bán 3 | `28800` | | **`ask_vol_3`** | `int64` | Khối lượng Bán 3 | `14100` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `1655531` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `4292400` | --- ## Document: Reference ### Reference().bond('BAB123032').info() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --------------------- | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `BAB123032` | | **`change_1m`** | `float64` | Thay đổi 1 tháng | `0.00` | | **`change_1y`** | `float64` | Thay đổi 1 năm | `0.00` | | **`current_ratio`** | `float64` | Tỷ số thanh toán hiện hành | `1.5` | | **`debt_ratio`** | `float64` | Tỷ lệ nợ | `0.8` | | **`roe`** | `float64` | Tỷ suất lợi nhuận trên vốn CSH | `15.5` | | **`roa`** | `float64` | Tỷ suất lợi nhuận trên tổng tài sản| `2.3` | | **`pe`** | `float64` | Hệ số Giá / Lợi nhuận (P/E) | `12.33` | | **`pb`** | `float64` | Hệ số Giá / Giá trị sổ sách (P/B) | `2.12` | | **`report_period`** | `object` | Kỳ báo cáo | `12/2024` |
Đối với Trái phiếu Chính phủ (Government Bonds, ví dụ: 41BAGC000), do tính chất không có báo cáo tài chính doanh nghiệp hay các chỉ số kinh doanh, API gốc của KBS chỉ trả về 3 trường dữ liệu. Vì vậy kết quả DataFrame trả về sẽ chỉ gồm 3 cột: symbol, change_1m và change_1y.
### Reference().bond().list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ----------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `BAB123032` | | **`type`** | `object` | Loại hình (Ví dụ: corporate, STOCK) | `corporate` | ### Reference().company('FPT').events() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --------------------- | ------------ | ---------------------------------- | ------------------------------------------------------- | | **`id`** | `object` | Mã ID hệ thống | `6a445e54279ac17a86e4cab3` | | **`event_name_vi`** | `object` | Tên sự kiện (Tiếng Việt) | `Giao dịch nội bộ: Giao dịch cá nhân` | | **`event_name_en`** | `object` | Tên sự kiện (Tiếng Anh) | `Director Deal: Individual transactions` | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`event_code`** | `object` | Mã sự kiện | `DDIND` | | **`event_title_vi`** | `object` | Tiêu đề sự kiện (Tiếng Việt) | `Nguyễn Văn Khoa - Đăng kí Mua 428,368 FPT` | | **`event_title_en`** | `object` | Tiêu đề sự kiện (Tiếng Anh) | `Nguyen Van Khoa - Subscribe to Buy 428,368 FPT shares` | | **`display_date1`** | `object` | Thời gian / Ngày tháng | `2026-06-24T00:00:00` | | **`display_date2`** | `object` | Thời gian / Ngày tháng | `2026-06-29T00:00:00` | | **`public_date`** | `object` | Public Ngày | `2026-06-29T00:00:00` | | **`start_date`** | `object` | Start Ngày | `2026-06-24T00:00:00` | | **`end_date`** | `object` | End Ngày | `2026-06-24T00:00:00` | | **`action_type_vi`** | `object` | Loại hành động (Tiếng Việt) | `Mua` | | **`action_type_en`** | `object` | Loại hành động (Tiếng Anh) | `Buy` | | **`category`** | `object` | Phân loại | `MAJOR_SHAREHOLDER_TRADING` | | **`record_date`** | `object` | Record Ngày | None | | **`exright_date`** | `object` | Exright Ngày | None | | **`exercise_ratio`** | `float64` | Tỷ lệ | None | | **`payout_date`** | `object` | Payout Ngày | None | | **`value_per_share`** | `float64` | Giá trị trên mỗi cổ phần | None | | **`issue_date`** | `object` | Ngày phát hành | None | | **`listing_date`** | `object` | Listing Ngày | None | ### Reference().company('FPT').info() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------ | ------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Công ty Cổ phần FPT` | | **`sector`** | `object` | Ngành nghề | `Technology` | | **`profile`** | `object` | Hồ sơ công ty / Mô tả hoạt động | `Công ty Cổ phần FPT (FPT) có tiền thân là Công ty Công nghệ Thực phẩm được thành lập năm 1988. Công ty hoạt động chính trong lĩnh vực phần mềm, công nghệ thông tin, tích hợp hệ thống, viễn thông, và giáo dục đào tạo. FPT chính thức hoạt động theo mô hình công ty cổ phần từ năm 2002. FPT là tập đoàn công nghệ và dịch vụ CNTT có hiện diện tại hơn 30 quốc gia và vùng lãnh thổ trên 4 châu lục. Doanh nghiệp tập trung vào các mảng công nghệ chiến lược như AI, điện toán đám mây, bán dẫn, an ninh mạng và dữ liệu, đồng thời vận hành trung tâm dữ liệu quy mô 10.000 m² cùng các nhà máy AI tại Việt Nam và Nhật Bản. FPT cũng tham gia nhiều dự án chuyển đổi số quy mô lớn cho khối Chính phủ, bộ ngành, địa phương và khách hàng toàn cầu. FPT được niêm yết trên Sở Giao dịch Chứng khoán Thành phố Hồ Chí Minh (HOSE) từ tháng 12/2006.` | | **`listing_date`** | `object` | Listing Ngày | `2006-12-13T00:00:00` | | **`issued_share`** | `float64` | Khối lượng cổ phiếu lưu hành | `1714326422.0` | ### Reference().company('FPT').news() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------ | ------------ | ---------------------------------- | --------------------------------------------------------------------------------- | | **`id`** | `object` | Mã ID hệ thống | `6a600e13c5a4aaeae5fa24cd` | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`title`** | `object` | Tiêu đề tin tức | `FPT: Giấy chứng nhận đăng ký doanh nghiệp thay đổi lần thứ 61` | | **`summary`** | `object` | Nội dung tóm tắt | None | | **`content`** | `object` | Nội dung đầy đủ | None | | **`publish_time`** | `object` | Thời gian công bố | `2026-07-20T17:35:14` | | **`source`** | `object` | Nguồn dữ liệu | None | | **`url`** | `object` | Đường dẫn nguồn gốc | None | | **`category`** | `object` | Phân loại | None | | **`image_url`** | `object` | Đường dẫn ảnh tin tức | `https://cdn.fiingroup.vn/medialib/127889/I/2024/11/25/16205804004570700_FPT.png` |
Khi sử dụng tham số `mode='detail'` (Ví dụ: `Reference().company('FPT').news(mode='detail')`), API sẽ đi vào từng trang bài viết để lấy chi tiết nội dung văn bản.
### Reference().company('FPT').news(mode='detail') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------ | ------------ | ---------------------------------- | --------------------------------------------------------------------------------- | | **`id`** | `object` | Mã ID hệ thống | `6a600e13c5a4aaeae5fa24cd` | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`title`** | `object` | Tiêu đề tin tức | `FPT: Giấy chứng nhận đăng ký doanh nghiệp thay đổi lần thứ 61` | | **`summary`** | `object` | Nội dung tóm tắt | `Công ty Cổ phần FPT thông báo...` | | **`content`** | `object` | Nội dung đầy đủ | `Công ty Cổ phần FPT thông báo...Tài liệu đính kèm...` | | **`publish_time`** | `object` | Thời gian công bố | `2026-07-20T17:35:14` | | **`source`** | `object` | Nguồn dữ liệu | `HOSE` | | **`url`** | `object` | Đường dẫn nguồn gốc | `https://www.hsx.vn/vi/tin-tuc/...` | | **`category`** | `object` | Phân loại | `Operations` | | **`image_url`** | `object` | Đường dẫn ảnh tin tức | `https://cdn.fiingroup.vn/medialib/127889/I/2024/11/25/16205804004570700_FPT.png` | ### Reference().company('FPT').officers() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------ | ------------ | -------------------------------------- | ---------------------------- | | **`index`** | `int64` | Mã chỉ số | `0` | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Trương Gia Bình` | | **`position`** | `object` | Chức vụ | `Chủ tịch Hội đồng Quản trị` | | **`total_shares`** | `int64` | Tổng số cổ phần nắm giữ | `117347966` | | **`rate`** | `float64` | Tỷ lệ sở hữu | `0.0689` | ### Reference().company('FPT').shareholders() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------------- | ------------ | -------------------------------------- | ------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Trương Gia Bình` | | **`shareholder_type`** | `object` | Loại cổ đông (Cá nhân/Tổ chức) | `Individual` | | **`total_shares`** | `int64` | Tổng số cổ phần nắm giữ | `117347966` | | **`rate`** | `float64` | Tỷ lệ sở hữu | `0.0689` | | **`date`** | `object` | Ngày giao dịch / Dấu thời gian | `2026-02-03T10:36:48.587` | ### Reference().company('FPT').subsidiaries() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------- | ------------ | -------------------------------------- | --------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `FPT` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `Công ty TNHH Giáo Dục FPT` | | **`rate`** | `float64` | Tỷ lệ sở hữu | `1.0` | | **`sub_symbol`** | `object` | Mã công ty con | `FPTE` | ### Reference().equity.by_exchange() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------------- | ------------ | ---------------------------------- | ----------------------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `YTC` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `UPCOM` | | **`organ_name`** | `object` | Tên tổ chức | `Công ty Cổ phần Xuất nhập khẩu Y tế Thành phố Hồ Chí Minh` | | **`organ_short_name`** | `object` | Tên viết tắt của tổ chức | `XNK Y tế TP.HCM` | | **`icb_code_lv2`** | `object` | Mã phân ngành ICB cấp 2 | `4500` | ### Reference().equity.by_group('VN30') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | ### Reference().equity.list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | -------------- | ------------ | ---------------------------------- | ----------------------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `YTC` | | **`org_name`** | `object` | Tên tổ chức | `Công ty Cổ phần Xuất nhập khẩu Y tế Thành phố Hồ Chí Minh` | ### Reference().equity.list_by_exchange() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------------- | ------------ | ---------------------------------- | ----------------------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `YTC` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `UPCOM` | | **`organ_name`** | `object` | Tên tổ chức | `Công ty Cổ phần Xuất nhập khẩu Y tế Thành phố Hồ Chí Minh` | | **`organ_short_name`** | `object` | Tên viết tắt của tổ chức | `XNK Y tế TP.HCM` | | **`icb_code_lv2`** | `object` | Mã phân ngành ICB cấp 2 | `4500` | ### Reference().equity.list_by_group('VN30') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | ### Reference().equity.list_by_industry('8773') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------- | ------------ | ---------------------------------- | --------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `EVF` | | **`organ_name`** | `object` | Tên tổ chức | `Công ty Tài chính Tổng hợp Cổ phần Điện Lực` | | **`com_type_code`** | `object` | Loại hình công ty | `NH` | | **`icb_level`** | `int64` | Cấp độ ngành ICB | `4` | | **`icb_code`** | `object` | Mã chuẩn phân ngành ICB | `8773` | | **`icb_name`** | `object` | Tên ngành ICB | `Tài chính cá nhân` | ### Reference().etf.list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `E1VFVN30` | ### Reference().events.calendar() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------- | ---------------- | ---------------------------------- | ----------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `HVN` | | **`event_name`** | `object` | Tên sự kiện | `Đại hội Đồng Cổ đông` | | **`event_title`** | `object` | Tiêu đề sự kiện | `HVN - Tổ chức ĐHĐCĐ thường niên 2026` | | **`ex_right_date`** | `datetime64[ns]` | Ex Right Ngày | `2026-05-28T00:00:00.000` | | **`record_date`** | `datetime64[ns]` | Record Ngày | `2026-05-29T00:00:00.000` | | **`organ_name`** | `object` | Tên tổ chức | `Tổng Công ty Hàng không Việt Nam - CTCP` | | **`public_date`** | `datetime64[ns]` | Public Ngày | `2026-05-19T00:00:00.000` | | **`issue_date`** | `datetime64[ns]` | Ngày phát hành | `2026-06-28T00:00:00.000` | | **`event_type`** | `object` | Loại sự kiện | `AGME` | ### Reference().events.market() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------- | ---------------- | ------------------------------ | ------------------------- | | **`date`** | `datetime64[ns]` | Ngày giao dịch / Dấu thời gian | `2000-01-01T00:00:00.000` | | **`event_name`** | `object` | Tên sự kiện | `Tết Dương Lịch` | | **`event_type`** | `object` | Loại sự kiện | `Holiday` | | **`duration`** | `object` | Thời lượng / Kỳ hạn | None | ### Reference().fund.list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ---------------------- | ------------ | ---------------------------------- | ---------------------------------------- | | **`ticker`** | `object` | Mã định danh chứng khoán / tổ chức | `BVFED` | | **`organ_name`** | `object` | Tên tổ chức | `QUỸ ĐẦU TƯ CỔ PHIẾU NĂNG ĐỘNG BẢO VIỆT` | | **`organ_short_name`** | `object` | Tên viết tắt của tổ chức | `CÔNG TY TNHH QUẢN LÝ QUỸ BẢO VIỆT` | | **`fund_type`** | `object` | Loại quỹ (ETF, Mở, Đóng...) | `equity_fund` | | **`management_fee`** | `float64` | Phí quản lý (%) | `1.0` | | **`inception_date`** | `object` | Ngày thành lập | `2014-01-07` | | **`nav`** | `float64` | Giá trị tài sản ròng | `29011.0` | | **`nav_update_at`** | `object` | Thời gian / Ngày tháng | `2026-07-26` | ### Reference().futures('VN30F1M').info() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------------- | ------------ | ---------------------------------- | --------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `41I1G8000` | | **`full_name`** | `object` | Tên đầy đủ | `VN30 Index Futures 082026` | | **`underlying_symbol`** | `object` | Mã chứng khoán cơ sở | `VN30` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `HNX` | | **`first_trading_date`** | `object` | First Trading Ngày | `19/06/2026` | | **`last_trading_date`** | `object` | Last Trading Ngày | `20/08/2026` | | **`reference_price`** | `float64` | Giá tham chiếu | `1842.7` | | **`ceiling_price`** | `float64` | Giá trần | `1971.6` | | **`floor_price`** | `float64` | Giá sàn | `1713.8` | | **`open_price`** | `int64` | Giá mở cửa | `1834` | | **`high_price`** | `float64` | Giá cao nhất | `1841.7` | | **`low_price`** | `float64` | Giá thấp nhất | `1822.3` | | **`close_price`** | `int64` | Giá đóng cửa | `1835` | | **`open_interest`** | `object` | Hợp đồng mở (OI) | `39352` | | **`basis`** | `object` | Độ lệch (Basis) | `5.64` | | **`foreign_buy_volume`** | `int64` | Khối lượng khối ngoại mua | `8153` | | **`foreign_sell_volume`** | `int64` | Khối lượng khối ngoại bán | `0` | ### Reference().futures().list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `41I1G8000` | ### Reference().index.groups() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------- | ------------ | ------------- | --------------------------------------------------- | | **`group_name`** | `object` | Tên nhóm | `BOND` | | **`group_code`** | `object` | Mã nhóm | `BOND` | | **`category`** | `object` | Phân loại | `Trái phiếu` | | **`description`** | `object` | Mô tả tóm tắt | `Corporate Bond - Trái phiếu doanh nghiệp niêm yết` | ### Reference().index.list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------- | ------------ | -------------------------------------- | ---------------------------------------------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `VN30` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `VN30` | | **`description`** | `object` | Mô tả tóm tắt | `30 cổ phiếu vốn hóa lớn nhất & thanh khoản tốt nhất HOSE` | | **`full_name`** | `object` | Tên đầy đủ | `VN30 Index` | | **`group`** | `object` | Nhóm chỉ số / Nhóm ngành | `HOSE Indices` | | **`index_id`** | `float64` | Mã ID chỉ số | `5.0` | | **`sector_id`** | `float64` | Mã ID ngành | None | ### Reference().index.members('VN30') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `ACB` | ### Reference().industry.list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | --------------- | ------------ | ----------------------- | ----------- | | **`icb_code`** | `object` | Mã chuẩn phân ngành ICB | `0001` | | **`icb_name`** | `object` | Tên ngành ICB | `Dầu khí` | | **`icb_level`** | `int64` | Cấp độ ngành ICB | `1` | ### Reference().industry.sectors() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------------- | ------------ | ---------------------------------- | -------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `A32` | | **`organ_name`** | `object` | Tên tổ chức | `Công ty Cổ phần 32` | | **`com_type_code`** | `object` | Loại hình công ty | `CT` | | **`icb_level`** | `int64` | Cấp độ ngành ICB | `1` | | **`icb_code`** | `object` | Mã chuẩn phân ngành ICB | `3000` | | **`icb_name`** | `object` | Tên ngành ICB | `Hàng Tiêu dùng` | ### Reference().market.status() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------------- | ---------------- | -------------------------------- | ------------------------- | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `UPCOM` | | **`asset_type`** | `object` | Loại tài sản (Ví dụ: EQUITY) | `EQUITY` | | **`status`** | `object` | Trạng thái (Ví dụ: CLOSED, OPEN) | `CLOSED` | | **`timestamp`** | `datetime64[ns]` | Dấu thời gian | `2026-07-26T05:05:25.046` | | **`last_trading_date`** | `datetime64[ns]` | Last Trading Ngày | `2026-07-24T12:00:02.757` | ### Reference().search.info('EURUSD') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------- | ------------ | -------------------------------------- | ------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `EURUSD` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `EUR/USD` | | **`exchange`** | `object` | Sàn giao dịch (HOSE, HNX, UPCOM) | `FX` | | **`description`** | `object` | Mô tả tóm tắt | `Euro vs US Dollar` | | **`name_local`** | `object` | Tên địa phương (Tiếng Việt) | `DE` | | **`symbol_id`** | `object` | Mã ID hệ thống | `EUR-USD` | ### Reference().search.symbol('EURUSD') | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ----------------- | ------------ | -------------------------------------- | ------------------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `EURUSD` | | **`name`** | `object` | Tên đầy đủ của tổ chức / công ty / quỹ | `EUR/USD` | | **`description`** | `object` | Mô tả tóm tắt | `Euro vs US Dollar` | ### Reference().warrant('CHPG2322').info() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `CHPG2322` | ### Reference().warrant().list() | Tên Cột | Kiểu Dữ Liệu | Ý Nghĩa | Giá Trị Mẫu | | ------------ | ------------ | ---------------------------------- | ----------- | | **`symbol`** | `object` | Mã định danh chứng khoán / tổ chức | `CACB2511` | --- ## Document: Nguồn dữ liệu

Hướng dẫn này tập trung vào Unified UI - kiến trúc mới và định tuyến sử dụng mặc định của Vnstock. Nếu bạn là nhà phát triển muốn can thiệp sâu, ép nguồn hoặc tuỳ biến dữ liệu chi tiết (ví dụ sử dụng CafeF), vui lòng tham khảo Tính Năng Nâng Cao.

Tài liệu này là chỉ mục tổng hợp giúp bạn tra cứu toàn bộ các hệ thống cấp dữ liệu gốc được sử dụng trong thư viện vnstock_data. Hiện tại, thư viện bao gồm **14 module** cấp dữ liệu (gồm 10 nguồn trong/ngoài nước). Hệ sinh thái phân loại thành 3 nhóm cấp bậc: 1. **Unified UI**: Các nguồn được hệ thống tự động định tuyến. 2. **Adapter API**: Nguồn chuyên biệt, yêu cầu chỉ định tham số `source='...'`. --- ## Bảng Tra Cứu Nhanh ### 1. Nguồn Dữ Liệu Nội Địa | Lớp (Layer) | VCI | KBS | ASEAN | MAS | VND | MBK/SPL | Fmarket | CafeF* | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | **Listing** | ✅ | ✅ | - | - | - | - | - | - | | **Quote/Market** | ✅ | ✅ | - | - | - | - | - | - | | **Company** | ✅ | - | - | - | - | - | - | - | | **Finance** | ✅ | - | - | ✅ | - | ✅ | - | - | | **Trading** | ✅ | ✅ | - | - | - | - | - | ✅ | | **Insights** | - | - | ✅ | - | ✅ | - | - | - | | **Macro** | - | - | ✅ | - | - | ✅ | - | - | | **Commodity** | - | - | ✅ | - | - | ✅ | - | - | | **Fund** | - | - | - | - | - | - | ✅ | - | *\*Ghi chú: CafeF thuộc nhóm Adapter API.* ### 2. Nguồn Dữ Liệu Quốc Tế & Giao Dịch | Lớp (Layer) | Dukascopy | Binance | FXSB* | Chủ yếu dùng cho | | --------------------- | :-------: | :-----: | :---: | -------------------------------------- | | **Market (Crypto)** | - | ✅ | - | Dữ liệu giao dịch tiền mã hóa | | **Market (Forex)** | ✅ | - | ✅ | Tỷ giá các cặp ngoại tệ | | **Commodity** | ✅ | - | - | Giá hàng hóa thế giới | *\*Ghi chú: FXSB thuộc nhóm Adapter API.* *\*\*Ghi chú: DNSE, SSI thuộc nhóm Connectors.* --- ## Phân Cấp Các Nguồn Dữ Liệu ### Nhóm 1: Unified UI Đây là các nguồn sẽ tự động phản hồi dữ liệu khi bạn gọi lệnh cơ bản như `Market().equity('VIC').ohlcv()`. **1. VCI - Nguồn Dữ Liệu Thông Tin Doanh Nghiệp & Danh Mục** - Cung cấp dữ liệu chuỗi thời gian dài (từ năm 2000), hệ thống toàn diện về hồ sơ doanh nghiệp và phân bổ danh mục chuẩn ICB. - *Lưu ý*: Có thể phát sinh hạn chế kết nối khi chạy trên các môi trường cloud do chính sách chặn dải IP. **2. KBS - Nguồn Dữ Liệu Biến Động Thị Trường** - Tập trung vào biến động giá trị và khớp lệnh trong phiên, là hệ thống định tuyến tự động xử lý các tác vụ truy xuất dữ liệu giá OHLCV, intraday, và sổ lệnh. **3. ASEAN - Nguồn Dữ Liệu Chỉ Báo & Vĩ Mô** - Chuyên biệt hóa về các phân tích định lượng (luân chuyển dòng tiền RRG, dòng tiền ngành) và thống kê dữ liệu vĩ mô, lãi suất, hàng hóa thế giới. **4. MAS - Nguồn Dữ Liệu Báo Cáo Tài Chính** - Định dạng cấu trúc báo cáo tài chính phân nhánh (cây tài khoản cha-con), bám sát cách thức trình bày thực tế. **5. VND - Nguồn Dữ Liệu Xếp Hạng** - Hỗ trợ dữ liệu định giá (P/E, P/B) và thống kê xếp hạng thị trường. **6. MBK & SPL - Nguồn Dự Phòng** - **MBK:** Bổ sung các chỉ số vĩ mô nội địa đặc thù (sản xuất công nghiệp, bán lẻ). - **SPL:** Định tuyến dự phòng cho các loại hàng hóa nội địa. **7. Fmarket - Nguồn Dữ Liệu Quỹ Đầu Tư** - Cơ sở dữ liệu chuyên biệt về chứng chỉ quỹ mở và quỹ ETF tại Việt Nam. **8. Binance - Nguồn Dữ Liệu Tiền Mã Hóa** - Định tuyến tự động phục vụ lớp `market.crypto` (lịch sử giá, sổ lệnh, giao dịch). **9. Dukascopy - Nguồn Dữ Liệu Ngoại Hối & Hàng Hóa Thế Giới** - Định tuyến tự động phục vụ nhu cầu tra cứu ngoại hối (`market.forex`) và hàng hóa quốc tế. --- ### Nhóm 2: Adapter API Không được cấu hình định tuyến mặc định nhằm giảm tải. Người dùng cần chủ động truyền tên nguồn vào lệnh gọi. **10. CafeF - Nguồn Phân Tích Dòng Tiền Tổ Chức** - Chuyên sâu về thống kê giao dịch khối ngoại, tự doanh, và giao dịch của cổ đông nội bộ. - **Cách gọi:** `Quote(source='cafef', symbol='VIC').history()` **11. FXSB (FX Smartbull) - Nguồn Mở Rộng Ngoại Hối** - Nguồn mở rộng dùng để trích xuất dữ liệu đa dạng hơn về các cặp tiền tệ. --- ## Hướng Dẫn Chọn Nguồn Cấu trúc Unified UI đã tự động hóa phần lớn quá trình lựa chọn. Tuy nhiên, người dùng có thể tham khảo quy tắc sau để tự tinh chỉnh khi cần: 1. **Biến động Giá & Sổ Lệnh**: Unified UI gọi KBS cho OHLCV ngắn hạn và VCI cho dài hạn. 2. **Tiền Mã Hóa / Ngoại hối**: Mặc định gọi Binance và Dukascopy. 3. **Hồ Sơ Công Ty & Danh Mục Ngành**: Mặc định gọi VCI để đảm bảo tính đầy đủ. 4. **Báo Cáo Tài Chính**: Định tuyến tới MAS để tận dụng cấu trúc dữ liệu theo định dạng khoản mục phổ biến. 5. **Dòng Tiền & Vĩ Mô**: Mặc định gọi ASEAN cho các chỉ báo tâm lý, vĩ mô và luân chuyển ngành. 6. **Sổ Lệnh Nội Bộ Chi Tiết**: Dùng cấu hình Nâng cao với tham số nguồn CafeF. 7. **Đặt Lệnh & Danh Mục**: Sử dụng SSI/DNSE thông qua hệ thống Connectors. ## Xử Lý Lỗi & Dự Phòng (Fallback) Do bản chất truy xuất dữ liệu API từ bên thứ ba, kết nối đôi khi có thể bị gián đoạn. Unified UI được thiết kế để hạn chế sự gián đoạn này, tuy nhiên người dùng có thể áp dụng thủ thuật tự viết kịch bản dự phòng: ```python from vnstock_data import Quote def get_data_with_fallback(symbol): # Ưu tiên mặc định (KBS), kế đến dự phòng dài hạn (VCI), và cuối cùng (VND) sources = ['kbs', 'vci', 'vnd'] for source in sources: try: quote = Quote(source=source, symbol=symbol) return quote.history(...) except Exception as e: print(f"Gián đoạn kết nối tới {source}: {e}") continue raise Exception("Lỗi truy xuất từ tất cả các nguồn dự phòng.") ``` --- ## Document: Dữ Liệu Cơ Bản (Fundamental Data)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
Nguồn dữ liệu mặc định cho Fundamental trong Unified UI đã được đổi từ MAS sang VCI để cung cấp độ chi tiết tốt hơn và tuân thủ các chuẩn mực VAS. Tuy nhiên, khi chạy trên Google Colab có thể gặp lỗi do không truy cập được dữ liệu từ VCI. Khuyến nghị cài đặt cục bộ (local) trên máy tính cá nhân để sử dụng ổn định.
## 📌 Tổng Quan **Fundamental Layer** cung cấp dữ liệu **báo cáo tài chính** (BCTC) và **tỷ số tài chính** phục vụ cho phân tích cơ bản của doanh nghiệp. Ở phương thức nâng cao, hệ thống trang bị tính năng **quy chuẩn hoá (Force scorecard)** giúp định hình ma trận tài chính cực mạnh cho các mô hình AI dự báo. Bao gồm Báo cáo kết quả kinh doanh, Bảng cân đối kế toán, Lưu chuyển tiền tệ, Tỷ số tài chính, Thuyết minh BCTC và Báo cáo sức khỏe tài chính tổng hợp (Auto Scorecard). ### 🗂️ Định Dạng Dữ Liệu & Cấu Trúc Cột Mới Từ phiên bản 3.2.8, tất cả các cơ chế triển khai hàm lấy BCTC đều có chung định dạng dữ liệu trả về mặc định là **Tidy Data (long format)**. Dữ liệu được tái cấu trúc, chuẩn hóa theo tiêu chuẩn kế toán Việt Nam (VAS) và các biểu mẫu ban hành đã được chuẩn hoá cho từng loại hình doanh nghiệp: * `id`: Mã (primary key) duy nhất cho mỗi tiêu chí (ví dụ: `IS_NET_REVENUE`). Giúp code gọi hàm đảm bảo thuật toán ổn định. * `name`: Tên tiêu chí theo chuẩn mực kế toán Việt Nam, dùng để giải nghĩa cho `id`. * `unit`: Đơn vị dữ liệu giúp đọc hiểu chuẩn xác. * `order`: Thứ tự trình bày tiêu chí trong báo cáo, giúp tái tạo chuẩn thứ tự khi dùng pivot hoặc hiển thị nhiều kỳ. * `level`: Phân cấp cha/con theo hệ thống chuẩn mực kế toán. Khi đổi tham số `format` sang `'wide'` hoặc `'time_series'`, hệ thống sẽ dùng `id` làm khoá chính để xoay trục báo cáo thay vì tên gốc dạng snake\_case đã được làm sạch như ở phiên bản cũ. > 🔗 Xem chi tiết: [Hướng dẫn Migration v3.2.8](https://vnstocks.com/docs/vnstock-data/nang-cap-phien-ban/v3.2.8) ### 🏗️ Cấu Trúc Nhóm Hàm Mô đun Fundamental hỗ trợ 2 dạng cú pháp linh hoạt (Proxy chaining): 1. **Dạng hướng đối tượng (Object Oriented):** `fun.equity("TCB").cash_flow()` 2. **Dạng hàm tiện ích (Utility Function):** `fun.equity.cash_flow("TCB")` ```python Fundamental() └── .equity # Dữ liệu tài chính chứng khoán (Cổ phiếu) ├── .income_statement() # Báo cáo kết quả kinh doanh ├── .balance_sheet() # Cân đối kế toán ├── .cash_flow() # Lưu chuyển tiền tệ ├── .ratio() # Tỷ số tài chính ├── .note() # Thuyết minh cơ cấu BCTC ├── .filing() # Hồ sơ & Tài liệu BCTC (PDF) └── .financial_health() # Báo cáo hợp nhất với Auto Scorecard ``` ## 1. Bảng cân đối kế toán (Balance Sheet) **Source:** VCI\ **Nhóm lệnh:** `equity.fundamental.balance_sheet`\ **Tham số:** * `period` (`str`, optional): Kỳ báo cáo (`'year'` cho năm, `'quarter'` cho quý). * `lang` (`str`, optional): Ngôn ngữ (`'vi'` hoặc `'en'`). Mặc định `'vi'`. * `format` (`str`, optional): Định dạng dữ liệu đầu ra (`'long'`, `'wide'`, `'time_series'`). Mặc định `'long'` ngoại từ hàm `financial_health`. * `drop_empty` (`bool`, optional): Xoá các tiêu chí trống hoàn toàn (NaN) trong kỳ báo cáo. Mặc định `False`. * `com_type` (`str`, optional): Cố định loại hình công ty để áp dụng taxonomy (`'Regular'`, `'Bank'`, `'Securities'`, `'Insurance'`). Theo mặc định sẽ tự động dò. Sử dụng nếu có mã bất kỳ bị nhận diện sai nhóm ngành khiến cho các chỉ tiêu bị thiếu hụt hoặc sai lệch. **Ví Dụ:** ```python from vnstock_data import Fundamental fun = Fundamental() df_bs = fun.equity.balance_sheet("VIC", period="quarter") ``` *** ## 2. Báo cáo kết quả kinh doanh (Income Statement) **Source:** VCI\ **Nhóm lệnh:** `equity.fundamental.income_statement`\ **Tham số:** Tương tự `balance_sheet` (`period`, `lang`, `format`, `drop_empty`, `com_type`). **Ví Dụ:** ```python df_income = fun.equity("TCB").income_statement(period="year") ``` *** ## 3. Lưu chuyển tiền tệ (Cash Flow) **Source:** VCI\ **Nhóm lệnh:** `equity.fundamental.cash_flow`\ **Tham số:** Tương tự `balance_sheet` (`period`, `lang`, `format`, `drop_empty`, `com_type`). **Ví Dụ:** ```python df_cf = fun.equity("VNM").cash_flow(period="year") ``` *** ## 4. Tỷ số tài chính (Financial Ratio) Chứa các tỷ số quan trọng như PE, PB, ROE, Debt/Equity. **Source:** VCI\ **Nhóm lệnh:** `equity.fundamental.ratio`\ **Tham số:** Tương tự `balance_sheet` (`period`, `lang`, `format`, `drop_empty`, `com_type`). **Ví Dụ:** ```python df_ratio = fun.equity("HPG").ratio(period="quarter") ``` *** ## 5. Thuyết minh BCTC (Note) **Source:** VCI\ **Nhóm lệnh:** `equity.fundamental.note`\ **Tham số:** * `period` (`str`, optional): Kỳ báo cáo. * `lang` (`str`): Ngôn ngữ (`'en'` hoặc `'vi'`). Mặc định `'en'`. * `dropna` (`bool`): Xóa trường rỗng. Mặc định `True`. Trích xuất tự động các thuyết minh con/ghi chú chi tiết đính kèm trên báo cáo tài chính hàng quý. **Ví Dụ:** ```python df_note = fun.equity("FPT").note(period="year", lang="vi") ``` *** ## 6. Hồ sơ & tài liệu PDF (Filing) **Source:** MBK\ **Nhóm lệnh:** `equity.fundamental.filing`\ **Tham số:** * `doc_type` (`str`, optional): Phân loại tài liệu muốn lấy. Mặc định `None` (lấy tất cả). Các tuỳ chọn hợp lệ bao gồm: * `financial_report`: Báo cáo tài chính * `annual_report`: Báo cáo thường niên * `prospectus`: Bản cáo bạch * `shareholder_resolution`: Nghị quyết HĐCĐ * `shareholder_material`: Tài liệu HĐCĐ * `business_explanation`: Giải trình KQKD * `management_report`: Báo cáo tình hình quản trị * `capital_adequacy`: Báo cáo tỷ lệ an toàn vốn * `board_resolution`: Nghị quyết HĐQT * `capital_safety`: Tỷ lệ an toàn tài chính * `other`: Khác Cung cấp đường dẫn tải trực tiếp đến các bản cáo bạch, báo cáo thường niên, file PDF BCTC. **Ví Dụ:** ```python df_filing = fun.equity("TCB").filing() ``` *** ## 7. Bảng tiêu chí tổng hợp (Financial Health) Từ **Vnstock 3.1.0**, hàm này được trang bị nhằm tăng tính ổn định cho code của người dùng và trích xuất bộ tiêu chí phân tích phổ biến một cách nhanh chóng. Cơ chế hoạt động của `financial_health` như sau: * Dò tìm mã ngành ICB tự động (qua `Reference` layer). * **Ép chuẩn** dữ liệu tài chính đi qua **bộ tiêu chí (scorecard)** (Ngân hàng, CK, Bảo hiểm, chung...). * Chỉ cho phép các tiêu chí đã chỉ định. * Nối BCTC theo phương ngang dựa vào index là `period`. * Áp `lang="vi"` để ánh xạ ra giao diện hiển thị. **Tham số bổ sung:** * `com_type`: `"auto"`, `"bank"`, `"securities"`, `"insurance"`, `"regular"` * `reports`: List các loại báo cáo muốn hợp nhất (Mặc định: cả 4 fundamental reports). **Ví Dụ:** ```python df_ssi = fun.equity("SSI").financial_health(scorecard="auto", lang="vi", limit=4) df_tcb = fun.equity("TCB").financial_health(scorecard="bank", lang="en", limit=4) ``` *** ## ⚠️ Lưu Ý Quan Trọng 1. **Tần Suất Update**: BCTC định kỳ được công bố theo quý, bán niên, báo cáo năm. 2. **Tự động cập nhật:** Dữ liệu các kỳ đã có báo cáo kiểm toán/soát xét sẽ tự động cập nhật thay thế dữ liệu do doanh nghiệp tự công bố trước đó. 3. **Mẫu báo cáo:** Dữ liệu chuẩn hoá tuân theo nội dung của báo cáo Hợp Nhất (nếu có). 4. **Đơn Vị Tiền Tệ**: Mặc định là VND trừ khi có chỉ định khác. Bạn có thể đối chiếu với trang chính thức của nguồn dữ liệu được công bố. --- ## Document: Giới thiệu vnstock_data

Dành cho thành viên đã tham gia chương trình tài trợ Vnstock Sponsor hoặc người dùng muốn so sánh tính năng giữa bản Cộng đồng miễn phí, mã nguồn công khai theo giấy phép riêng (vnstock) và bản Mở rộng nâng cao (vnstock_data) trước khi quyết định nâng cấp.

## Tổng quan so sánh | Tiêu chí | vnstock | vnstock_data | | :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Loại** | Mã nguồn công khai theo giấy phép riêng | Mã nguồn đóng (cấm sao chép, tái phân phối) | | **Mức phí** | Miễn phí | Tham gia đóng góp qua Gói tài trợ | | **Phân phối** | Công khai qua [PyPI](https://pypi.org/) và [Github](https://github.com/thinh-vu/vnstock) | Tại website qua trình cài đặt riêng | | **Hạn mức API** | Tối đa 60 yêu cầu/phút với mã API Key tạo trên website sau khi đăng nhập | Lên tới 180 - 600 yêu cầu/phút | | **Tải song song** | Người dùng tự cấu hình | Tự động tải đa luồng kết hợp giới hạn API cao hơn từ 3-8x tuỳ gói tài trợ | | **Dữ liệu trong phiên** | Qua REST API, độ trễ tương đối khoảng 1-5 giây theo nguồn | Qua WebSocket, cập nhật theo độ trễ của nguồn | | **Phạm vi dữ liệu** | Hạn chế: [Xem chi tiết](/docs/vnstock-data/gioi-thieu-vnstock-data#so-sanh-tinh-nang-chi-tiet) | Không giới hạn dữ liệu trả về từ nguồn. [Xem chi tiết](/docs/vnstock-data/gioi-thieu-vnstock-data#so-sanh-tinh-nang-chi-tiet) | | **Mục đích sử dụng** | Số lượng hàm và API hạn chế, sử dụng cho mục đích học tập, nghiên cứu, tra cứu nhanh, làm quen với lập trình và AI - không phù hợp cho người sử dụng chuyên nghiệp, phân tích thường xuyên số lượng lớn, cần tốc độ cao. | Cung cấp đầy đủ các hàm và API chuyên sâu, tối ưu hiệu suất, phù hợp cho người sử dụng chuyên nghiệp, xây dựng hệ thống phân tích tự động, phân tích thường xuyên dữ liệu lớn với tốc độ cao và độ ổn định vượt trội. | --- ## So sánh tính năng chi tiết ### 1. Dữ liệu giá cổ phiếu | Chức năng | vnstock (Miễn phí) | vnstock_data (Tài trợ) | | :------------------------- | :-------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lịch sử giá OHLCV | Tối đa 8 năm (khung ngày) và 1 năm (khung phút) | Truy cập toàn bộ dữ liệu từ khi cổ phiếu niêm yết | | Giá khớp lệnh trong ngày | Tối đa 30.000 bản ghi giao dịch | Không giới hạn | | Tải dữ liệu trong phiên | Sử dụng REST API - độ trễ thực tế ~1-5s trong phiên, theo nguồn | Sử dụng WebSocket nhận dữ liệu trong phiên theo độ trễ của nguồn, kết hợp thư viện `vnstock_pipeline` khi sử dụng gói tài trợ Golden trở lên. Mặc định sẽ dùng REST API như bản Cộng đồng. | ### 2. Dữ liệu tài chính & Doanh nghiệp | Chức năng | vnstock (Miễn phí) | vnstock_data (Tài trợ) | | :---------------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chỉ số tài chính & BCTC | Tối đa 8 kỳ (xác thực API key) hoặc 4 kỳ (chế độ khách) | Truy cập không giới hạn số kỳ lịch sử trả về từ nguồn. | | Thuyết minh báo cáo tài chính | Không hỗ trợ | Hỗ trợ trích xuất chi tiết thuyết minh BCTC | | Tải báo cáo tài chính PDF | Không hỗ trợ tải file PDF scan | Hỗ trợ tải toàn bộ các loại báo cáo chính thức của doanh nghiệp. Tiện lợi khi ứng dụng tải về trích xuất dữ liệu bằng nhận dạng hình ảnh thông qua AI Agent, đặc biệt hữu ích cho phần diễn giải thuyết minh BCTC. | | Chỉ tiêu sức khỏe tài chính | Không hỗ trợ | Đầy đủ bộ tiêu chí chuẩn hoá để đánh giá nhanh sức khỏe tài chính của doanh nghiệp | ### 3. Dữ liệu vĩ mô & Hàng hóa | Chức năng | vnstock (Miễn phí) | vnstock_data (Tài trợ) | | :------------------------------- | :----------------- | :----------------------------------------------- | | Chỉ số kinh tế vĩ mô | Không hỗ trợ | Đầy đủ thông số GDP, CPI, FDI, xuất nhập khẩu... | | Tỷ giá & Lãi suất liên ngân hàng | Không hỗ trợ | Dữ liệu được cập nhật liên tục | | Giá hàng hóa thế giới & VN | Không hỗ trợ | Giá thép, dầu thô, nông sản, kim loại quý... | --- ## Giải đáp thắc mắc thường gặp ### 1. Khắc phục lỗi "Đã nâng cấp nhưng vẫn bị giới hạn 60 yêu cầu/phút" Đây là bối rối phổ biến nhất của các thành viên sau khi tham gia gói tài trợ. Mặc dù tài khoản của bạn đã được kích hoạt thành công trên hệ thống, bạn vẫn thấy thông báo sử dụng bản **Community** và bị giới hạn **60 yêu cầu/phút**. **Nguyên nhân cốt lõi** Bạn đang chạy code dựa trên thư viện `vnstock` công khai (cài bằng lệnh `pip install vnstock` thông thường) và thực hiện xác thực bằng hàm `register_user()`. Thư viện miễn phí `vnstock` **không thể tự chuyển đổi** hoặc mở rộng tính năng của gói tài trợ. Các gói tài trợ sử dụng một bộ thư viện độc lập cần cài đặt riêng nhưng hỗ trợ chuyển đổi code dễ dàng. **Cách xử lý** 1. **Cài đặt thư viện tài trợ:** Bộ thư viện dành cho nhà tài trợ là các gói mã nguồn riêng (như `vnstock_data`, `vnstock_ta`, `vnstock_pipeline`), không thể cài đặt qua lệnh `pip install vnstock_data` thông thường. Bạn bắt buộc phải cài đặt thông qua trình cài đặt riêng tại trang [Cài đặt gói tài trợ](/onboard-member/cai-dat-go-loi). 2. **Thay đổi câu lệnh Import trong code:** Sau khi cài đặt thành công, hãy cập nhật lại toàn bộ mã nguồn của bạn để import từ thư viện mới: - **Cách cũ (Bản Cộng đồng):** ```python from vnstock import Quote, Listing ``` - **Cách mới (Bản Mở rộng):** ```python from vnstock_data import Market, Reference ``` Khi bạn import từ `vnstock_data`, hệ thống sẽ tự động nhận diện API Key và áp dụng đúng hạn mức truy cập của gói tài trợ (180 đến 600 yêu cầu/phút tương ứng với hạng Bronze, Silver, Golden, Diamond). ### 2. Chuyển đổi mã nguồn từ Bản Cộng đồng sang Bản Mở rộng Hầu hết các chức năng trên bản Mở rộng được thiết kế tương thích ngược với bản Cộng đồng giúp bạn dễ dàng chuyển đổi chỉ bằng cách đổi tên thư viện khi nạp lệnh. **Lưu ý về cấu trúc dữ liệu tài chính (nguồn VCI)** Riêng đối với dữ liệu tài chính lấy từ nguồn VCI, cấu trúc bảng dữ liệu trả về giữa bản Cộng đồng và bản Mở rộng sẽ có sự khác biệt nhỏ về tên cột hoặc định dạng. Bạn cần lưu ý điều chỉnh lại các đoạn code xử lý bảng dữ liệu (DataFrame) sau khi chuyển đổi sang bản Mở rộng đối với nguồn này. Vnstock cung cấp sẵn Agent Skill hỗ trợ chuyển đổi code tự động tại Agent Guide. --- ## Document: Phân Tích Chuyên Sâu (Insights)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
## 📌 Tổng Quan **Insights Layer** cung cấp **xếp hạng top cổ phiếu** và **bộ lọc chứng khoán** để nhà đầu tư nhận diện cơ hội và xu hướng thị trường. > **Lưu ý**: Nhóm chức năng định giá (P/E, P/B toàn thị trường) đã được chuyển sang **[nhóm lệnh Analytics](07-analytics-layer.md)** từ phiên bản Unified UI mới. Nếu trước đây bạn dùng `Insights().valuation`, vui lòng chuyển sang `Analytics().valuation(index)`. ### 🏗️ Cấu Trúc Nhóm Lệnh ```python Insights() ├── .ranking # Xếp hạng top cổ phiếu ├── .screener # Bộ lọc chứng khoán ├── .sentiment # Tâm lý thị trường (Experimental) ├── .flow # Dòng tiền thị trường (Experimental) ├── .sector() # Phân tích ngành (Experimental) └── .equity() # Phân tích cổ phiếu (Experimental) ``` ## 1. Xếp hạng (Ranking) Xếp hạng top cổ phiếu theo các tiêu chí khác nhau: tăng giá, giảm giá, khối lượng, nước ngoài, v.v. **Source:** VND **Nhóm lệnh:** `insights.ranking` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | ---------------- | ---------------- | ----------------------------------- | --------- | | `gainer()` | `index`, `limit` | Top cổ phiếu tăng giá | DataFrame | | `loser()` | `index`, `limit` | Top cổ phiếu giảm giá | DataFrame | | `value()` | `index`, `limit` | Top cổ phiếu theo giá trị giao dịch | DataFrame | | `volume()` | `index`, `limit` | Top cổ phiếu theo khối lượng | DataFrame | | `foreign_buy()` | `date`, `limit` | Top nước ngoài mua nhiều | DataFrame | | `foreign_sell()` | `date`, `limit` | Top nước ngoài bán nhiều | DataFrame | | `deal()` | `index`, `limit` | Top giao dịch thỏa thuận | DataFrame | **Parameters:** - `index` (str, optional): Chỉ số lọc (ví dụ: `'VNINDEX'`, `'HNX'`). Mặc đình lấy toàn thị trường. - `limit` (int, optional): Số lượng kết quả. Mặc định 10. - `date` (str, optional): Ngày giao dịch (YYYY-MM-DD). **Ví Dụ** ```python from vnstock_data import Insights ins = Insights() df_gainers_vn = ins.ranking.gainer(index='VNINDEX', limit=1) print(df_gainers_vn) ``` | symbol | exchange | last_price | last_updated | price_change_1d | price_change_pct_1d | total_value | avg_volume_20d | volume_spike_20d_pct | | :----- | :------- | ---------: | :--------------- | --------------: | ------------------: | ----------: | -------------: | -------------------: | | HID | HOSE | 4.65 | 2026-05-15 10:38 | 0.3 | 6.89655 | 7.35031e+08 | 446655 | 35.9562 | df_losers = ins.ranking.loser() print(df_losers) df_volume = ins.ranking.volume() print(df_volume) ```python df_foreign_buy = ins.ranking.foreign_buy(limit=1) print(df_foreign_buy) ``` | symbol | date | net_value | | :----- | :--------- | ----------: | | TCB | 2026-05-15 | 4.11252e+10 | ```python df_foreign_sell = ins.ranking.foreign_sell() print(df_foreign_sell) df_deals = ins.ranking.deal() print(df_deals) ``` --- ## 2. Bộ lọc chứng khoán (Screener) Bộ lọc cổ phiếu cho phép lọc nhanh danh sách các mã cổ phiếu bạn quan tâm với bộ tiêu chí được hỗ trợ. Người dùng có thể nạp điều kiện lọc khi gọi API bằng cách truyền `filters` cấu hình bộ lọc nhằm rút ngắn thời gian và độ lớn dữ liệu tải về. (Mặc định nếu chạy không có tham số API sẽ kết hợp rất nhiều tiêu chí với biên độ lớn, đôi khi trả về rất ít kết quả). **Source:** VCI **Nhóm lệnh:** `insights.screener` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | ------------ | ------------------ | ------------------------------------------------- | --------- | | `criteria()` | `lang` | Danh sách giải thích tên cột và cấu hình (vi/en) | DataFrame | | `filter()` | `filters`, `limit` | Dữ liệu screener theo bộ lọc hoặc toàn thị trường | DataFrame | **Parameters:** - `filters` (List[Dict], optional): Payload bộ lọc tùy chỉnh (là danh sách các tiêu chí lọc). Nếu không truyền, hệ thống sẽ gọi bộ lọc mặc định rộng nhất. - `lang` (str): Ngôn ngữ ('vi' hoặc 'en'). Mặc định 'vi'. - `limit` (int): Số lượng bản ghi tối đa. Mặc định 2000. **Bảng Tham Chiếu Cấu Trúc Bộ Lọc (Filters Payload)** Cấu trúc JSON cơ bản của `filters` (là một danh sách các dictionary) như sau: ```json [ { "name": "TÊN_TIÊU_CHÍ_TỪ_HÀM_CRITERIA", "extraName": "TÊN_BỔ_SUNG_NẾU_CÓ", "conditionOptions": [ {"type": "value", "value": "GIÁ_TRỊ_LỰA_CHỌN"}, {"from": 0, "to": 10} ] } ] ``` **Lưu ý quan trọng**: Các `field_name` và `extraName` ở bảng dưới đây dùng để cấu hình `filters` khi gửi request. Khi dữ liệu trả về thành DataFrame, tên cột sẽ tự động chuyển sang định dạng `snake_case` (ví dụ: `priceEma` + `ema20` sẽ thành cột `price_ema_20`, `ema20Ema50` sẽ thành cột `ema_20_ema_50`). Vui lòng xem [Schema Reference](schema/06-insights.md) để biết chính xác tên cột của kết quả đầu ra. Tất cả các tiêu chí lọc được hệ thống hỗ trợ bạn có thể tìm thấy ở bảng dưới đây (được rút trích từ bộ tiêu chí đầy đủ của hàm `criteria()`): | Phân Loại | Tiêu Chí | `field_name` | `extraName` / `extraName2` | Kiểu Filter (conditionOptions) | Ví dụ | | ------------------------ | ----------------------------- | ------------------------- | -------------------------- | ------------------------------ | ---------------------------------------------- | | **Thông tin chung** | Sàn giao dịch | `exchange` | | chọn giá trị (hsx, hnx, upcom) | `{"type": "value", "value": "hsx"}` | | | Nhóm ngành cấp 1 | `sectorLv1` | | chọn mã ngành | `{"type": "value", "value": "1000"}` | | | Vốn hóa (VND) | `marketCap` | | khoảng giá trị | `{"from": 0, "to": 1000000000}` | | | Thị giá | `marketPrice` | | khoảng giá trị | `{"from": 10000, "to": 50000}` | | **Giá & Khối lượng** | % Biến động giá hàng ngày | `dailyPriceChangePercent` | | khoảng giá trị | `{"from": -5, "to": 5}` | | | Giá trị GD trung bình | `adtv` | `30Days` | khoảng giá trị | `{"from": 1e9, "to": 5e9}` | | | Khối lượng TB | `avgVolume` | `30Days` | khoảng giá trị | `{"from": 100000, "to": 2000000}` | | | Đột biến KL (vs TB) | `esVolumeVsAvgVolume` | `30Days` | khoảng giá trị (%) | `{"from": 20, "to": 100}` | | | Tỷ suất lợi nhuận | `priceReturn` | `3Month` | khoảng giá trị (%) | `{"from": 5, "to": 20}` | | | Hiệu suất vs VN-Index | `outperformsIndex` | `3Month` | khoảng giá trị (%) | `{"from": 0, "to": 15}` | | | Mức biến động giá | `priceFluctuation` | `30Days` | khoảng giá trị (%) | `{"from": 0, "to": 10}` | | **Phân tích kỹ thuật** | Sức mạnh giá (Stock Strength) | `stockStrength` | | khoảng giá trị | `{"from": 50, "to": 100}` | | | Sức mạnh tương đối (RS) | `rs` | `3Month` | khoảng giá trị | `{"from": 70, "to": 100}` | | | RSI | `rsi` | | khoảng giá trị | `{"from": 30, "to": 70}` | | | Giá so với EMA | `priceEma` | `ema20` | khoảng giá trị (%) | `{"from": -5, "to": 5}` | | | Tương quan EMA20 & EMA50 | `ema20Ema50` | | khoảng giá trị (%) | `{"from": 0, "to": 5}` | | | Tương quan EMA50 & EMA200 | `ema50Ema200` | | khoảng giá trị (%) | `{"from": 0, "to": 5}` | | | MACD | `macd` | | khoảng giá trị | `{"from": 0, "to": 5}` | | | MACD Histogram | `histogram` | | khoảng giá trị | `{"from": 0, "to": 1}` | | | ADX | `adx` | | khoảng giá trị | `{"from": 25, "to": 100}` | | | Xu hướng cổ phiếu | `stockTrend` | | chọn giá trị string | `{"type": "value", "value": "STRONG_UPTREND"}` | | | Xu hướng AO (Awesome Osc) | `aoTrend` | | chọn giá trị string | `{"type": "value", "value": "ABOVE_ZERO"}` | | **Định giá & Tài chính** | P/E cơ bản | `ttmPe` | | khoảng giá trị | `{"from": 5, "to": 15}` | | | P/B cơ bản | `ttmPb` | | khoảng giá trị | `{"from": 0.5, "to": 2.5}` | | | ROE | `ttmRoe` | | khoảng giá trị (%) | `{"from": 15, "to": 50}` | | | Tăng trưởng LNST (Mẹ) | `npatmiGrowth` | `Yoy`, `Qm1` (extraName2) | khoảng giá trị (%) | `{"from": 10, "to": 100}` | | | Tăng trưởng doanh thu | `revenueGrowth` | `Yoy` | khoảng giá trị (%) | `{"from": 10, "to": 100}` | | | Biên Lợi nhuận ròng | `netMargin` | | khoảng giá trị (%) | `{"from": 10, "to": 100}` | | | Biên Lợi nhuận gộp | `grossMargin` | | khoảng giá trị (%) | `{"from": 15, "to": 100}` | **🤖 Mẹo: Dùng AI Để Viết Bộ Lọc** Do số lượng tiêu chí lọc tương đối nhiều, bạn nên yêu cầu AI viết cấu trúc payload JSON `filters` bằng cách cung cấp danh sách cột từ hàm `criteria()`. **Prompt mẫu:** > "Tôi đang dùng thư viện vnstock_data, hàm `ins.screener.filter(filters=...)` cho phép truyền payload JSON để lọc cổ phiếu từ máy chủ. Dưới đây là danh sách tiêu chí lấy từ hàm `criteria()`: > > [Copy/paste kết quả từ hàm `ins.screener.criteria().to_csv()` hoặc `to_json()` vào đây]. > > Hãy soạn cho tôi một danh sách Python (cấu trúc JSON array) để lọc các cổ phiếu thuộc sàn HSX, có ROE > 15%, P/E < 10, và khối lượng giao dịch trung bình 30 ngày > 1,000,000." **Ví Dụ** ```python from vnstock_data import Insights ins = Insights() custom_filters = [ { "name": "exchange", "conditionOptions": [{"type": "value", "value": "hsx"}] }, { "name": "ttmRoe", "conditionOptions": [{"from": 15, "to": 100}] }, { "name": "ttmPe", "conditionOptions": [{"from": 0, "to": 10}] } ] df_filtered = ins.screener.filter(filters=custom_filters) print(f"Cổ phiếu HSX, P/E < 10, ROE > 15: {len(df_filtered)}") print(df_filtered[['ticker', 'ttm_pe', 'ttm_roe']].head()) from vnstock_data import Listing lst_vci = Listing(source="vci") icb_df = lst_vci.industries_icb() lv1_sectors = icb_df[icb_df['level'] == 1] print("Danh sách mã ngành cấp 1:\n", lv1_sectors[['icb_code', 'icb_name']].head()) sector_code = "1000" sector_filter = [ { "name": "sectorLv1", "conditionOptions": [{"type": "value", "value": sector_code}] } ] df_sector = ins.screener.filter(filters=sector_filter) print(f"\nCổ phiếu thuộc nhóm ngành {sector_code}: {len(df_sector)}") print(df_sector[['ticker', 'exchange', 'sector_lv1']].head()) df_all = ins.screener.filter() print(f"Total stocks: {len(df_all)}") cheap_good = df_all[ (df_all['pe'] < 10) & (df_all['roe'] > 15) ] print(cheap_good[['symbol', 'pe', 'roe']].head()) ``` | symbol | exchange | ref_price | ceiling | price | floor | accumulated_value | accumulated_volume | market_cap | price_change_percent | avg_value_30d | avg_value_10d | avg_volume_30d | est_volume | volume_breakout_30d | pe | pb | roe | profit_growth_yoy | revenue_growth_yoy | net_margin | gross_margin | | :----- | :------- | --------: | ------: | ----: | ----: | ----------------: | -----------------: | ----------: | -------------------: | ------------: | ------------: | -------------: | ---------: | ------------------: | ------: | -------: | ------: | ----------------: | -----------------: | ---------: | -----------: | | ABB | UPCOM | 15200 | 17400 | 15200 | 13000 | 1.65051e+09 | 107900 | 1.57326e+13 | 0 | 1.23616e+10 | -86.8034 | 831840 | 302733 | -63.6068 | 4.69571 | 0.986995 | 21.1886 | 260.74 | 49.4604 | 34.5488 | 68.6208 | --- ## 3. Tâm lý thị trường (Sentiment) Cung cấp các chỉ báo vĩ mô về tâm lý thị trường. **Nhóm lệnh:** `insights.sentiment` | Method | Tham Số | Mô Tả | Return | | ---------------- | ---------- | ---------------------------------------------- | --------- | | `breadth()` | `exchange` | Độ rộng thị trường (tăng/giảm, trên MA20/MA50) | DataFrame | | `contribution()` | `exchange` | Top cổ phiếu đóng góp vào điểm số chỉ số | DataFrame | | `heatmap()` | `exchange` | Bản đồ nhiệt thị trường | DataFrame | ```python df_breadth = ins.sentiment.breadth(exchange='HOSE') ``` --- ## 4. Dòng tiền (Flow) Cung cấp phân tích dòng tiền của các thành phần tham gia thị trường. **Nhóm lệnh:** `insights.flow` | Method | Tham Số | Mô Tả | Return | | --------------- | ---------------------- | ------------------------------------- | --------- | | `foreign()` | `exchange`, `group_by` | Dòng tiền mua/bán ròng của khối ngoại | DataFrame | | `proprietary()` | `exchange`, `group_by` | Dòng tiền tự doanh | DataFrame | | `active()` | `exchange`, `group_by` | Dòng tiền chủ động (aggressor) | DataFrame | ```python df_foreign = ins.flow.foreign(exchange='HOSE', group_by='stock') ``` --- ## 5. Phân tích ngành (Sector) Cung cấp công cụ phân tích cấp độ ngành (Yêu cầu `ind_code`). **Nhóm lệnh:** `insights.sector` | Method | Tham Số | Mô Tả | Return | | ------------------ | ------- | ------------------------------------- | --------- | | `valuation()` | | Chỉ số định giá của ngành | DataFrame | | `members()` | | Danh sách các cổ phiếu thành phần | DataFrame | | `rrg()` | | Động lượng RRG của ngành | DataFrame | | `flow()` | | Dòng tiền cấp độ ngành | DataFrame | | `index_intraday()` | | Giá trị chỉ số ngành intraday | DataFrame | | `flow_intraday()` | | Dòng tiền chủ động intraday của ngành | DataFrame | ```python df_bank_val = ins.sector('bank').valuation() ``` --- ## 6. Phân tích cổ phiếu (Equity) Cung cấp công cụ phân tích cấp độ cổ phiếu (Yêu cầu `symbol`). **Nhóm lệnh:** `insights.equity` | Method | Tham Số | Mô Tả | Return | | ---------------------- | ------- | ----------------------------------------------------- | --------- | | `peer_compare()` | | So sánh định giá với các công ty cùng ngành | DataFrame | | `order_flow()` | `mode` | Phân bổ dòng lệnh (`mode`: 'by_price' hoặc 'by_time') | DataFrame | | `order_flow_history()` | | Lịch sử giao dịch và phân bổ dòng tiền | DataFrame | | `rrg()` | | Động lượng RRG của cổ phiếu | DataFrame | ```python df_acb_comp = ins.equity('ACB').peer_compare() ``` --- ## Document: Kiến trúc thư viện
Thư viện vnstock_data được thiết kế với cấu trúc dạng mô-đun, dễ mở rộng, dễ tích hợp, và dễ chuyển đổi nguồn dữ liệu chỉ qua một tham số cấu hình.

Đây là bộ công cụ dữ liệu chứng khoán - kinh tế - tài sản toàn diện, sẵn sàng hỗ trợ bạn xây dựng mọi sản phẩm từ phân tích, hỗ trợ giao dịch, đến dự báo thị trường.
## Triết Lý Thiết Kế 3 Lớp Mọi dòng code trong `vnstock_data` đều hướng tới một mục tiêu duy nhất: **Giúp bạn tập trung vào phân tích tài chính thay vì xử lý mã nguồn.** | Lớp Kiến Trúc | Bản Chất Kỹ Thuật | Ý nghĩa | | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Giao diện hợp nhất (Unified UI)** | Lớp trên cùng, tổ chức lại toàn bộ dữ liệu thành cấu trúc nghiệp vụ (Market, Reference, Fundamental...). | **Lập trình như một chuyên gia tài chính:** Trải nghiệm xuyên suốt, dễ tìm kiếm chức năng qua `show_api()`, gọi hàm liền mạch qua dấu chấm `.` để phân nhánh hàm mà không cần quan tâm tới cài đặt nguồn dữ liệu. | | **Giao tiếp chung (Core Adapter)** | Lớp trung gian tạo ra một chuẩn giao tiếp duy nhất giữa code của bạn và mọi nguồn cấp dữ liệu. | **Tự do chuyển đổi nguồn cấp dữ liệu:** Thay đổi nhà cung cấp (từ VCI sang VND, MAS) chỉ đơn giản là thay đổi giá trị `source=` khi khởi tạo class. Code được hạn chế tối đa khả năng lỗi, tăng tính bền vững và linh hoạt cho dự án. | | **Module Nguồn cấp (Implementation)** | Lớp dưới cùng giao tiếp trực tiếp với hệ thống API gốc đặc thù của từng nguồn cấp. | **Quyền kiểm soát tuyệt đối:** Cho phép người dùng có kinh nghiệm có thể khai thác tối đa các chức năng của thư viện được đặt sâu trong mã nguồn. | ## Hướng Dẫn Sử Dụng

vnstock_data hỗ trợ 3 cách tiếp cận khi gọi dữ liệu, được tổ chức theo cấu trúc 3 lớp. Người dùng cũ từ thư viện miễn phí của Vnstock có thể nâng cấp mượt mà chỉ bằng cách thay đổi câu lệnh import. Để tận dụng toàn bộ sức mạnh và tiện ích mới nhất, Vnstock giới thiệu Unified UI là cách gọi lệnh mặc định.

```python # Câu lệnh cũ from vnstock import Market, Reference, Fundamental # Câu lệnh dùng cho bản Mở rộng (Đổi tên thư viện là được) from vnstock_data import Market, Reference, Fundamental ``` ### 1. Giao diện hợp nhất (Unified UI - Mặc định) > Kiến trúc tiêu chuẩn mới nhất, vận hành mượt mà, cảm hứng thiết kế từ cơ chế phân loại của Bloomberg Terminal, FIX. Đây là cách tương tác với dữ liệu theo các miền nghiệp vụ rõ ràng, giúp lập trình viên thao tác một cách tự nhiên mà không cần bận tâm về cấu trúc kỹ thuật bên dưới. ```python title="(.venv)" from vnstock_data import Market, Reference, Fundamental # Ví dụ tra cứu giá lịch sử thông qua Market Layer df = Market.quote(symbol="VCI") \ .history(start="2024-02-01", end="2025-04-18", interval="1D") ``` **Ưu điểm**: - Trải nghiệm lập trình liền mạch với khả năng gọi chuỗi lệnh (method chaining). - Các nhóm dữ liệu được tổ chức logic theo sát kiến thức tài chính. - Hỗ trợ hàm `show_api()` để dễ dàng tự khám phá chức năng mà không cần mở tài liệu từ website để tra cứu. ### 2. Sử dụng cổng Giao tiếp chung (Core Adapter) > **Tối ưu cho sự linh hoạt, hoán đổi nguồn nhà cung cấp, phù hợp người dùng nâng cấp từ bản cũ.** Phương thức này dành riêng cho người dùng quen thuộc với phong cách của phiên bản Vnstock trước đây. Chỉ cần điều chỉnh phần nạp thư viện, gần như toàn bộ tính năng và code hiện tại của bạn sẽ tiếp tục hoạt động nguyên vẹn. ```python title="(.venv)" from vnstock_data import Quote, Trading, Finance, Listing, Company, Macro quote = Quote(source="vci", symbol="VCI") df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D") ``` **Ưu điểm**: - Chuyển đổi nhanh chóng từ bản Cộng đồng. - Linh hoạt đối chiếu và thay đổi nhà cung cấp (từ VCI sang VND, MAS...). ### 3. Sử dụng trực tiếp Module Nguồn cấp > **Kiểm soát chặt chẽ nhất, tối ưu cho sự ổn định ở môi trường triển khai sản phẩm.** Thay vì dùng giao tiếp chung, bạn gọi thẳng dữ liệu từ module bên trong của từng nhà cung cấp. ```python title="(.venv)" from vnstock_data.explorer.vci import Quote quote = Quote(symbol="VCI") df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D") ``` **Ưu điểm**: - Giảm thiểu hoàn toàn rủi ro chức năng không hỗ trợ chéo. - Truy cập vào những trường dữ liệu đặc thù hay tính năng ẩn chỉ có riêng ở một nhà cung cấp cụ thể. ## Tra cứu API Thay vì phải tra cứu tài liệu rời rạc, **Unified UI** gom toàn bộ thư viện lại thành một cây tính năng. Nhập `show_api()` và bạn sẽ có toàn cảnh bức tranh dữ liệu. ```python title="(.venv) mrthinh@Thinhs-MacBook-Air ~ % python" from vnstock_data import show_api, show_doc >>> show_api() ```
Hiển thị kết quả API Tree ```txt API STRUCTURE TREE - VNSTOCK_DATA (Unified UI Endpoints) vnstock_data ├── Reference │ ├── bond # Access bond reference data. │ │ ├── list() # List bonds available in the market. │ ├── company() # Access company-specific reference data. │ │ ├── events() [VCI] -> DataFrame # Get company events. │ │ ├── info() [VCI] -> DataFrame # Get company info/overview. │ │ ├── margin_ratio() [KBS] -> DataFrame # Get margin lending ratio for the company across brokers. │ │ ├── news() [VCI] -> DataFrame # Get company news. │ │ ├── officers() [VCI] -> DataFrame # Get company officers. │ │ ├── shareholders() [VCI] -> DataFrame # Get company shareholders. │ │ ├── subsidiaries() [VCI] -> DataFrame # Get company subsidiaries. │ ├── equity # Access equity reference data. │ │ ├── list() [VCI] -> DataFrame # List all equity symbols. │ │ ├── list_by_exchange() -> DataFrame # List all equities organized by exchange. │ │ ├── list_by_group() -> DataFrame # List equities by group (e.g., VN30, HOSE). │ │ ├── list_by_industry() -> DataFrame # List equities by industry (ICB classification). │ ├── etf # Access ETF reference data. │ │ ├── list() [KBS] -> DataFrame # List all Exchange-Traded Funds (ETFs) available in the market. │ ├── events # Access events reference data (calendar, etc.). │ │ ├── calendar() [VCI] -> DataFrame # Retrieve events calendar (dividends, AGM, new listings, ...) from the default data source. │ │ ├── market() -> DataFrame # Retrieve special stock market events (holidays, system incidents, ...) │ ├── fund # Master data for Mutual Funds (Chứng Chỉ Quỹ). │ │ ├── list() [FMARKET] -> DataFrame # Extracts the list of all available mutual funds. │ ├── futures() # Access index futures reference data (listing or symbol-specific info). │ │ ├── info() [KBS] -> DataFrame # Get info and realtime information for the specific index future. │ │ ├── list() [VCI] -> DataFrame # List all available futures indices with metadata. │ ├── index # Access index reference data. │ │ ├── groups() [KBS] -> DataFrame # List all supported index groups and categories. │ │ ├── list() [KBS] -> DataFrame # List all standardized market indices with metadata. │ │ ├── list_by_group() -> DataFrame # List market indices by group/category. │ │ ├── members() [KBS] -> Series # List constituents/members of the specified index. │ ├── industry # Access industry reference data. │ │ ├── list() [VCI] -> DataFrame # List ICB industry classifications for all symbols in the market. │ │ ├── sectors() [VCI] -> DataFrame # List all symbols by their industry sectors. │ ├── market # Access live market status. │ │ ├── status() [MAS] -> DataFrame # Retrieve live stock market status (OPEN, CLOSED, ATO, ATC, etc.) │ ├── search # Access global symbol search. │ │ ├── symbol() [MSN] -> DataFrame # Retrieves a list of symbols from the market matching the query. │ └── warrant() # Access covered warrant reference data (info, specifications, pricing). │ ├── info() [KBS] -> DataFrame # Get info and realtime information for the specific covered warrant. │ ├── list() [VCI] -> DataFrame # List all available covered warrants. ├── Market │ ├── commodity() # Access commodity market data (e.g., 'GC=F'). │ │ ├── ohlcv() [MSN] -> DataFrame # Historical OHLCV bars. │ │ ├── quote() -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── summary() -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ ├── crypto() # Access crypto market data (e.g., 'BTC'). │ │ ├── ohlcv() [MSN] -> DataFrame # Historical OHLCV bars. │ │ ├── quote() -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── summary() -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ ├── equity() # Access equity market data. │ │ ├── block_trades() [KBS] -> DataFrame # Real-time or historical data for negotiated/block trades (giao dịch thoả thuận). │ │ ├── foreign_flow() [VCI] -> DataFrame # Historical or daily foreign buy/sell volume and value. │ │ ├── odd_lot() [KBS] -> DataFrame # Real-time pricing or trades for odd-lot execution (Lô lẻ). │ │ ├── ohlcv() [KBS] -> DataFrame # Historical OHLCV bars. │ │ ├── order_book() [KBS] -> DataFrame # Order book levels (Best Bid/Ask L2/L3). │ │ ├── proprietary_flow() [VCI] -> DataFrame # Trade data for proprietary desks (Tự doanh). │ │ ├── quote() [KBS] -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── session_stats() [VCI] -> DataFrame # End-of-session aggregate statistics. │ │ ├── summary() [KBS] -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ │ ├── trade_history() [KBS] -> DataFrame # Historical trading statistics (price, volume, value) for Equities. │ │ ├── trades() [KBS] -> DataFrame # Real-time or intraday tick-by-tick trading tape (Time & Sales). │ │ ├── volume_profile() [KBS] -> DataFrame # Aggregated volume distributed across executed price levels (Volume Profile). │ ├── etf() # Access ETF market data. │ │ ├── ohlcv() [KBS] -> DataFrame # Historical OHLCV bars. │ │ ├── order_book() [KBS] -> DataFrame # Order book levels (Best Bid/Ask L2/L3). │ │ ├── quote() [KBS] -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── session_stats() [VCI] -> DataFrame # End-of-session aggregate statistics. │ │ ├── summary() [KBS] -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ │ ├── trades() [KBS] -> DataFrame # Real-time or intraday tick-by-tick trading tape (Time & Sales). │ ├── forex() # Access forex market data (e.g., 'USDVND'). │ │ ├── ohlcv() [MSN] -> DataFrame # Historical OHLCV bars. │ │ ├── quote() -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── summary() -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ ├── fund() # Access historical NAVs and portfolio compositions for a specific Mutual Fund. │ │ ├── asset_holding() [FMARKET] -> DataFrame # Extracts the asset allocation (Equities vs Cash/Bonds) of the fund. │ │ ├── industry_holding() [FMARKET] -> DataFrame # Extracts the industry weighting inside the fund's portfolio. │ │ ├── top_holding() [FMARKET] -> DataFrame # Extracts the top equity/bond holdings of the fund. │ ├── futures() # Access futures market data. │ │ ├── ohlcv() [KBS] -> DataFrame # Historical OHLCV bars. │ │ ├── order_book() [KBS] -> DataFrame # Order book levels (Best Bid/Ask L2/L3). │ │ ├── quote() [KBS] -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── summary() [KBS] -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ │ ├── trades() [KBS] -> DataFrame # Real-time or intraday tick-by-tick trading tape (Time & Sales). │ ├── index() # Access index market data. │ │ ├── ohlcv() [KBS] -> DataFrame # Historical OHLCV bars. │ │ ├── quote() [KBS] -> DataFrame # Real-time single-symbol pricing snapshot. │ │ ├── summary() [KBS] -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ └── warrant() # Access warrant market data. │ ├── ohlcv() [KBS] -> DataFrame # Historical OHLCV bars. │ ├── order_book() [KBS] -> DataFrame # Order book levels (Best Bid/Ask L2/L3). │ ├── quote() [KBS] -> DataFrame # Real-time single-symbol pricing snapshot. │ ├── summary() [KBS] -> DataFrame # Stock Info / Snapshot summary metrics including pricing, │ ├── trades() [KBS] -> DataFrame # Real-time or intraday tick-by-tick trading tape (Time & Sales). ├── Fundamental │ └── equity() # Access financial data for a specific corporate equity (Fundamental Layer). │ ├── balance_sheet() [KBS] -> DataFrame # Extracts Balance Sheet. │ ├── cash_flow() [KBS] -> DataFrame # Extracts Cash Flow statement. │ ├── income_statement() [KBS] -> DataFrame # Extracts Income Statement. │ ├── note() [VCI] -> DataFrame # Extracts Footnotes (Thuyết minh Báo cáo tài chính). │ ├── ratio() [KBS] -> DataFrame # Extracts key financial ratios (P/E, ROE, Debt/Equity, etc.). ├── Analytics │ └── valuation() # Access historical valuation multiples for market indices (Analytics Layer). │ ├── evaluation() [VND] -> DataFrame # Retrieves an overview of the market with both P/E and P/B ratios. │ ├── pb() [VND] -> DataFrame # Retrieves P/B (Price-to-Book) ratio data. │ ├── pe() [VND] -> DataFrame # Retrieves P/E (Price-to-Earnings) ratio data. ├── Macro │ ├── commodity() # Access global and local commodity prices (Macro Layer - Commodity Domain). │ │ ├── coke() [SPL] -> DataFrame # Coke (Coal) prices. │ │ ├── corn() [SPL] -> DataFrame # Corn prices. │ │ ├── fertilizer_ure() [SPL] -> DataFrame # Fertilizer URE prices. │ │ ├── gas() -> DataFrame # Gas prices. Note: 'GLOBAL' returns natural gas futures. 'VN' returns aggregated RON/DO prices. │ │ ├── gold() -> DataFrame # Gold prices. │ │ ├── iron_ore() [SPL] -> DataFrame # Iron ore prices. │ │ ├── oil_crude() [SPL] -> DataFrame # Crude Oil prices. │ │ ├── pork() -> DataFrame # Pork prices. 'VN' for local North Pig, 'CHINA' for China market. │ │ ├── soybean() [SPL] -> DataFrame # Soybean prices. │ │ ├── steel() -> DataFrame # Steel prices. 'GLOBAL' for HRC1!, 'VN' for D10. │ │ ├── sugar() [SPL] -> DataFrame # Sugar prices. │ ├── currency() # Access foreign exchange rates and interest rate data (Macro Layer - Currency Domain). │ │ ├── exchange_rate() [MBK] -> DataFrame # Foreign exchange rates. │ │ ├── interest_rate() [MBK] -> DataFrame # Interest rates data. │ └── economy() # Access standard macroeconomic indicators (Macro Layer - Economy Domain). │ ├── cpi() [MBK] -> DataFrame # Consumer Price Index data. │ ├── fdi() [MBK] -> DataFrame # Foreign Direct Investment data. │ ├── gdp() [MBK] -> DataFrame # GDP data. │ ├── import_export() [MBK] -> DataFrame # Import/Export macro data. │ ├── industry_prod() [MBK] -> DataFrame # Industrial Production data. │ ├── money_supply() [MBK] -> DataFrame # Money supply data. │ ├── population_labor() [MBK] -> DataFrame # Population and Labor data. │ ├── retail() [MBK] -> DataFrame # Retail macro data. └── Insights ├── ranking() # Access market ranking metrics - Top movers by various criteria (Insights Layer). │ ├── deal() [VND] -> DataFrame # Top 10 stocks with highest put-through/deal volume spikes. │ ├── foreign_buy() [VND] -> DataFrame # Top 10 stocks with highest foreign net buy value. │ ├── foreign_sell() [VND] -> DataFrame # Top 10 stocks with highest foreign net sell value. │ ├── gainer() [VND] -> DataFrame # Top 10 stocks with highest price increase. │ ├── loser() [VND] -> DataFrame # Top 10 stocks with highest price decrease. │ ├── value() [VND] -> DataFrame # Top 10 stocks with highest trading value. │ ├── volume() [VND] -> DataFrame # Top 10 stocks with highest volume spikes. └── screener() # Access stock screener functionality (Insights Layer). ├── criteria() [VCI] -> DataFrame # Retrieves the mapping list of criteria to explain field names (data columns). ├── filter() [VCI] -> DataFrame # Retrieves full market data (all stocks) with all available criteria (ratios, metrics) Tip: Sử dụng show_doc(node) để đọc docstring. [Navigation] = Intermediate methods returning domain objects ```
--- ## Document: Lịch sử phiên bản ## 06-09-2026 > Phát hành phiên bản v3.2.9 khắc phục các sai lệch của dữ liệu khớp lệnh trong phiên (`trades`/`intraday`), đặc biệt với nhóm phái sinh. - **Khối lượng khớp lệnh trở về đúng thực tế:** Khắc phục tình trạng tổng khối lượng bị gấp đôi so với số liệu sở công bố. - **Nhãn ATO/ATC chính xác hơn:** Nhận diện đúng phiên ATO 08:45–09:00 của hợp đồng tương lai, đồng thời không còn gán nhầm nhãn cho các lệnh khớp liên tục. Bổ sung nhãn `PLO` cho mã sàn HNX. - **Sửa lỗi giá và thời gian ở nguồn MAS:** Khắc phục tình trạng chỉ trả về vài chục dòng, sai đơn vị giá và mốc thời gian nhảy về năm 1970. - **Mặc định lấy trọn phiên cho phái sinh:** Nâng giới hạn mặc định lên 100.000 bản ghi để phủ hết phiên, thay vì 1.000 bản ghi chỉ đủ chạm cụm ATC cuối phiên. Thư viện cũng tự cảnh báo khi dữ liệu trả về chưa phủ hết phiên. - **Thêm nguồn khớp lệnh VND:** Hỗ trợ cả cổ phiếu, chứng quyền và hợp đồng tương lai, cấu trúc dữ liệu đồng nhất với các nguồn còn lại. - **Gọi mã phái sinh kiểu cũ vẫn ra dữ liệu:** Các mã như `VN30F1M` được tự động chuyển sang mã KRX ở mọi lớp truy xuất. Bổ sung `Market().future(...)` bên cạnh `Market().futures(...)`. - **Lưu ý về nguồn VCI:** Nhà cung cấp đã áp giới hạn 100 bản ghi mỗi lượt gọi cho dữ liệu khớp lệnh. Nếu cần dữ liệu cả phiên, bạn nên dùng KBS, MAS hoặc VND. - **Khôi phục cây API `show_api()`:** Cây hiển thị đầy đủ mọi nhóm tài sản kèm nguồn dữ liệu và mô tả chức năng của từng hàm.
Phiên bản này đổi nguồn mặc định của dữ liệu khớp lệnh cổ phiếu và làm số liệu khối lượng khác đi so với bản cũ. Xem hướng dẫn nâng cấp v3.2.9 để biết cần chỉnh gì.
## 16-08-2026 > Phát hành phiên bản v3.2.8 mang đến nâng cấp toàn diện cho hệ thống dữ liệu Báo cáo tài chính, chuẩn hoá hoàn toàn theo chuẩn mực kế toán VAS. - **Đồng nhất API Báo cáo tài chính (Finance):** Tất cả các nguồn cấp dữ liệu (VCI, MAS, KBS) giờ đây đã được đồng nhất về cùng một định dạng chuẩn **Tidy Data (Long-form)**, giúp loại bỏ hoàn toàn sự thiếu nhất quán giữa các nguồn. - **Chuẩn hoá mã định danh (Semantic ID):** Áp dụng bộ Taxonomy ID chuẩn mực (ví dụ: `BS_CASH_AND_PRECIOUS_METALS`) làm khoá chính, giúp mã nguồn phân tích định lượng không bị gãy sụp đổ khi tên hiển thị của chỉ tiêu thay đổi. - **Hệ thống tham số mới mạnh mẽ:** - Thay thế tham số `dropna` bằng `drop_empty`. - Hỗ trợ tuỳ chỉnh linh hoạt cấu trúc dữ liệu trả về thông qua tham số `format` (`'long'`, `'wide'`, `'time_series'`). - Thêm tham số `com_type` giúp hệ thống bóc tách chính xác báo cáo dựa trên loại hình công ty (`Regular`, `Bank`, `Securities`, `Insurance`) khi cơ chế nhận diện tự động không thành công. - **Nâng cấp tài liệu & Hướng dẫn (Migration):** Cung cấp bảng tham chiếu chi tiết và [tài liệu hướng dẫn nâng cấp](/docs/vnstock-data/nang-cap-phien-ban/v3.2.8) mã nguồn dành riêng cho các thay đổi của phiên bản cập nhật này. ## 03-08-2026 > Phát hành phiên bản v3.2.7 tập trung vào nâng cấp trải nghiệm truy xuất dữ liệu & vá lỗi - **Khắc phục lỗi tham số kỳ báo cáo cho Finance module - nguồn VCI**: Xử lý triệt để tình trạng dữ liệu báo cáo tài chính bị trộn lẫn. Hiện tại, khi gọi `Finance(..., period='year').balance_sheet()`, kết quả trả về sẽ hoàn toàn chuẩn xác theo cột năm (tránh lẫn với dữ liệu quý), giúp việc phân tích chuỗi thời gian liền mạch. - **Tự động lấy đủ dữ liệu giao dịch từ Trading module - nguồn CafeF**: Xóa bỏ giới hạn cứng 20 bản ghi mỗi trang của nguồn CafeF. Các hàm dữ liệu (lịch sử giá, giao dịch khối ngoại, tự doanh, thống kê đặt lệnh...) nay tự động lật trang ngầm để trả về đủ giới hạn `limit` bạn yêu cầu. - **Khắc phục lỗi cắt xén dữ liệu từ Trading module - nguồn VCI**: Xử lý tình trạng dữ liệu bị cắt cụt âm thầm (chỉ trả về ~100 dòng) khi gọi chuỗi thời gian dài. Giờ đây, chỉ cần truyền khoảng ngày `start` và `end`, thư viện sẽ tự động tính toán và phân trang ngầm để lấy trọn vẹn toàn bộ lịch sử giao dịch. ## 22-07-2026 > Phát hành `vnstock_data` phiên bản 3.2.6 giúp sửa lỗi và tối ưu hoá mã nguồn. - **Sửa lỗi trích xuất thuyết minh báo cáo tài chính (Nguồn VCI):** Cập nhật lại cấu trúc hàm trích xuất thuyết minh báo cáo tài chính để hàm hoạt động ổn định và trả về dữ liệu đầy đủ thay vì kết quả rỗng. ## 18-07-2026 > Phát hành `vnstock_data` phiên bản 3.2.5 mang đến cho bạn nhiều lựa chọn dữ liệu hơn và nâng cao độ ổn định của hệ thống. - **Thêm nguồn dữ liệu giao dịch mới:** Tích hợp thêm nguồn `asean` và `mbk` giúp bạn có thêm các lựa chọn đáng tin cậy khi phân tích dữ liệu lịch sử giao dịch. - **Mở rộng tra cứu thông tin doanh nghiệp:** Bổ sung tính năng lấy dữ liệu thông tin niêm yết từ nguồn CafeF giúp bạn dễ dàng theo dõi các thông tin quan trọng của doanh nghiệp. - **Trải nghiệm mượt mà hơn với nguồn ASEAN:** Khắc phục hoàn toàn tình trạng lỗi kết nối khi lấy dữ liệu các nhóm hàm Insight, Sector và Trading từ nguồn ASEAN. ## 16-07-2026 > Phát hành `vnstock_data` phiên bản 3.2.4 giúp quá trình truy xuất dữ liệu báo cáo tài chính từ nguồn KBS ổn định. - **Dữ liệu tài chính ổn định hơn:** Hệ thống giờ đây có khả năng tự động xử lý và phục hồi (fallback) khi nhà cung cấp dữ liệu KBS thay đổi định dạng, giúp bạn luôn lấy được đầy đủ báo cáo tài chính mà không lo bị ngắt quãng. ## 24-05-2026 > Phát hành vnstock_data phiên bản 3.2.0 và cập nhật đồng loạt các thư viện trong gói sponsor với những tinh chỉnh nhỏ giúp tăng tính ổn định của hệ thống. - **Tích hợp Toàn diện Dữ liệu ASEAN (Unified UI)**: - Tích hợp luồng dữ liệu từ trung tâm phân tích của Asean Securities, mở rộng mạnh mẽ năng lực phân tích và giúp người dùng tiếp cận dữ liệu với góc nhìn đa chiều: - **Insights**: Cung cấp bộ công cụ chuyên sâu đo lường tâm lý thị trường (`sentiment`: breadth, heatmap, contribution), theo vết dòng tiền (`flow`: foreign, proprietary, active). Đào sâu phân tích cấp độ Ngành (`sector`) và Cổ phiếu (`equity`) thông qua biểu đồ Relative Rotation Graph (`rrg`), định giá (`valuation`), so sánh ngang hàng (`peer_compare`), và phân tích dòng lệnh (`order_flow`). - **Vĩ mô & Hàng hoá (Macro)**: Thay thế lõi truy xuất dữ liệu Vĩ mô (Kinh tế, Tiền tệ) sang nguồn ASEAN với độ trễ thấp hơn. Tăng cường khả năng tiếp cận tức thời các chỉ số toàn cầu như Lợi suất trái phiếu (`bond_yield`), Lãi suất Fed (`fed_rate`), và các rổ hàng hoá phái sinh chuẩn quốc tế trực tiếp qua `Macro().global` và `Macro().commodity()`. - **Tương thích & Ổn định**: - Khi người dùng truy xuất các hàng hoá đặc thù của Việt Nam (VD: Vàng SJC, Thép D10, Lợn Hơi) qua tham số `market="VN"`, hệ thống tự động fallback mượt mà về nguồn SPL cũ, đảm bảo không bị gián đoạn trải nghiệm phân tích số liệu cục bộ. - **Trải nghiệm Phát triển**: Toàn bộ các endpoints mới được dán nhãn `[Experimental]` khi gọi lệnh `show_api()`, giúp các nhà phân tích phân biệt và nắm bắt nhanh chóng kho công cụ mới này. **Chi tiết cấu trúc API Tree (Các hàm mới & nâng cấp):** ```bash ├── Insights │ ├── equity() │ │ ├── order_flow() -> DataFrame # Phân bổ dòng tiền chủ động │ │ ├── order_flow_history() -> DataFrame # Lịch sử giao dịch & dòng lệnh │ │ ├── peer_compare() -> DataFrame # So sánh với các mã cùng ngành │ │ └── rrg() -> DataFrame # Sức mạnh tương đối (RRG) │ ├── flow │ │ ├── active() -> DataFrame # Dòng tiền chủ động mua/bán │ │ ├── foreign() -> DataFrame # Giao dịch khối ngoại (FII) │ │ └── proprietary() -> DataFrame # Giao dịch tự doanh │ ├── sector() │ │ ├── flow() -> DataFrame # Dòng tiền tổng hợp toàn ngành │ │ ├── flow_intraday() -> DataFrame # Dòng tiền ngành trong ngày │ │ ├── index_intraday() -> DataFrame # Chỉ số ngành trong ngày │ │ ├── members() -> DataFrame # Chỉ số tài chính của các mã trong ngành │ │ ├── rrg() -> DataFrame # Sức mạnh tương đối ngành (RRG) │ │ └── valuation() -> DataFrame # Tỷ số định giá ngành │ └── sentiment │ ├── breadth() -> DataFrame # Độ rộng thị trường │ ├── contribution() -> DataFrame # Top đóng góp điểm số │ └── heatmap() -> DataFrame # Bản đồ nhiệt toàn thị trường └── Macro ├── commodity() │ ├── coke() -> DataFrame # Giá Hợp đồng tương lai Than Cốc │ ├── corn() -> DataFrame # Giá Ngô Mỹ │ ├── gas() -> DataFrame # Khí tự nhiên / Xăng dầu VN │ ├── gold() -> DataFrame # Vàng thế giới / Vàng SJC │ ├── iron_ore() -> DataFrame # Quặng sắt Trung Quốc │ ├── listing() -> DataFrame # Danh sách hàng hoá hỗ trợ │ ├── oil_crude() -> DataFrame # Dầu thô WTI │ ├── pork() -> DataFrame # Giá Lợn Hơi VN / TQ │ ├── related_industry() -> DataFrame # Nhóm ngành liên quan Hàng hoá │ ├── related_stock() -> DataFrame # Nhóm cổ phiếu liên quan Hàng hoá │ ├── soybean() -> DataFrame # Giá Đậu nành Mỹ │ ├── steel() -> DataFrame # Thép HRC thế giới / Thép D10 VN │ └── sugar() -> DataFrame # Giá Đường London ├── currency() │ ├── deposit_rate() -> DataFrame # Lãi suất huy động │ ├── exchange_rate() -> DataFrame # Tỷ giá trung tâm │ ├── interbank_rate() -> DataFrame # Lãi suất liên ngân hàng │ ├── omo() -> DataFrame # Nghiệp vụ thị trường mở (OMO) │ └── policy_rate() -> DataFrame # Lãi suất điều hành ├── economy() │ ├── cpi() -> DataFrame # Chỉ số giá tiêu dùng (CPI) │ ├── credit() -> DataFrame # Tăng trưởng tín dụng │ ├── fdi() -> DataFrame # Vốn đầu tư trực tiếp nước ngoài │ ├── gdp() -> DataFrame # Tổng sản phẩm quốc nội (GDP) │ ├── import_export() -> DataFrame # Xuất nhập khẩu │ ├── money_supply() -> DataFrame # Cung tiền M2 │ ├── state_budget() -> DataFrame # Thu ngân sách nhà nước │ └── total_investment() -> DataFrame # Tổng vốn đầu tư └── global ├── bond_yield() -> DataFrame # Lợi suất TPCP (VN / Mỹ) ├── fed_rate() -> DataFrame # Lãi suất Fed └── index() -> DataFrame # Các chỉ số thế giới (DXY, SPX...) ``` ## 12-05-2026 > Cập nhật vnstock installer GUI v3.1.2 & CLI v3.0.2 - **Nhận diện mẫu Venv**: Đồng bộ cơ chế nhận diện các tên thư mục môi trường ảo phổ biến (`venv`, `.venv`, `env`). - **Cảnh báo tương tác**: Bổ sung hộp thoại xác nhận khi người dùng cung cấp đường dẫn không theo quy chuẩn môi trường ảo. - **Cơ chế an toàn**: Kiểm tra sự tồn tại của tệp `pyvenv.cfg` và các mẫu định danh venv trước khi thực hiện thao tác sửa đổi thư mục môi trường ảo bị lỗi. - **Gợi ý đường dẫn thông minh**: Tự động gợi ý thêm hậu tố `.venv` nếu người dùng chọn thư mục dự án làm nơi cài đặt môi trường ảo. ## 05-05-2026 (v3.1.7) - Bổ sung khả năng truy xuất tài liệu và báo cáo tài chính cho từng mã chứng khoán. Người dùng có thể truy xuất hàng loạt liên kết đến file báo cáo tài chính định dạng PDF thông qua lập trình đơn giản. ```python from vnstock_data import Fundamental fun = Fundamental() fun.equity('FPT').filing(doc_type='annual_report') ``` - Tinh chỉnh chức năng hàm tiện ích `show_api` để hiển thị thông tin cây API trọn vẹn hơn theo từng cấp. - Ví dụ để xem tất cả cấu trúc bên dưới nhóm hàm `Reference` có thể gọi `show_api('Reference')` - Để xem chi tiết sâu hơn 1 cấp nữa, có thể sử dụng cú pháp chaining dạng `show_api('Reference.equity')` ## 02-05-2026 (v3.1.6) - Sửa lỗi xảy ra với `vnstock_data/explorer/vci/listing.py", line 35, in all_symbols` xung đột thư viện sau khi code bị làm rối. ## 01-05-2026 (v3.1.5) - Cập nhật khả năng tuỳ chỉnh điều kiện lọc cho hàm lọc dữ liệu cổ phiếu từ VCI trong giao diện hợp nhất tại lớp `Insights` - Sửa lỗi `ProxyConfig.update_forward_refs()` trong `vnstock_data/core/utils/client.py` khi gọi lệnh mẫu `Company(symbol='VIC', source='KBS').overview()` ## 29-04-2026 (v3.1.4) - Cập nhật CLI Installer phiên bản 3.1.4 - Bổ sung danh sách mapping chính xác các chỉ số index từ HNX, UPCOM để truy xuất dữ liệu lịch sử ohlcv từ VCI ## 27-03-2026 - Cập nhật CLI Installer phiên bản 3.0.2 - Tự động nhận diện API Key đã lưu trong môi trường thay vì yêu cầu người dùng nhập lại. - Tinh chỉnh thiết lập để người dùng tiện cài đặt bộ thư viện trên Google Colab, không yêu cầu bắt buộc phải kết nối Google Drive. - Nâng cấp cơ chế bỏ qua thông báo chuyển đổi câu lệnh import từ vnstock sang vnstock_data gây phiền phức ## 23-04-2026 (v3.1.3) - **Chuẩn hoá & Mở rộng Báo cáo Tài chính (Fundamental & Financial Health)**: - Mở rộng Schema tài chính với các trường dữ liệu chi tiết từ nguồn MAS. - Định chuẩn hóa bộ tiêu chí đánh giá cho 4 nhóm ngành: Ngân hàng, Chứng khoán, Bảo hiểm và Đa ngành theo tiêu chuẩn phân tích chung tương tự giao diện tại TCBS. - **Hạ tầng & Tối ưu hóa (Infrastructure & Refactoring)**: - Nâng cấp các module tiện ích lõi (`client.py`, `user_agent.py`) để cải thiện hiệu năng kết nối và quản lý User-Agent. - **Sửa lỗi & Ổn định hệ thống (Bug Fixes)**: - Khắc phục triệt để lỗi sai tỷ lệ giá (price scaling) cho các tài sản Chỉ số (Index) và Phái sinh (Derivative) tại module `quote` (nguồn KBS). - Sửa lỗi truy xuất dữ liệu danh sách niêm yết (listing) và báo giá (quote) cho nguồn Dukascopy. - Xử lý các lỗi nhỏ trong UI Registry và logic phân loại ngành giúp hệ thống hoạt động chính xác hơn. - **Chuyển đổi giao thức dữ liệu VCI (API Migration)**: - Chuyển đổi toàn bộ quy trình lấy danh sách (Listing) và mã ngành (ICB) từ nguồn VCI từ GraphQL sang REST API để tăng độ ổn định và tốc độ phản hồi. ## 12-04-2026 > Phần mềm `vnstock_data` cập nhật phiên bản 3.1.0: Hoàn thiện bộ dữ liệu hợp nhất (Unified UI) và bổ sung bổ sung dữ liệu thị trường Quốc tế. - **Thị trường Quốc tế & Crypto**: - Tích hợp dữ liệu tiền mã hoá (Cryptocurrency) thông qua API Binance Spot (hỗ trợ dữ liệu `ohlcv`, `order_book`, `intraday`, `quote`). Khung kiến trúc được trang bị thuật toán chờ và gửi lại để duy trì kết nối khi gặp giới hạn truy vấn API. - Xây dựng kiến trúc Explorer cung cấp biểu đồ đa khung thời gian cho Ngoại hối (Forex), Hàng hoá (Commodity) và các chỉ số toàn cầu thông qua Dukascopy và ForexSB. Cung cấp bộ cấu hình Múi giờ gốc sang múi giờ Hệ thống (`Asia/Ho_Chi_Minh`). - **Thị trường Nội địa (Unified UI)**: - Nâng cấp API cho thị trường chỉ số (Index Market): Hệ thống hỗ trợ lấy bộ dữ liệu thống kê giao dịch lịch sử của tất cả các loại chỉ số thông qua phương thức `trade_history()`. Hỗ trợ tên chỉ số quy chuẩn để tra lệnh. - Bổ sung hàm tóm tắt bức tranh tài chính tổng hợp `financial_health` (tổ hợp 3 bảng báo cáo tài chính và các chỉ số tài chính). Chuẩn hoá chuyển ngữ thẻ Scorecard chuyên ngành: Ngân hàng, Chứng khoán, Bảo hiểm, hỗ trợ trích lọc linh hoạt. Quy chuẩn này lấy cảm hứng từ cấu trúc báo cáo của nền tảng TCBS, giúp duy trì sự nhất quán trong bộ tiêu chí cố định trong phân tích cơ bản cho doanh nghiệp, tránh phải xử lý bộ tiêu chí không thống nhất trong các báo cáo tài chính vốn có nhiều khác biệt giữa các nguồn khác nhau. Sử dụng bộ tiêu chí này giúp người dùng hạn chế phải thay đổi code khi nguồn dữ liệu gặp sự cố hoặc phiên bản phần mềm thay đổi ảnh hưởng tới bộ tiêu chí này. -Nguồn dữ liệu cung cấp dữ liệu tài chính cho các hàm tại Unified UI được chuyển đổi từ KBS sang MAS để tăng số kỳ báo cáo tài chính lên trên 10 năm, thay vì bị giới hạn 4 kỳ mặc định của API từ KBS. - Tối ưu tra cứu dữ liệu Vĩ mô (Macro) và Hàng hoá: Áp dụng kỹ thuật quét lùi tự động và đắp điền dữ liệu khuyết rỗng (Forward-fill) để xử lý hoàn thiện độ trễ công bố thông tin, giảm thiểu phát sinh lỗi. - Cải thiện khả năng chuẩn hoá symbol nhập nhập vào hàm của CafeF để nhận diện các chỉ số chính xác VNINDEX/HOSE, HNXINDEX/HNX, UPCOMINDEX/UPCOM và VN30. - Tái cấu trúc chuẩn thư viện: Áp dụng chuẩn hoá, bổ sung tham số định danh nhà cung cấp `source` theo yêu cầu từ phiên bản. - **Tài liệu Agent Guide**: - Cập nhật mô tả các hàm và nguồn dữ liệu bổ sung - Cung cấp schema dữ liệu chuẩn hoá giúp xác định mô hình dữ liệu và xây dựng sản phẩm tin cậy hơn, giảm thiểu việc phải chạy từng đoạn code để kiểm tra cấu trúc dữ liệu. - **Bổ sung bộ Notebook hoàn chỉnh**: - Bổ sung bộ Notebook hoàn chỉnh về các hàm tại Unified UI và theo kiểu gọi Adapter Pattern (thay đổi tham số source kiểu cũ) phản ánh đầy đủ trạng thái mới nhất của thư viện. ## 07-04-2026 > Phát hành `vnstock_data` phiên bản 3.0.1 sửa các lỗi quan trọng và tinh chỉnh trải nghiệm người dùng. - **Unified UI**: Bổ sung hàm `cash_flow` vào giao diện hợp nhất; cập nhật mô tả cho hàm `trade_history` (thống kê giao dịch, giá chứng khoán trước khi pha loãng). - **Nguồn KBS**: Sửa lỗi chia điểm index cho 1000 và lỗi 502 Bad Gateway do web phân định lại cấu trúc URL; tinh chỉnh chuẩn hoá tên chỉ tiêu tài chính và thông tin định danh User Agent. - **Nguồn MBK (Vĩ mô)**: Cải thiện thuật toán truy xuất dữ liệu theo tham số `length` và tự động *forward fill* để khắc phục lỗi trả về dữ liệu rỗng. - **Nguồn SPL (Hàng hoá)**: Sửa lỗi truy xuất dữ liệu null sinh ra do không khớp cấu hình múi giờ. - **Nguồn VCI**: Bổ sung cơ chế tương thích pandas cho hàm map và applymap để hoạt động tốt cho tất cả phiên bản từ 2.1.0 và trước đó. ## 11-03-2026 > **Phát hành vnstock_data 3.0.0: Thế hệ mới với Unified UI và Thị trường Quốc tế.** > > Phiên bản 3.0.0 không chỉ là một bản cập nhật thông thường, mà là bước chuyển mình quan trọng của hệ sinh thái Vnstock. Phiên bản này mang đến kiến trúc 7 lớp tiêu chuẩn nghiệp vụ và trải nghiệm lập trình (DX) được nâng cấp vượt trội. - **Kiến trúc 7 Lớp & Unified UI (U2)**: - Hoàn thiện mô hình **Unified UI** với 7 phân vùng chức năng rõ rệt: `Reference`, `Market`, `Fundamental`, `Analytics`, `Alternative`, `Macro`, và `Insights`. - Cách tiếp cận "Vấn đề là trên hết": Bạn không còn phải lo lắng về việc dữ liệu đến từ đâu, chỉ cần tập trung vào việc bạn muốn làm gì (định giá, xem bảng giá hay tra cứu thông tin cơ bản). Chất lượng và nguồn dữ liệu tốt nhất sẽ được Vnstock khuyến nghị. Bạn có thể cá nhân hoá nguồn dữ liệu như cách lập trình cũ nếu muốn để khai thác các chức năng có sẵn nhưng ẩn sâu trong mã nguồn. - Bổ sung thông tin hồ sơ (profile) chi tiết cho **Chứng quyền** và **Hợp đồng tương lai**, giúp bạn nắm bắt đầy đủ thông tin sản phẩm trước khi giao dịch. - Tích hợp **Lịch sự kiện thị trường** toàn diện: từ dữ liệu lịch sử (nghỉ lễ, sự cố thị trường... từ năm 2000) đến các sự kiện hiện tại và tương lai giúp bạn bao quát toàn cảnh thị trường một cách chuyên sâu. - **Trợ lý lập trình thông minh (Next-Gen DX)**: - Tái kích hoạt tính năng **Autocomplete** và **Docstring** vượt trội trên các IDE (VSCode, PyCharm), giúp việc viết code nhanh và ít lỗi hơn. - Bổ sung bộ công cụ khám phá API: `show_api()` để vẽ sơ đồ thư viện ngay trong terminal và `show_doc()` để đọc nhanh hướng dẫn sử dụng cho từng hàm. - Tài liệu (Docstrings) đã được chuyển đổi sang tiếng Anh chuẩn để dễ dàng tiếp cận và phù hợp với tiêu chuẩn lập trình hiện đại và tương tác với AI Agent. - **Chuẩn hóa & Tối ưu hóa hệ thống**: - **Chuẩn hoá dữ liệu bảng giá từ nguồn KBS**: Giải quyết triệt để các vấn đề về hiển thị lô chẵn, lô lẻ; đồng bộ hóa dữ liệu cho đa dạng loại tài sản từ cổ phiếu, phái sinh, chứng quyền đến trái phiếu. - Dữ liệu được **tự động chuẩn hóa (Normalization)** từ nhiều nguồn khác nhau về một định dạng duy nhất, giúp việc tính toán và phân tích nhất quán hơn. - Cơ chế **Lọc tham số (Kwargs Filtering)**: Giúp giảm thiểu lỗi runtime khi bạn vô tình truyền thừa tham số, tăng tính ổn định cho chương trình. - Tối ưu hóa tốc độ tải dữ liệu và cấu trúc nội bộ để sẵn sàng cho các bài toán phân tích dữ liệu lớn. - **Cập nhật Vnstock Agent Guide**: Tài liệu hướng dẫn chi tiết và các quy tắc cho AI Agent trong lập trình tự động được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) --- ## 05-03-2026 - **Cập nhật module Unified UI (U2)**: Cập nhật các lớp UI cung cấp cấu trúc lệnh hợp nhất với phân nhóm chặt chẽ lấy cảm hứng từ chuẩn FIX và Bloomberg Terminal giúp điều hướng dễ dàng theo mặc định do Vnstock thiết kế và người dùng không cần cài đặt nguồn dữ liệu. Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) - **Bổ sung hàm lấy thông tin Chứng quyền và hợp đồng tương lai**: - Cung cấp hàm trong giao diện U2 để lấy thông tin chứng quyền và hợp đồng tương lai thông qua Reference().derivatives().warrant() và Reference().derivatives().futures() - **Bổ sung hàm lấy thông tin bộ lọc cổ phiếu từ VCI** thông qua U2 tại `Insights().screener()` - **Cải thiện & bổ sung API nguồn Vĩ mô**: - Bổ sung method `interest_rate` để lấy dữ liệu Lãi suất bình quân & Doanh số trên thị trường liên ngân hàng. Hỗ trợ tham số `format='pivot'` (mặc định) để trả về bảng dạng nhóm cột (MultiIndex giống biểu diễn trên website) hoặc `format='long'` để trả về định dạng phẳng (raw format). - Tích hợp thêm tham số khoảng thời gian tương đối `length` (ví dụ: `90`, `1Y`, `30D`, `100b`) tương tự như cách sử dụng trong `quote.history`. Tính năng này áp dụng đồng bộ cho tất cả các hàm vĩ mô (`gdp`, `cpi`, `interest_rate`, `exchange_rate` v.v...) để bỏ qua việc nhập ngày bắt đầu `start` và kết thúc `end`. - Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) là 1 năm (`1Y`) để trả về thông tin ở khoảng thời gian phù hợp và nhẹ. - Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) - **Cải thiện trải nghiệm sử dụng module lấy dữ liệu hàng hoá**: - Tích hợp khả năng lấy thời gian tương đối thông qua tham số `length` tương tự như module `macro` và `quote.history`. - Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) về 1 năm (`1Y`) thay vì lấy toàn bộ lịch sử như trước đây. - Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) ## 31-01-2026 > Phát hành phiên bản 2.3.4, sửa lỗi và cải thiện trải nghiệm người dùng - Chuẩn hoá định dạng dữ liệu giá thành dạng thập phân xx.xx (ngàn) thay vì xxxx (đồng) cho các hàm `history` và `intraday` trong lớp Quote của nguồn dữ liệu KBS. - Sửa lỗi không cho phép gọi tham số length trong hàm `history` của lớp Quote của nguồn dữ liệu VCI, VND, MAS khi không truyền tham số `start` và `end`. - Sửa lỗi không nhận diện nguồn VND cho lớp hàm Market - Cập nhật chương trình cài đặt vnstock installer chế độ GUI và CLI sử dụng `uv` là công cụ quản lý thư viện thay cho `pip`, tăng tốc độ cài đặt và giảm 30% thời gian hoàn thành. ## 28-01-2026 > Phát hành phiên bản 2.3.2, sửa lỗi và cải thiện trải nghiệm người dùng - Chuẩn hoá tham số `period` để lấy dữ liệu báo cáo tài chính cho các phương thức trong lớp Finance của nguồn dữ liệu KBS - cho phép gọi tham số này khi khởi tạo lớp Finance thay vì gọi ở mỗi phương thức. - Bổ sung tham số `length` cho phép lấy dữ liệu hàng hoá theo cách tính thời gian tương đối so với hiện tại thay vì bắt buộc nhập ngày bắt đầu và kết thúc. - Tinh chỉnh nhỏ cho lớp Commodity giúp nạp thư viện chính xác, loại bỏ lỗi liên quan nested f-string sinh ra trong quá trình bảo mật mã nguồn. ## 27-01-2026 > Phát hành phiên bản 2.3.1, bổ sung tài liệu hướng dẫn chi tiết Vnstock Agent Guide. - Bổ sung hàm tiện ích `convert_derivative_symbol` giúp chuyển đổi mã hợp đồng tương lai kiểu cũ (VN30F1M) sang kiểu mới sau áp dụng KRX (tương đương 41I1G2000 tại thời điểm tháng 1/2026) - Cải thiện nguồn KBS - Sửa lỗi không nhận diện nguồn dữ liệu KBS từ Finance wrapper - Bổ sung khả năng lấy dữ liệu báo cáo tài chính nhiều năm thay vì cố định 4 năm như phiên bản trước - Tự động nhận diện và chuyển đổi mã hợp đồng tương lai sang kiểu mới để gọi các hàm `history` và `intraday` trong lớp hàm Quote. - Bổ sung khả năng lấy dữ liệu các mã index phổ biến HNXINDEX, HNXINDEX, UPCOMINDEX, VN30, VN100, HNX30 trong hàm `history` của lớp Quote. - Cải thiện chung - Hiện cảnh báo mã index không có dữ liệu `intraday`. ## 23-01-2026 - Phát hành phiên bản 2.2.0, bổ sung nguồn dữ liệu KBS cho phép truy cập từ các dịch vụ cloud của Google như Google Colab, Kaggle thay vì nguồn VCI bị chặn IP. - Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. - Cập nhật yêu cầu phiên bản gói phụ thuộc tương thích. ## 21-07-2025 > Phát hành phiên bản Vnstock Data 2.1.3 và nâng cấp cơ chế quản lý license chính xác hơn. Để thực hiện nâng cấp phiên bản, các bạn vui lòng chạy lại chương trình cài đặt, lưu ý nên chạy thử và trải nghiệm qua môi trường như Github Codespace để hình dung các thay đổi để không làm ảnh hưởng đến chương trình hiện có. Hệ thống **không thể quay lại phiên bản cú sau nâng cấp**.
Nâng cấp


### Ads Free Ẩn banner quảng cáo đối với người dùng đang duy trì gói sponsor trừ những thông báo đặc biệt liên quan đến trải nghiệm người dùng hoặc yêu cầu nâng cấp bắt buộc. ### Vnstock Data Explorer - Bổ sung nguồn Fmarket vào mã nguồn - Bổ sung và nâng cấp các API của nguồn VCI - Thay thế API các nhóm hàm Quote, Listing class gặp lỗi từ chối truy cập và đổi url - Bổ sung bộ API mới cho nhóm hàm thuộc Financial class - Cập nhật API mới - Cho phép sử dụng tiếp API cũ từ máy tính local nếu muốn. - Sửa đổi nhóm hàm Trading cho phép lấy dữ liệu phân tích lịch sử giao dịch & bảng giá - Thêm các hàm `foreign_trade` để lấy riêng thông tin giao dịch nước ngoài - Loại bỏ các hàm `trading_stats` và `side_stats` trong nhóm hàm thuộc Trading class để không trùng thông tin với hàm `price_board` ## 02-06-2025 ### Vnstock Data Explorer
Bổ sung hàm truy xuất dữ liệu lịch sử giao dịch từ VCI với Trading class thay thế dữ liệu từ CafeF gặp lỗi.
Chi tiết hàm bổ sung tại [Nguồn VCI - Thống kê giao dịch](/docs/vnstock-data/du-lieu-giao-dich) ## 06-05-2024 ### Vnstock Data Explorer
Cập nhật phiên bản Vnstock Data 2.1.1 sửa lỗi hàm Intraday sau khi triển khai hệ thống KRX từ 5/5/2025 và cải thiện trải nghiệm người dùng.
- [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Cập nhật tính năng thay đổi user_agent ngẫu nhiên không sử dụng gói fake_user_agent - [Issue 172](https://github.com/thinh-vu/vnstock/issues/172): Bổ sung hàm `price_board` cho Trading class thuộc nguồn dữ liệu VCI - [Issue 178](https://github.com/thinh-vu/vnstock/issues/178) và sửa lỗi dữ liệu Intraday sau cập nhật hệ thống KRX cho nguồn VCI và MAS. - Đóng [Issue 169](https://github.com/thinh-vu/vnstock/issues/169) vì dữ liệu khung thời gian `1W` đã được hỗ trợ sẵn trong thư viện. - [Issue 166](https://github.com/thinh-vu/vnstock/issues/166) Cập nhật thiết lập rate limit cho các nguồn dữ liệu trong gói tài trợ, tránh hiển thị nhầm thông báo nâng cấp. ## 22-04-2025 ### Vnstock Data Explorer > Phiên bản `vnstock_data` **2.1.0** đánh dấu bước tiến lớn trong khả năng quản lý và mở rộng dữ liệu, với việc áp dụng **cấu trúc Adapter** chuẩn hóa toàn bộ giao tiếp với nguồn cấp dữ liệu. #### ✨ Những Thay Đổi Quan Trọng | Hạng mục | Thay đổi | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cấu trúc thư viện** | Triển khai mô hình **Adapter Pattern** cho tất cả các lớp dữ liệu (Quote, Trading, Finance, Listing, Company, Macro, Commodity, v.v.). | | **Cách gọi hàm** | Các hàm khi sử dụng Adapter cần truyền **tham số `source`** để xác định rõ nhà cung cấp dữ liệu mong muốn. | | **Mặc định `source`** | Tham số `source` **không còn mặc định ngầm định** như phiên bản trước. Nếu không truyền `source` đúng, hàm có thể gây lỗi `NotSupportedError`. | | **Hướng dẫn chi tiết hơn** | Bổ sung [bảng tra cứu](/vnstock-insider-api/vnstock-data/kien-truc-thu-vien) phương thức hỗ trợ theo nguồn cấp dữ liệu, và sơ đồ hệ thống trực quan. | #### 🚨 Lưu Ý Ảnh Hưởng Đến Đoạn Mã Cũ Nếu bạn đang sử dụng `vnstock_data` theo cách cũ ```python from vnstock_data import Trading trading = Trading(symbol='MSN') quote.history(start="2024-01-01", end="2024-04-01") ``` ➡️ Từ phiên bản 2.1.0, đoạn code trên **sẽ lỗi** nếu thông tin `source` không trùng khớp với nguồn cấp dữ liệu hỗ trợ. Cụ thể, bạn cần sửa lại thành: ```python from vnstock_data import Trading quote = Quote(source="cafef", symbol="VCI") quote.history(start="2024-01-01", end="2025-04-18", interval="1D") ``` --- ## Document: Dữ Liệu Vĩ Mô & Hàng Hóa (Macro Data)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
## 📌 Tổng Quan **Macro Layer** cung cấp dữ liệu **kinh tế vĩ mô, tiền tệ, hàng hóa** phục vụ cho: - Phân tích tác động yếu tố kinh tế đến thị trường - Trading danh sách hàng hóa (gold, oil, steel, etc.) - Quản lý rủi ro tiền tệ, lãi suất - Dự báo xu hướng kinh tế ### 🏗️ Cấu Trúc Domain ```python Macro() ├── .economy() # Dữ liệu kinh tế Việt Nam ├── .currency() # Tỷ giá, lãi suất ├── .commodity() # Giá hàng hóa └── .global # Chỉ số toàn cầu (bond, fed rate) ``` ## 1. Kinh tế Việt Nam (Economy) Dữ liệu kinh tế Việt Nam theo quý/năm: GDP, CPI, FDI, xuất nhập khẩu, v.v. **Source:** ASEAN **Nhóm lệnh:** `macro.economy` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | -------------------- | ------------------------------------- | --------------------------- | --------- | | `gdp()` | `start`, `end`, `period` | Tăng trưởng GDP | DataFrame | | `cpi()` | `start`, `end`, `period` | Chỉ số giá tiêu dùng | DataFrame | | `industry_prod()` | `start`, `end`, `period` | Sản xuất công nghiệp | DataFrame | | `import_export()` | `start`, `end`, `period` | Xuất nhập khẩu | DataFrame | | `retail()` | `start`, `end`, `period` | Bán lẻ | DataFrame | | `fdi()` | `start`, `end`, `period` | Đầu tư trực tiếp nước ngoài | DataFrame | | `money_supply()` | `start`, `end`, `period`, `breakdown` | Cung tiền | DataFrame | | `population_labor()` | `start`, `end`, `period` | Dân số & lao động | DataFrame | | `credit()` | `start`, `end`, `period`, `breakdown` | Tín dụng | DataFrame | | `total_investment()` | `start`, `end`, `period` | Tổng vốn đầu tư | DataFrame | | `state_budget()` | `start`, `end`, `period` | Ngân sách nhà nước | DataFrame | **Parameters:** - `start`: Mốc bắt đầu (ví dụ: "2020-01" hoặc "2020") - `end`: Mốc kết thúc (ví dụ: "2026-03") - `period`: "quarter" (mặc định) hoặc "month" hoặc "year" - `length`: Số kỳ gần nhất (ví dụ: length=12 lấy 12 tháng gần nhất) **Ví Dụ** ```python from vnstock_data import Macro mac = Macro() df_gdp_q = mac.economy().gdp( start="2020-01", end="2026-03", period="quarter" ) print(df_gdp_q.head(1)) df_cpi = mac.economy().cpi(period="month", length=24) # 24 tháng gần nhất print(df_cpi.head(1)) df_ind = mac.economy().industry_prod(period="month", length=12) print(df_ind.head(1)) df_trade = mac.economy().import_export(period="month") df_retail = mac.economy().retail(period="month") df_fdi = mac.economy().fdi(period="month") print(df_fdi.head(1)) df_money = mac.economy().money_supply(period="month") df_labor = mac.economy().population_labor(period="year") ``` --- ## 2. Tiền tệ & Lãi suất (Currency) Tỷ giá hối đoái, lãi suất tiền tệ, chính sách tiền tệ. **Source:** ASEAN **Nhóm lệnh:** `macro.currency` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | ------------------ | ---------------------------------- | ----------------------- | --------- | | `exchange_rate()` | `start`, `end`, `period` | Tỷ giá hối đoái | DataFrame | | `interest_rate()` | `start`, `end`, `period`, `format` | Lãi suất | DataFrame | | `interbank_rate()` | `start`, `end`, `period` | Lãi suất liên ngân hàng | DataFrame | | `policy_rate()` | `start`, `end` | Lãi suất điều hành | DataFrame | | `omo()` | `start`, `end` | Nghiệp vụ thị trường mở | DataFrame | | `deposit_rate()` | `mode`, `period`, `start`, `end` | Lãi suất huy động | DataFrame | **Parameters:** - `period`: "day" (mặc định), "month", "quarter" - `format`: "pivot" (mặc định) hoặc "long" - `length`: Số kỳ gần nhất **Ví Dụ** ```python from vnstock_data import Macro mac = Macro() df_exr = mac.currency().exchange_rate( start="2026-02-06", end="2026-03-06", period="day" ) print(df_exr[['time', 'USD', 'EUR', 'JPY']]) df_exr_m = mac.currency().exchange_rate(period="month", length=12) print(df_exr_m[['time', 'USD', 'EUR']].tail()) df_ir = mac.currency().interest_rate( period="day", length=365 # 1 năm gần nhất ) print(df_ir[['time', 'lending_rate', 'deposit_rate']]) df_ir_long = mac.currency().interest_rate(period="month", format="long") print(df_ir_long[['date', 'rate_type', 'rate_value']].head(10)) ``` --- ## 3. Hàng hóa (Commodity) Giá hàng hóa địa phương và quốc tế: vàng, dầu, thép, nông sản, v.v. **Source:** ASEAN (Quốc tế), SPL (Nội địa) **Nhóm lệnh:** `macro.commodity` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | ------------------ | ------------------------ | ------------------- | --------- | | `gold()` | `market`, `start`, `end` | Giá vàng | DataFrame | | `gas()` | `market`, `start`, `end` | Giá xăng dầu | DataFrame | | `oil_crude()` | `start`, `end` | Giá dầu thô | DataFrame | | `coke()` | `start`, `end` | Giá coke (than cốc) | DataFrame | | `steel()` | `market`, `start`, `end` | Giá thép | DataFrame | | `iron_ore()` | `start`, `end` | Giá quặng sắt | DataFrame | | `fertilizer_ure()` | `start`, `end` | Giá phân URE | DataFrame | | `soybean()` | `start`, `end` | Giá đậu tương | DataFrame | | `corn()` | `start`, `end` | Giá ngô | DataFrame | | `sugar()` | `start`, `end` | Giá đường | DataFrame | | `pork()` | `market`, `start`, `end` | Giá thịt lợn | DataFrame | **Parameters (cho gold, gas, steel, pork):** - `market`: "VN" (Việt Nam) hoặc "GLOBAL" (quốc tế), mặc định = "VN" - `start`, `end`: Khoảng thời gian lịch sử **Ví Dụ** ```python from vnstock_data import Macro import pandas as pd mac = Macro() df_gold_vn = mac.commodity().gold(market="VN") print(df_gold_vn[['time', 'price']].tail()) df_gold_global = mac.commodity().gold(market="GLOBAL") print(df_gold_global.head(1)) # OHLCV DataFrame df_gas_vn = mac.commodity().gas(market="VN") print(df_gas_vn.head(1)) df_gas_global = mac.commodity().gas(market="GLOBAL") print(df_gas_global.head(1)) # USD/MMBtu (OHLCV) df_oil = mac.commodity().oil_crude() print(df_oil.head(1)) df_coke = mac.commodity().coke() print(df_coke.head(1)) df_steel_vn = mac.commodity().steel(market="VN") print(df_steel_vn.head(1)) df_steel_global = mac.commodity().steel(market="GLOBAL") print(df_steel_global.head(1)) # USD/tấn (OHLCV) df_ore = mac.commodity().iron_ore() print(df_ore.head(1)) # USD/tấn (OHLCV) df_soy = mac.commodity().soybean() print(df_soy.head(1)) # USD/bushel (OHLCV) df_corn = mac.commodity().corn() print(df_corn.head(1)) df_sugar = mac.commodity().sugar() print(df_sugar[['time', 'price']]) df_pork_vn = mac.commodity().pork(market="VN") print(df_pork_vn[['time', 'price']]) # VNĐ/kg df_pork_china = mac.commodity().pork(market="CHINA") print(df_pork_china[['time', 'price']]) ``` --- ## 4. Kinh tế toàn cầu (Global) Cung cấp các chỉ số vĩ mô toàn cầu như lợi suất trái phiếu chính phủ, lãi suất Fed, và các chỉ số vĩ mô thế giới (ví dụ DXY). **Source:** ASEAN **Nhóm lệnh:** `macro.global` **Phương Thức** | Method | Tham Số | Mô Tả | Return | | -------------- | ----------------- | ------------------------------------------- | --------- | | `bond_yield()` | `market`, `tenor` | Lợi suất trái phiếu chính phủ | DataFrame | | `fed_rate()` | `start`, `end` | Lãi suất Fed (US Federal Reserve Fund Rate) | DataFrame | | `index()` | `symbol` | Các chỉ số vĩ mô toàn cầu (ví dụ DXY) | DataFrame | **Parameters:** - `market`: Ví dụ "VN" - `tenor`: Kỳ hạn, ví dụ "10Y", "5Y" - `symbol`: Ticker của chỉ số vĩ mô (mặc định 'DXY') **Ví Dụ** ```python from vnstock_data import Macro mac = Macro() df_bond = mac.global.bond_yield(market="VN", tenor="10Y") df_fed = mac.global.fed_rate() df_dxy = mac.global.index(symbol="DXY") ``` --- ## ⚠️ Lưu Ý Quan Trọng ### 1. Tương Thích Ngược **DEPRECATED** (sẽ xóa sau 31/8/2026): ```python m = Macro() df = m.interest_rate(length=90) # ⚠️ Warning ``` **RECOMMENDED** (Dùng từ bây giờ): ```python df = Macro().currency().interest_rate(length=90) ``` Tất cả legacy methods sẽ hiển thị **deprecation warning bằng tiếng Việt + Anh**: ``` [DEPRECATED] Macro.interest_rate() sẽ bị xóa sau ngày 31/8/2026. Vui lòng sử dụng Macro().currency().interest_rate() thay thế. | Macro.interest_rate() is deprecated and will be removed after 31/8/2026. Please use Macro().currency().interest_rate() instead. ``` ### 2. Độ Trễ Dữ Liệu - GDP, CPI: Công bố quý/tháng, có độ trễ 1-2 tuần - Tỷ giá: Cập nhật hằng ngày, có thể bị delay 1-2 giờ - Giá hàng hóa: Cập nhật hằng ngày, trong phiên hoặc T+1, theo độ trễ của nguồn ### 3. Đơn Vị Tiền Tệ - Tỷ giá: Nghìn VNĐ (ví dụ: 24.5 = 24,500 VNĐ) - Vàng: VNĐ/lượng - Dầu/Quặng: USD/barrel hoặc USD/tấn - Nông sản: USD/bushel hoặc USD/tấn ### 4. Chỉ Số & Phần Trăm - GDP Growth, CPI: Phần trăm YoY hoặc QoQ - Lãi suất: Phần trăm năm (%/năm) - Tỷ lệ: 0-100 (không phải 0-1) --- ## Document: Dữ Liệu Giao Dịch (Market Data)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
## 📌 Tổng Quan **Market Layer** cung cấp dữ liệu **trong phiên & lịch sử** về giá, khối lượng, vốn hóa, thanh khoản ngay từ các sàn giao dịch và data providers. Đây là dữ liệu **thay đổi liên tục** và phục vụ cho trading, phân tích kỹ thuật, và monitoring portfolio. ### 🏗️ Cấu Trúc Domain ```python Market() ├── .equity(symbol) # Thị trường cổ phiếu ├── .index(symbol) # Thị trường chỉ số ├── .futures(symbol) # Thị trường hợp đồng tương lai ├── .warrant(symbol) # Thị trường chứng quyền ├── .bond(symbol) # Thị trường trái phiếu ├── .etf(symbol) # Thị trường ETF ├── .fund(symbol) # Thị trường quỹ mở ├── .crypto(symbol) # Tiền mã hoá ├── .forex(symbol) # Ngoại hối ├── .commodity(symbol) # Hàng hoá quốc tế └── .quote(symbols_list) # Bảng giá nhiều mã ``` ## ⚙️ Cấu Trúc Tham Số Đa số các phương thức trong Market Layer đều tuân theo hệ thống tham số chuẩn hóa: ### 1. Dữ liệu Lịch sử (Historical Data) Các hàm lấy chuỗi thời gian như `ohlcv()`, `trade_history()`, `foreign_flow()`, `proprietary_flow()`... hỗ trợ: - `start` (`str`): Ngày bắt đầu lấy dữ liệu (VD: `"2024-01-01"`). - `end` (`str`): Ngày kết thúc (VD: `"2024-12-31"`). Nếu bỏ trống sẽ lấy đến hiện tại. - `interval` (`str`, tuỳ chọn): Độ phân giải dữ liệu. Các giá trị hợp lệ: - Khung ngày/tuần/tháng: `'1D'`, `'1W'`, `'1M'` (Mặc định thường là `'1D'`). - Khung phút (Intraday): `'1m'`, `'5m'`, `'15m'`, `'1H'` (Chỉ khả dụng với tài khoản Premium/Pro tuỳ nguồn cung cấp). - `length` (`int` | `str`, tuỳ chọn): Số lượng nến/kỳ cần lấy ngược về quá khứ tính từ `end`. Có thể dùng thay cho `start` (VD: `100` nến, hoặc chuỗi thời gian như `"30D"`, `"1Y"`). ### 2. Dữ liệu Chi tiết Giao dịch (Intraday / Trades) Các hàm lấy thông tin từng lệnh (Time & Sales) như `trades()`, `block_trades()`... hỗ trợ: - `limit` (`int`): Giới hạn số lượng lệnh trả về trên mỗi trang. Mặc định `1000`. - `page` (`int`): Số thứ tự trang cần truy xuất. Mặc định `1`. - `get_all` (`bool`): Nếu `True`, API sẽ tự động quét qua tất cả các trang để lấy toàn bộ dữ liệu lịch sử lệnh (cẩn trọng với mã thanh khoản lớn). Mặc định `False`. ### 3. Dữ liệu Tức thời & Thống kê (Snapshot / Stats) Các hàm truy xuất trạng thái hiện tại như `quote()`, `order_book()`, `session_stats()`, `summary()`, `volume_profile()`, `odd_lot()`: Hầu hết **không yêu cầu truyền tham số** thời gian. Dữ liệu trả về mặc định là snapshot tại thời điểm truy vấn hoặc thống kê tổng hợp của ngày giao dịch hiện hành. --- ## 1. Cổ phiếu (Equity) **Nguồn chính:** KBS (kbs), VCI **Nhóm lệnh:** `market.equity` **Phương Thức** | Method | Mô Tả | Return | | -------------------- | ----------------------------------------------------- | --------- | | `ohlcv()` | Giá OHLCV lịch sử | DataFrame | | `trade_history()` | Lịch sử thống kê giao dịch (giá, khối lượng, giá trị) | DataFrame | | `trades()` | Lệnh giao dịch chi tiết (Time & Sales) | DataFrame | | `order_book()` | Cấp độ mua/bán | DataFrame | | `quote()` | Giá hiện tại / Bảng giá | DataFrame | | `session_stats()` | Thống kê phiên giao dịch | DataFrame | | `foreign_flow()` | Dòng tiền nước ngoài | DataFrame | | `proprietary_flow()` | Dòng tiền tự doanh | DataFrame | | `block_trades()` | Giao dịch thỏa thuận | DataFrame | | `odd_lot()` | Giao dịch lô lẻ | DataFrame | | `volume_profile()` | Phân bố khối lượng theo giá | DataFrame | | `summary()` | Tổng hợp thông tin cổ phiếu | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Lịch sử Giá (ohlcv)** Lấy dữ liệu giá mở, cao, thấp, đóng và khối lượng theo chuỗi thời gian để vẽ biểu đồ kỹ thuật. ```python from vnstock_data import Market mkt = Market() df_ohlc = mkt.equity("VIC").ohlcv( start="2026-02-01", end="2026-03-01", interval="1D" ) ``` **2. Thống kê Giao dịch Lịch sử (trade_history)** Cung cấp dữ liệu thống kê tổng hợp cuối ngày về giá trị, khối lượng khớp lệnh và thỏa thuận. ```python history_stats = mkt.equity("VIC").trade_history( start="2026-02-01", end="2026-03-01" ) ``` **3. Khớp Lệnh Intraday (trades)** Truy xuất danh sách các lệnh khớp chi tiết trong phiên (Time & Sales) để phân tích hành vi dòng tiền. ```python df_trades = mkt.equity("TCB").trades(limit=100) ``` **4. Sổ Lệnh (order_book)** Xem thông tin các mức giá chờ mua/bán tốt nhất trên sổ lệnh (thường là 3-10 mức). ```python df_orderbook = mkt.equity("VNM").order_book() ``` **5. Bảng Giá (quote)** Lấy trạng thái giá và các chỉ số giao dịch mới nhất trong phiên (snapshot), cập nhật theo độ trễ của nguồn. ```python quote = mkt.equity("HPG").quote() ``` **6. Thống kê Phiên (session_stats)** Tổng hợp các chỉ số thanh khoản, trung bình lệnh, tỷ lệ mua/bán chủ động trong ngày. ```python session = mkt.equity("VIC").session_stats() ``` **7. Tổng Hợp Cổ Phiếu (summary)** Các chỉ số định giá cơ bản (PE, PB), biên độ 52 tuần, số lượng cổ phiếu lưu hành, vốn hoá. ```python summary_info = mkt.equity("VIC").summary() ``` **8. Dòng Tiền Nước Ngoài (foreign_flow)** Lịch sử thống kê khối lượng và giá trị mua/bán ròng của nhà đầu tư nước ngoài. ```python foreign = mkt.equity("VIC").foreign_flow() ``` **9. Dòng Tiền Tự Doanh (proprietary_flow)** Lịch sử thống kê giao dịch của khối Tự doanh các Công ty Chứng khoán. ```python proprietary = mkt.equity("VIC").proprietary_flow() ``` **10. Giao Dịch Thỏa Thuận (block_trades)** Thông tin các lệnh thỏa thuận khối lượng lớn được thực hiện ngoài sàn khớp lệnh liên tục. ```python blocks = mkt.equity("VIC").block_trades(limit=50) ``` **11. Giao Dịch Lô Lẻ (odd_lot)** Thông tin các lệnh giao dịch có khối lượng dưới tiêu chuẩn lô chẵn (thường < 100 cổ phiếu). ```python odds = mkt.equity("VIC").odd_lot() ``` **12. Phân Bố Khối Lượng (volume_profile)** Tổng hợp khối lượng giao dịch đã khớp tại từng mức giá cụ thể trong phiên. ```python vol_profile = mkt.equity("VJC").volume_profile() ``` --- ## 2. Chỉ số (Index) **Nguồn:** KBS (kbs) **Nhóm lệnh:** `market.index` **Phương Thức** | Method | Mô Tả | Return | | ------------------- | -------------------------------------------- | --------- | | `ohlcv()` | Điểm chỉ số lịch sử | DataFrame | | `quote()` | Điểm chỉ số hiện tại | DataFrame | | `summary()` | Tổng hợp chỉ số | DataFrame | | `trade_history()` | Thống kê giao dịch lịch sử (giá, khối lượng) | DataFrame | | `stock_influence()` | Top cổ phiếu ảnh hưởng tới chỉ số | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Điểm Chỉ Số Lịch Sử (ohlcv)** Lấy lịch sử biến động điểm số (mở, cao, thấp, đóng) của Index theo thời gian. ```python from vnstock_data import Market mkt = Market() df_vnindex = mkt.index("VNINDEX").ohlcv( start="2026-01-01", end="2026-03-01" ) ``` **2. Điểm Hiện Tại (quote)** Truy xuất điểm số trong phiên hoặc điểm chốt phiên gần nhất của chỉ số. ```python quote_index = mkt.index("VNINDEX").quote() ``` **3. Tổng Hợp Chỉ Số (summary)** Thống kê tổng quan trạng thái chỉ số (khối lượng, giá trị giao dịch toàn rổ, số mã tăng/giảm). ```python summary_index = mkt.index("VNINDEX").summary() ``` **4. Thống kê Giao dịch Lịch sử (trade_history)** Cung cấp dữ liệu thống kê giao dịch theo thời gian. ```python hist_trades = mkt.index("VNINDEX").trade_history(start="2026-02-01", end="2026-03-01") ``` **5. Cổ phiếu Ảnh hưởng (stock_influence)** Lấy top các cổ phiếu tác động mạnh nhất đến điểm số của chỉ số. ```python influence = mkt.index("VNINDEX").stock_influence() ``` --- ## 3. Hợp đồng tương lai (Futures) **Nguồn:** KBS (kbs) **Nhóm lệnh:** `market.futures` **Phương Thức** | Method | Mô Tả | Return | | -------------- | -------------------- | --------- | | `ohlcv()` | Giá hợp đồng lịch sử | DataFrame | | `quote()` | Giá hiện tại | DataFrame | | `trades()` | Giao dịch chi tiết | DataFrame | | `order_book()` | Cấp độ mua/bán | DataFrame | | `summary()` | Thông tin hợp đồng | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Lịch sử Hợp đồng (ohlcv)** Lấy dữ liệu nến lịch sử của hợp đồng phái sinh. ```python from vnstock_data import Market mkt = Market() df_vn30f = mkt.futures("VN30F2503").ohlcv( start="2026-02-01", end="2026-03-01" ) ``` **2. Giá Hiện Tại (quote)** Lấy giá khớp gần nhất, khối lượng mở (OI) và độ lệch (Basis) của hợp đồng trong phiên. ```python quote_vn30f = mkt.futures("VN30F2503").quote() ``` **3. Khớp Lệnh Intraday (trades)** Danh sách chi tiết các lệnh khớp phái sinh trong phiên. ```python trades_vn30f = mkt.futures("VN30F2503").trades(limit=100) ``` **4. Sổ Lệnh (order_book)** Bảng giá các mức chờ mua/bán tốt nhất của hợp đồng. ```python orderbook_vn30f = mkt.futures("VN30F2503").order_book() ``` **5. Thông tin Hợp đồng (summary)** Cung cấp thông tin tổng quan, ngày đáo hạn, số lượng hợp đồng mở (OI). ```python summary_vn30f = mkt.futures("VN30F2503").summary() ``` --- ## 4. Chứng quyền (Warrant) **Nguồn:** KBS (kbs) **Nhóm lệnh:** `market.warrant` **Phương Thức** | Method | Mô Tả | Return | | -------------- | ----------------------- | --------- | | `ohlcv()` | Giá chứng quyền lịch sử | DataFrame | | `quote()` | Giá hiện tại | DataFrame | | `trades()` | Giao dịch chi tiết | DataFrame | | `order_book()` | Cấp độ mua/bán | DataFrame | | `summary()` | Thông tin chứng quyền | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Lịch sử Giá Chứng Quyền (ohlcv)** Lấy dữ liệu nến lịch sử của mã chứng quyền. ```python from vnstock_data import Market mkt = Market() df_warrant = mkt.warrant("CACB2511").ohlcv( start="2026-02-01", end="2026-03-01" ) ``` **2. Giá Hiện Tại (quote)** Lấy thông tin giá khớp lệnh hiện tại và các thông số thanh khoản của chứng quyền. ```python quote_warrant = mkt.warrant("CACB2511").quote() ``` **3. Khớp Lệnh Intraday (trades)** Truy xuất danh sách các lệnh khớp chi tiết trong phiên của chứng quyền. ```python trades_warrant = mkt.warrant("CACB2511").trades(limit=100) ``` **4. Sổ Lệnh (order_book)** Xem thông tin các mức giá chờ mua/bán tốt nhất. ```python orderbook_warrant = mkt.warrant("CACB2511").order_book() ``` **5. Tổng hợp Chứng Quyền (summary)** Các chỉ số cơ bản của chứng quyền (ngày đáo hạn, tỷ lệ chuyển đổi, giá thực hiện, tổ chức phát hành). ```python summary_warrant = mkt.warrant("CACB2511").summary() ``` --- ## 5. Trái phiếu (Bond) **Nguồn:** KBS (kbs) **Nhóm lệnh:** `market.bond` **Phương Thức** | Method | Mô Tả | Return | | -------------- | ---------------------- | --------- | | `ohlcv()` | Giá trái phiếu lịch sử | DataFrame | | `quote()` | Giá hiện tại | DataFrame | | `trades()` | Giao dịch chi tiết | DataFrame | | `order_book()` | Cấp độ mua/bán | DataFrame | | `summary()` | Thông tin trái phiếu | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Lịch sử Giá Trái Phiếu (ohlcv)** Lấy dữ liệu biến động giá trị giao dịch trái phiếu lịch sử. ```python from vnstock_data import Market mkt = Market() df_bond = mkt.bond("TD2444161").ohlcv( start="2026-02-01", end="2026-03-01" ) ``` **2. Giá Hiện Tại (quote)** Trạng thái giá khớp và thanh khoản trong phiên của trái phiếu. ```python quote_bond = mkt.bond("TD2444161").quote() ``` *(Các phương thức khác như `trades()`, `order_book()`, `summary()` được sử dụng hoàn toàn tương tự như `Equity Market`)* --- ## 6. Chứng chỉ quỹ (ETF) **Nguồn:** KBS (kbs), VCI **Nhóm lệnh:** `market.etf` **Phương Thức** Giống Equity Market (đầy đủ): `ohlcv()`, `trades()`, `order_book()`, `quote()`, `session_stats()`, `foreign_flow()`, `proprietary_flow()`, `block_trades()`, `odd_lot()`, `volume_profile()`, `summary()`. **📝 Chi Tiết Các Phương Thức** **1. Lịch sử Giá ETF (ohlcv)** Lấy dữ liệu giá trị của chứng chỉ quỹ ETF trên sàn theo thời gian. ```python from vnstock_data import Market mkt = Market() df_etf = mkt.etf("E1VFVN30").ohlcv( start="2026-02-01", end="2026-03-01" ) ``` **2. Giá Hiện Tại (quote)** Trạng thái giá khớp và thanh khoản trong phiên của ETF. ```python quote_etf = mkt.etf("E1VFVN30").quote() ``` *(Các phương thức khác như `trades()`, `order_book()`, `summary()`, `session_stats()`, v.v. được sử dụng hoàn toàn tương tự như `Equity Market`)* --- ## 7. Quỹ mở (Fund) **Nguồn:** FMarket (fmarket) **Nhóm lệnh:** `market.fund` **Phương Thức** | Method | Mô Tả | Return | | -------------------- | ------------------------- | --------- | | `history()` | Lịch sử NAV quỹ | DataFrame | | `top_holding()` | Top cổ phiếu nắm giữ | DataFrame | | `industry_holding()` | Nắm giữ theo ngành | DataFrame | | `asset_holding()` | Nắm giữ theo loại tài sản | DataFrame | **📝 Chi Tiết Các Phương Thức** **1. Lịch sử NAV Quỹ (history)** Lấy chuỗi dữ liệu lịch sử giá trị tài sản ròng (NAV) của quỹ để đánh giá hiệu suất. - **Tham số:** `limit` (`int`): Số lượng bản ghi giới hạn. ```python from vnstock_data import Market mkt = Market() df_nav = mkt.fund("VFIBS").history(limit=100) ``` **2. Top Cổ Phiếu Nắm Giữ (top_holding)** Liệt kê các cổ phiếu có tỷ trọng lớn nhất trong danh mục đầu tư của quỹ. - **Tham số:** `limit` (`int`): Số lượng cổ phiếu tối đa hiển thị (thường 10-20 mã). ```python top_holding = mkt.fund("VFIBS").top_holding() ``` **3. Nắm Giữ Theo Ngành (industry_holding)** Xem tỷ trọng phân bổ vốn của quỹ vào các lĩnh vực kinh tế (Bất động sản, Ngân hàng, Bán lẻ...). ```python industry = mkt.fund("VFIBS").industry_holding() ``` **4. Nắm Giữ Theo Loại Tài Sản (asset_holding)** Xem tỷ trọng phân bổ tài sản (Cổ phiếu, Trái phiếu, Tiền mặt). ```python asset = mkt.fund("VFIBS").asset_holding() ``` --- ## 8. Bảng giá nhiều mã **Nguồn:** KBS (kbs) **Phương Thức** | Method | Tham Số | Mô Tả | Return | | --------------- | -------------- | ------------------------ | --------- | | `quote()` | `symbols_list` | Giá nhiều mã cùng lúc | DataFrame | | `put_through()` | `symbols_list` | Lệnh thoả thuận nhiều mã | DataFrame | | `odd_lot()` | `symbols_list` | Lệnh lô lẻ nhiều mã | DataFrame | **Ví Dụ** ```python from vnstock_data import Market mkt = Market() df_quotes = mkt.quote(["VIC", "TCB", "HPG", "VNM"]) print(df_quotes) df_odds = mkt.odd_lot(["VIC", "TCB"]) df_pts = mkt.put_through(["VIC", "TCB"]) ``` --- ## 9. Thị trường Quốc tế **Crypto Market (Thị Trường Tiền Mã Hóa)** **Nguồn chính:** Binance (Spot Trading API) **Nhóm lệnh:** `market.crypto` Dữ liệu Crypto Market được liên kết trực tiếp từ **Binance Spot API**. Hỗ trợ truy xuất OHLCV theo khung thời gian (interval) tuỳ chỉnh, Orderbook Horizontal chuẩn hoá đa cấp độ (L1-L10), lịch sử giao dịch (Intraday Trades với cơ chế map Taker/Maker) và báo giá tổng hợp 24h. | Method | Mô Tả | Return | | ----------------------- | ---------------------------------------------------------------- | --------- | | `ohlcv()` | Giá lịch sử Klines đa khung thời gian (1m, 1h, 1d) | DataFrame | | `quote()` | Báo giá ticker lũy kế 24 giờ dạng Snapshot | DataFrame | | `intraday()` | Khớp lệnh chi tiết gần nhất (Time & Sales) | DataFrame | | `order_book()` | Sổ lệnh L1 - L10 (được dàn đều theo chiều ngang) | DataFrame | | `trade_history()` | Truy vấn lịch sử giao dịch bằng ID lệnh cũ (`/historicalTrades`) | DataFrame | | `vwap()` | Giá trung bình theo khối lượng (`/avgPrice`) | DataFrame | | `daily_stats()` | Thống kê phiên giao dịch (`/ticker/tradingDay`) | DataFrame | | `last_price()` | Mức giá khớp lệnh cuối cùng (`/ticker/price`) | DataFrame | | `rolling_stats()` | Thống kê theo cửa sổ trượt (Rolling Window Ticker) | DataFrame | | `reference_price(mode)` | Giá tham chiếu (`price`) hoặc cấu trúc tính toán (`calc`) | DataFrame | **Ví dụ Truy xuất Crypto** ```python from vnstock_data import Market mkt = Market() crypto = mkt.crypto("BTCUSDT") df_quote = crypto.quote() df_ohlcv = crypto.ohlcv(interval="1d", limit=500) df_orderbook = crypto.order_book(limit=10) df_trades = crypto.intraday() df_vwap = crypto.vwap() ``` **Forex, Commodity & Global Index (Thị Trường Cầu & Hàng hóa)** **Nguồn chính:** Dukascopy **Nhóm lệnh:** `market.forex`, `market.commodity`, `market.index` Các domain Forex, Commodity, Index (Chỉ số Quốc Tế) giờ đây được hợp nhất kiến trúc và trực tiếp truy xuất Data **Tick/Phút liên tục** thông qua `Dukascopy`. Hệ thống còn cho phép cơ chế *Resampling* nội bộ đối với các khung cao (1h, 4h, 1d...). | Method | Tham Số Chính | Mô Tả | Return | | --------- | -------------------------------- | ---------------------------------------------------------- | --------- | | `ohlcv()` | `interval`, `length`, `timezone` | Lịch sử giá theo khoảng thời gian tuỳ chọn | DataFrame | | `quote()` | `timezone` | Snapshot giá hiện tại (áp dụng cho Index với scope global) | DataFrame | > **Lưu ý**: Dữ liệu khớp lệnh chi tiết (`trades`) không khả dụng trên nguồn FXSB cho Forex, Commodity và Global Index. > **🌟 Tính năng Timezone Configuration Parameter**: > Lịch sử giá Dukascopy và Quốc tế mặc định được tự động map về quy chuẩn giờ Hệ thống Việt Nam (`Asia/Ho_Chi_Minh` / GMT+7). Tuy nhiên, có thể tuỳ ý ghi đè múi giờ gốc (UTC) hoặc bất kỳ giờ khu vực nào qua tham số `timezone`. **Ví Dụ** ```python mkt = Market() df_eurusd = mkt.forex("EURUSD").ohlcv(interval="1h", length=15) df_utc_eurusd = mkt.forex("EURUSD", timezone="UTC").ohlcv(interval="1h", length=15) df_gold = mkt.commodity("XAUUSD").ohlcv(interval="1d", length=5) df_djia = mkt.index("USA30", scope="global").ohlcv(interval="4h") ``` > **Tip**: Có thể dùng `Reference().search.symbol("tên_tài_sản")` để tìm mã Symbol nếu không chắc chắn. --- ## 💡 Mẹo Sử Dụng ### 1. Gọi nhiều mã cùng lúc ```python mkt = Market() for symbol in symbols: quote = mkt.equity(symbol).quote() all_quotes = mkt.quote(symbols) ``` ### 2. Xử lý lỗi ```python mkt = Market() try: df = mkt.equity("INVALID").ohlcv(start="2026-02-01", end="2026-02-28") except ValueError as e: print(f"Symbol không tồn tại: {e}") except Exception as e: print(f"Lỗi: {e}") ``` --- ## Document: V3.0 # Hướng Dẫn Chuyển Đổi Sang Unified UI v3.0.0 Bản cập nhật v3.0.0 (11/03/2026) mang đến kiến trúc 7 Lớp & Unified UI. Tài liệu này hướng dẫn cách chuyển đổi code đang sử dụng các lớp API/Explorer cũ (`vnstock_data.api`, `vnstock_data.explorer`) sang **Unified UI** — giao diện hợp nhất thế hệ mới. ## 📌 1. Tổng Quan Những Thay Đổi Lớn
Breaking Changes: Các cách sử dụng cũ (truyền source linh hoạt) vẫn tiếp tục được duy trì (Legacy), tuy nhiên các hàm định giá trong Market() sẽ bị gỡ bỏ trong tương lai. Unified UI là giao diện được khuyến nghị bắt buộc.
- **Không cần chỉ định `source`**: Unified UI tự động chọn nguồn dữ liệu tối ưu nhất cho từng tính năng (KBS cho giá lịch sử, VCI cho thống kê phiên...). - **Cú pháp chaining API**: Mọi loại dữ liệu được phân chia vào 7 Domain chính: `Reference`, `Market`, `Fundamental`, `Analytics`, `Insights`, `Macro`. - **Tên method chuẩn hóa**: Ví dụ, `history()` → `ohlcv()`, `intraday()` → `trades()`, `price_depth()` → `order_book()`. --- ## 🔄 2. Bảng Chuyển Đổi API (Mapping) ### Lớp API cũ → Unified UI | Lớp cũ (`vnstock_data.api`) | Unified UI tương ứng (Bản >= 3.0.0) | | :--- | :--- | | `Quote(source, symbol)` | `Market().equity(symbol)` / `.index()` / `.etf()` / `.futures()` / `.warrant()` | | `Company(source, symbol)` | `Reference().company(symbol)` | | `Finance(source, symbol)` | `Fundamental().equity(symbol)` | | `Listing(source)` | `Reference().equity` / `.index` / `.fund` / `.bond` | | `Trading(source)` | `Market().equity(symbol)` | | `Market(source)` | `Analytics().valuation(index)` | | `TopStock(source)` | `Insights().ranking()` | | `Macro(source)` | `Macro().economy()` / `.currency()` / `.commodity()` | | `CommodityPrice(source)` | `Macro().commodity()` | --- ## 📋 3. Chi Tiết Cập Nhật Kèm Code Mẫu ### 3.1 Giá lịch sử & Giao dịch (Quote → Market) **Nguyên tắc chuyển đổi:** 1. Khởi tạo `mkt = Market()`. 2. Chọn đúng lớp tài sản (`equity`, `index`, `futures`, `etf`). 3. Gọi hàm `ohlcv()`, `trades()`. Các tên cũ như `history()` vẫn dùng được qua alias chuyển tiếp. **Cú pháp cũ:** ```python from vnstock_data.api import Quote q = Quote(source="kbs", symbol="VIC") df = q.history(start="2026-01-01", end="2026-03-01", interval="1D") ``` **Cú pháp mới:** ```python from vnstock_data import Market mkt = Market() df = mkt.equity("VIC").ohlcv(start="2026-01-01", end="2026-03-01") ``` ### 3.2 Thông tin công ty (Company → Reference) **Cú pháp cũ:** ```python from vnstock_data.api import Company c = Company(source="vci", symbol="TCB") df_profile = c.overview() ``` **Cú pháp mới:** ```python from vnstock_data import Reference ref = Reference() df_profile = ref.company("TCB").info() ``` ### 3.3 Báo cáo tài chính (Finance → Fundamental) **Cú pháp cũ:** ```python from vnstock_data.api import Finance f = Finance(source="kbs", symbol="HPG") income = f.income_statement(period="Y") ``` **Cú pháp mới:** ```python from vnstock_data import Fundamental fun = Fundamental() income = fun.equity("HPG").income_statement(period="Y") ``` ### 3.4 Định giá thị trường (Market → Analytics) **Cú pháp cũ:** ```python from vnstock_data.api import Market m = Market(source="vnd") pe = m.pe(duration="5Y") ``` **Cú pháp mới:** ```python from vnstock_data import Analytics ana = Analytics() pe = ana.valuation("VNINDEX").pe(duration="5Y") ``` --- ## 🚀 4. Lộ Trình Ngừng Hỗ Trợ (Deprecation Timeline)
Lưu ý các mốc thời gian quan trọng nếu có API bị loại bỏ hoàn toàn trong các phiên bản sau. Trước khi ngừng hỗ trợ, hệ thống sẽ hiển thị cảnh báo song ngữ và tự động chuyển tiếp.
| Tính năng cũ | Thay thế bằng | Hạn cuối (Deadline) | | :--- | :--- | :--- | | `Macro().gdp()`, `Macro().cpi()`, ... | `Macro().economy().gdp()`, ... | 31/8/2026 | | `Macro().exchange_rate()`, `Macro().interest_rate()` | `Macro().currency().exchange_rate()`, ... | 31/8/2026 | | `Reference().derivatives()` | `Reference().futures()` / `.warrant()` | 31/8/2026 | | `Market().pe()`, `.pb()`, `.evaluation()` | `Analytics().valuation(index).pe()`, ... | 31/8/2026 | --- ## Document: V3.2 # Hướng Dẫn Chuyển Đổi Sang API Unified UI v3.2.0 Bản cập nhật v3.2.0 (24/5/2026) mở rộng khả năng của `vnstock_data` bằng việc tích hợp toàn diện nguồn dữ liệu chuyên sâu của ASEAN Securities vào kiến trúc Unified UI. Tài liệu này hướng dẫn cách thay đổi cú pháp mã nguồn (code) từ các cấu trúc cũ (Legacy) sang kiến trúc định tuyến mới để khai thác tối đa hệ thống dữ liệu. ## 📌 1. Tổng Quan Những Thay Đổi Lớn
Breaking Changes: Các tính năng lấy dữ liệu Macro/Commodity đã được quy hoạch lại. Tương tự, cấu trúc shareholders() đã có những thay đổi để trả về cấu trúc phân cấp.
- **Kinh tế Vĩ mô (Macro)**: Cấu trúc truy xuất Vĩ mô cũ là "phẳng". Cấu trúc mới nhóm hàm theo 3 Domain (`economy`, `currency`, `global`). - **Giá Hàng hoá (Commodity)**: Chuyển sang lớp `Macro().commodity()`. Lược bỏ hậu tố `_vn` hoặc `_global` trong tên hàm. - **Insights & Analytics (Layer 7)**: Các tính năng phân tích tâm lý, khối ngoại và tìm kiếm cổ phiếu nằm rải rác ở lớp `TopStock` và một phần `Market` đã được quy hoạch chuẩn chỉnh về `Insights()`. --- ## 🔄 2. Bảng Chuyển Đổi API (Mapping) ### Insights & Analytics (Layer 7) Trước bản 3.2.0, các tính năng phân tích tâm lý, khối ngoại và tìm kiếm cổ phiếu nằm rải rác ở lớp `TopStock` và một phần `Market`. Nay chúng được quy hoạch chuẩn chỉnh về `Insights()`. | Legacy API (Bản < 3.2.0) | Unified UI API (Bản >= 3.2.0) | Tình trạng | | :------------------------- | :---------------------------------------------------------------------------------- | :------------------------------ | | `TopStock().gainer()` | `Insights().sentiment.contribution()` (Gợi ý thay thế) | Legacy (Vẫn hoạt động) | | `TopStock().foreign_buy()` | `Insights().flow.foreign()` | Legacy (Vẫn hoạt động) | | `Market().pe()` | `Insights().equity("MÃ").peer_compare()` hoặc `Insights().sector("MÃ").valuation()` | Cũ (Bị loại bỏ hoặc điều hướng) | | Không có | `Insights().sentiment.breadth()` | **MỚI** | | Không có | `Insights().flow.active()` | **MỚI** | | Không có | `Insights().sector("bank").rrg()` | **MỚI** | --- ### Kinh tế Vĩ mô (Layer 6 - Macro) Cấu trúc truy xuất Vĩ mô cũ là "phẳng" (gọi trực tiếp hàm từ class). Cấu trúc mới nhóm hàm theo 3 Domain (economy, currency, global). | Legacy API (Bản < 3.2.0) | Unified UI API (Bản >= 3.2.0) | Tình trạng | | :------------------------ | :----------------------------------------------------------------------------------------- | :--------------------- | | `Macro().gdp()` | `Macro().economy().gdp()` | Legacy (Vẫn hoạt động) | | `Macro().cpi()` | `Macro().economy().cpi()` | Legacy (Vẫn hoạt động) | | `Macro().interest_rate()` | `Macro().currency().interbank_rate()` (Nguồn mới) hoặc `Macro().currency().deposit_rate()` | Legacy (Vẫn hoạt động) | | `Macro().exchange_rate()` | `Macro().currency().exchange_rate()` | Legacy (Vẫn hoạt động) | | Không có | `Macro().global.bond_yield()` | **MỚI** | | Không có | `Macro().global.fed_rate()` | **MỚI** | --- ### Giá Hàng hoá (Commodity) Lớp `CommodityPrice()` cũ truy xuất từ hệ thống SPL. Cấu trúc mới `Macro().commodity()` sử dụng dữ liệu quốc tế của ASEAN làm mặc định, và tích hợp cơ chế Fallback (tự động chuyển nguồn) khi người dùng truy vấn hàng hoá nội địa. | Legacy API (Bản < 3.2.0) | Unified UI API (Bản >= 3.2.0) | | :--------------------------------- | :---------------------------------------------------------------------------- | | `CommodityPrice().gold_global()` | `Macro().commodity().gold(market="GLOBAL")` hoặc `Macro().commodity().gold()` | | `CommodityPrice().gold_vn()` | `Macro().commodity().gold(market="VN")` | | `CommodityPrice().steel_hrc()` | `Macro().commodity().steel()` | | `CommodityPrice().steel_d10()` | `Macro().commodity().steel(market="VN")` | | `CommodityPrice().pork_north_vn()` | `Macro().commodity().pork(market="VN")` | | `CommodityPrice().oil_crude()` | `Macro().commodity().oil_crude()` | **Nguyên tắc chuyển đổi:** 1. Thay chữ `CommodityPrice()` bằng `Macro().commodity()`. 2. Lược bỏ hậu tố `_vn` hoặc `_global` trong tên hàm (VD: `gold_vn()` chuyển thành `gold()`). 3. Truyền thêm tham số `market="VN"` nếu muốn lấy dữ liệu nội địa Việt Nam. --- ## 📋 3. Chi Tiết Cập Nhật (Kèm Code Mẫu) ### Thay đổi: Chuẩn hoá Cơ cấu Cổ đông & Cổ đông lớn (v3.2.1) Kể từ phiên bản v3.2.1, phương thức `shareholders()` được chuẩn hoá nhất quán trên cả API Adapter thường và Unified UI, hỗ trợ tham số `mode` để gom nhóm các API liên quan đến sở hữu/cơ cấu: - **detailed** (mặc định): Trả về danh sách chi tiết cổ đông lớn kèm trường phân loại `shareholder_type` (`Individual` / `Organization`). - **summary**: Trả về cơ cấu sở hữu tổng hợp (tỷ lệ sở hữu nhà nước, nước ngoài, ban lãnh đạo...). | Legacy API (Bản < 3.2.1) | Unified UI/API API (Bản >= 3.2.1) | Nguồn hỗ trợ | | :---------------------------------- | :---------------------------------------------------------------- | :------------------: | | `Company(source="KBS").ownership()` | `Company(source="KBS").shareholders(mode="summary")` | KBS (Bị thay thế) | | Không hỗ trợ | `Company(source="VCI").shareholders(mode="summary")` | VCI (Mới) | | `ref.company("TCB").shareholders()` | `ref.company("TCB").shareholders(mode="summary")` (hoặc `mode="detailed"`) | Unified UI (VCI/KBS) |
  • Nguồn ASEAN chỉ hỗ trợ mode=detailed. Nếu gọi mode=summary với nguồn ASEAN sẽ ném ra ngoại lệ ValueError tiếng Việt trực quan.
  • Tất cả các cột dữ liệu của nguồn VCI đã được chuẩn hoá ngắn gọn sang dạng chữ thường (lowercase) chuẩn database (ví dụ: state_percentage, foreign_percentage, v.v.).
--- --- ### Thay đổi: Chuẩn hoá Data Model Tin Tức (company.news) Kể từ phiên bản v3.2.3, phương thức `news()` truy xuất tin tức công ty đã được chuẩn hoá (Unified) hoàn toàn giữa các nguồn (`VCI`, `KBS`, `CAFEF`) với cùng một cấu trúc tham số đầu vào và một Data Model đầu ra duy nhất, thay vì schema phân mảnh như trước đây. **1. Tham số hỗ trợ được đồng bộ:** Hàm `news()` hiện hỗ trợ bộ tham số tuỳ chỉnh mạnh mẽ bao gồm: `start`, `end`, `length` (mặc định 90 ngày), `limit` (mặc định 10000), và `mode` (`list` hoặc `detail`). Tham số `**kwargs` cũng được proxy trực tiếp xuống hàm đích nếu nguồn dữ liệu hỗ trợ. **2. Data Model chuẩn hoá:** Tất cả các nguồn sẽ trả về chung một schema 10 cột nhất quán, giúp dễ dàng nối (concat) dữ liệu phân tích: `id`, `symbol`, `title`, `summary`, `content`, `publish_time`, `source`, `url`, `category`, `image_url` | Tính năng | Legacy API (Bản < 3.2.x) | Unified API (Bản >= 3.2.x) | | :------------------- | :-------------------------------------- | :----------------------------------------------------------------- | | **Cấu trúc trả về** | Tuỳ thuộc vào nguồn (khác biệt tên cột) | Schema 10 cột đồng nhất cho mọi nguồn | | **Cào nội dung báo** | Chỉ KBS, schema khác biệt | Hỗ trợ `mode=detail` cho mọi nguồn (VCI, KBS, CAFEF) | | **Khung thời gian** | VCI không hỗ trợ | Hỗ trợ `start`, `end`, `length` cho toàn bộ nguồn qua lớp Abstract |
Phân biệt vnstock_data và vnstock_news:
  • Hàm news() trong vnstock_data tập trung vào tin tức đã được phân loại cho một doanh nghiệp cụ thể (Bao gồm: thông báo nội bộ, công bố thông tin, tin từ sở giao dịch, tin tức trực tiếp về mã cổ phiếu).
  • Gói vnstock_news chuyên dùng để cào tin tức đại chúng chưa dán nhãn trực tiếp từ các trang báo (thích hợp làm nguyên liệu thô cho mô hình ML/AI hoặc sử dụng AI Agent để gán nhãn).
--- ### Khám Phá: Tổng Quan API Tree Mới Để khám phá trực quan toàn bộ các hàm được hỗ trợ trong hệ thống mới (kèm theo nhãn đánh dấu `[Experimental]`), bạn chỉ cần gọi 2 lệnh đơn giản: ```python from vnstock_data import show_api from vnstock_data.ui import Insights, Macro # Xem sơ đồ phân tích tâm lý, dòng tiền show_api(Insights()) # Xem sơ đồ vĩ mô và hàng hoá show_api(Macro()) ``` --- ## Document: Hướng dẫn Nâng Cấp Phiên Bản v3.2.8 Tài liệu này cung cấp hướng dẫn chi tiết để giúp bạn nâng cấp code từ các phiên bản cũ lên **vnstock\_data v3.2.8** trở đi. Trong phiên bản mới nhất, dữ liệu báo cáo tài chính (Fundamental) được **tái cấu trúc toàn diện**, áp dụng bộ chuẩn hóa theo chuẩn mực kế toán Việt Nam (VAS) cho tất cả các nguồn dữ liệu. Điều này giúp loại bỏ sự sai lệch tên gọi giữa các nguồn, đồng nhất dữ liệu và đảm bảo ngữ cảnh tài chính chính xác cho các thuật toán phân tích định lượng và AI. *** ## 🚨 Những Thay Đổi Quan Trọng
Nguồn dữ liệu Báo cáo tài chính mặc định đã được chuyển sang VCI để cung cấp mức độ chi tiết tốt nhất. Tuy nhiên, kết nối tới VCI có thể bị chặn trên môi trường Google Colab.

Khuyến nghị: Cài đặt và chạy code trong môi trường cục bộ (local PC) để sử dụng trơn tru nhất.
Tải bảng dữ liệu tham chiếu Agent Guide
### 1. Thay Đổi Định Dạng Đầu Ra Định dạng trả về mặc định cho tất cả các hàm tài chính (như Bảng cân đối kế toán, Kết quả kinh doanh, Lưu chuyển tiền tệ) hiện nay là **Tidy Data (Long Format)** thay vì bảng ngang (Wide Format) như trước. Mỗi hàng dữ liệu sẽ bao gồm các thuộc tính chuẩn hóa: * **`id`**: Mã định danh (primary key) duy nhất cho mỗi tiêu chí (Ví dụ: `BS_CASH_AND_PRECIOUS_METALS`). Sử dụng `id` giúp code không bị gãy khi tên tiêu chí hiển thị thay đổi. * **`name`**: Tên tiêu chí theo chuẩn mực kế toán. * **`unit`**: Đơn vị dữ liệu. * **`order`**: Thứ tự trình bày tiêu chí trong báo cáo gốc, giúp bạn khôi phục đúng cấu trúc khi pivot. * **`level`**: Thể hiện phân cấp tiêu chí cha/con. > **💡 Mẹo:** Nếu bạn cần phân tích dữ liệu dạng bảng ngang quen thuộc (nhiều kỳ nằm trên các cột), bạn có thể thêm tham số `format="wide"` hoặc `format="time_series"` khi gọi hàm. Khi đó, tên các cột sẽ được sử dụng bằng **Semantic ID** chuẩn hoá mới thay vì các tên cột snake\_case cũ bị phụ thuộc vào nguồn dữ liệu. ### 2. Thay Đổi Tham Số Hàm Các hàm tải dữ liệu tài chính như `balance_sheet()`, `income_statement()`, `cash_flow()`, `ratio()` đã thay đổi danh sách tham số: * **Xóa bỏ:** Tham số `dropna` đã bị thay thế thành `drop_empty`. * **Thêm mới:** Tham số `format` để cấu hình định dạng (`'long'`, `'wide'`, `'time_series'`). * **Thêm mới:** Tham số `com_type` giúp cố định loại hình công ty (`'Regular'`, `'Bank'`, `'Securities'`, `'Insurance'`) để áp dụng Taxonomy phù hợp thay vì tự động đoán ngầm định. *** ## 📊 Bảng Tham Chiếu (Mapping) ### Bảng Cân Đối Kế Toán (Balance Sheet) | Tên Chỉ Tiêu (Theo VAS) | Cột Mới (Semantic ID) | Tên Cột Cũ (Nguồn MAS) | Tên Cột Cũ (Nguồn KBS) | | ---------------------------------- | --------------------------------------------------- | ---------------------------------------- | ----------------------------- | | Tiền và các khoản tương đương tiền | `BS_CASH_AND_PRECIOUS_METALS` | `i_cash_gold_and_silver_precious_stones` | `1_cash_and_cash_equivalents` | | Tài sản cố định | `BS_FIXED_ASSETS` | `x_fixed_assets` | `ix_fixed_assets` | | Tài sản cố định hữu hình | `BS_TANGIBLE_FIXED_ASSETS` | `1_tangible_fixed_assets` | `1_tangible_fixed_assets` | | Nguyên giá | `BS_TANGIBLE_FIXED_ASSETS_COST` | `a_cost` | `cost` | | Giá trị hao mòn luỹ kế | `BS_TANGIBLE_FIXED_ASSETS_ACCUMULATED_DEPRECIATION` | `b_accumulated_depreciation` | `accumulated_depreciation` | | Tài sản cố định vô hình | `BS_INTANGIBLE_FIXED_ASSETS` | `3_intangible_fixed_assets` | `3_intangible_fixed_assets` | ### Lưu Chuyển Tiền Tệ (Cash Flow) | Tên Chỉ Tiêu (Theo VAS) | Cột Mới (Semantic ID) | Tên Cột Cũ (Nguồn MAS) | Tên Cột Cũ (Nguồn KBS) | | ----------------------- | ------------------------------------ | -------------------------------------------------------- | ----------------------------------- | | Lợi nhuận trước thuế | `CF_PROFIT_BEFORE_TAX` | `1_profit_before_tax` | `profit_before_tax` | | Khấu hao TSCĐ và BĐSĐT | `CF_DEPRECIATION_AND_AMORTISATION` | `depreciation_of_fixed_assets_and_investment_properties` | `depreciation_and_amortization` | | Các khoản dự phòng | `CF_PROVISIONS` | `reversal_of_provisions_provisions` | `reversal_of_provisions_provisions` | | Chi phí lãi vay | `CF_INTEREST_EXPENSE` | `borrowing_costs` | `interest_expense` | | Thu lãi và cổ tức | `CF_INTEREST_AND_DIVIDENDS_RECEIVED` | `interest_income_and_dividends` | `accrued_interest_income` | ### Báo Cáo Kết Quả Kinh Doanh (Income Statement) | Tên Chỉ Tiêu (Theo VAS) | Cột Mới (Semantic ID) | Tên Cột Cũ (Nguồn MAS) | Tên Cột Cũ (Nguồn KBS) | | ----------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ | | Tổng lợi nhuận kế toán trước thuế | `IS_PROFIT_BEFORE_TAX` | `xi_profit_before_tax` | `31_taxable_profit` | | Lợi nhuận sau thuế | `IS_NET_PROFIT_AFTER_TAX` | `xiii_net_profit_after_tax` | `34_profit_after_tax` | | Lợi nhuận sau thuế của cổ đông công ty mẹ | `IS_PROFIT_AFTER_TAX_FOR_SHAREHOLDERS_OF_PARENT_COMPANY` | `xv_net_profit_atttributable_to_the_equity_holders_of_the_bank` | `36_profit_after_tax_for_shareholders_of_the_parent_company` | | Thu nhập lãi thuần | `IS_NET_INTEREST_INCOME` | `i_net_interest_income` | `i_net_interest_income` | | Lãi thuần từ hoạt động dịch vụ | `IS_NET_FEE_AND_COMMISSION_INCOME` | `ii_net_fee_and_commission_income` | `ii_net_fee_and_commission_income` | *** Bạn có thể tra cứu nhanh chóng hàm và các tham số mới nhất thông qua bảng tham chiếu [vnstock\_3.2.8\_schema\_migration\_reference.csv](/account?section=packages\&tab=exclusive-files) tải về từ tài khoản đã thực hiện Tài trợ dự án. Chúc các bạn Vibe Coding hiệu quả với hệ thống dữ liệu hoàn toàn mới! --- ## Document: Hướng dẫn Nâng Cấp Phiên Bản v3.2.9 Phiên bản v3.2.9 khắc phục các sai lệch của dữ liệu khớp lệnh trong phiên, nên **số liệu bạn nhận được sẽ khác bản cũ**. Nếu code của bạn không dùng `trades()` hoặc `intraday()` và bạn đang sử dụng bản `3.2.8`, hãy nâng cấp thẳng lên v3.2.9, không cần chỉnh gì. *** ## 1. Cột `time` của `trades()` cổ phiếu nay có múi giờ Nguồn mặc định cho dữ liệu khớp lệnh cổ phiếu chuyển từ KBS sang VND, kéo theo cột `time` đổi kiểu từ `datetime64[ns]` sang `datetime64[ns, Asia/Ho_Chi_Minh]`. So sánh với mốc thời gian không múi giờ sẽ báo lỗi: ```python df = Market().equity('ACB').trades() df[df['time'] > pd.Timestamp('2026-09-04 09:30')] # TypeError: Invalid comparison between dtype=datetime64[ns, Asia/Ho_Chi_Minh] and Timestamp ``` Chọn một trong hai cách: ```python # Gắn múi giờ cho mốc so sánh df[df['time'] > pd.Timestamp('2026-09-04 09:30', tz='Asia/Ho_Chi_Minh')] # Hoặc bỏ múi giờ khỏi cột để giữ nguyên code phía sau df['time'] = df['time'].dt.tz_localize(None) ``` Muốn giữ nguyên nguồn KBS như cũ, đặt một lần lúc khởi động chương trình: ```python from vnstock_data.ui.config import set_route set_route('market.equity.trades', 'kbs', 'quote', 'Quote', 'intraday') ``` Nhóm phái sinh vẫn dùng KBS, không đổi. *** ## 2. Khối lượng và nhãn `match_type` thay đổi * **Khối lượng khớp lệnh giảm về đúng thực tế.** Trước đây nguồn KBS trả cả hai chiều mua/bán nên tổng khối lượng bị gấp đôi, ảnh hưởng nặng nhất tới hợp đồng tương lai. Nếu có báo cáo hay kết quả backtest xây trên số cũ, hãy chạy lại. * **Nhãn ATO/ATC chính xác hơn.** Phiên ATO của hợp đồng tương lai được nhận diện đúng khung 08:45–09:00, đồng thời các lệnh không rõ chiều không còn bị gán nhầm thành ATO/ATC. Nếu code lọc theo `match_type` để tính khối lượng phiên định kỳ, con số sẽ thay đổi. * **Xuất hiện nhãn `PLO`** với các mã sàn HNX. Nếu code giả định `match_type` chỉ có `Buy`/`Sell`, hãy bổ sung nhánh xử lý. *** ## 3. Số bản ghi mặc định cho phái sinh: 1.000 → 100.000 Một phiên của `VN30F1M` có gần 100.000 lệnh khớp, giới hạn cũ chỉ đủ phủ cụm ATC cuối phiên. Mặc định mới lấy trọn phiên, đổi lại lời gọi mất vài giây: ```python Market().futures('VN30F1M').trades() # trọn phiên Market().futures('VN30F1M').trades(limit=1000) # nhanh, chỉ dữ liệu gần nhất ``` Cổ phiếu giữ mặc định 1.000 bản ghi như cũ. Khi dữ liệu trả về chưa phủ hết phiên, thư viện sẽ cảnh báo kèm mức giới hạn nên tăng lên. Nếu chạy tác vụ tự động và không cần cảnh báo này: ```python import warnings warnings.filterwarnings('ignore', message='.*chưa phủ hết phiên.*') ``` *** ## 4. Nên chuyển khỏi nguồn VCI cho dữ liệu khớp lệnh Nguồn API đã áp giới hạn **100 bản ghi mỗi lượt gọi** cho dữ liệu khớp lệnh của VCI. Lấy trọn một phiên vì thế cần hàng trăm lượt gọi và thường bị ngắt kết nối giữa chừng, đặc biệt với mã thanh khoản lớn và hợp đồng tương lai. ```python from vnstock_data import Quote df = Quote(source='VCI', symbol='VN30F1M').intraday() # không còn phù hợp df = Quote(source='KBS', symbol='VN30F1M').intraday() # có nhãn Mua/Bán chủ động df = Quote(source='MAS', symbol='VN30F1M').intraday() df = Quote(source='VND', symbol='VN30F1M').intraday() ``` Nếu dùng Unified UI thì không cần làm gì, `trades()` vốn không định tuyến qua VCI. VCI vẫn dùng tốt cho các nhóm dữ liệu khác. *** ## Không cần chỉnh code Mã phái sinh kiểu cũ như `VN30F1M` nay tự động chuyển sang mã KRX ở mọi lớp truy xuất nên không còn trả về kết quả rỗng; bổ sung `Market().future(...)` bên cạnh `Market().futures(...)`; sửa lỗi giá và mốc thời gian sai ở nguồn MAS; cây API `show_api()` hiển thị đầy đủ trở lại. --- ## Document: Dữ Liệu Tham Chiếu (Reference)
Agent Guide Notebook minh hoạ
  • Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý.
  • Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
## 📌 Tổng Quan Nhóm **Dữ liệu tham chiếu** cung cấp thông tin nền tảng, cố định về các sản phẩm tài chính như công ty, chỉ số, ngành, danh sách mã chứng khoán, quỹ ETF, trái phiếu, sự kiện, v.v. Đây là dữ liệu **ít bị thay đổi** và thường được sử dụng để **tra cứu** hoặc làm **dữ liệu gốc**. ### 🏗️ Cấu Trúc Nhóm Lệnh ```python Reference() ├── .company(symbol) # Thông tin công ty ├── .equity # Danh sách cổ phiếu ├── .index # Danh sách chỉ số ├── .industry # Ngành kinh tế ├── .fund # Quỹ đầu tư mở ├── .etf # Quỹ ETF ├── .bond # Trái phiếu ├── .events # Sự kiện thị trường ├── .search # Tìm kiếm toàn cầu ├── .futures(symbol) # Hợp đồng tương lai └── .warrant(symbol) # Chứng quyền ``` ## 1. Thông tin công ty (company) **Nguồn:** VCI, KBS **Nhóm lệnh:** `company` **Danh sách hàm** | Hàm | Tham số | Mô tả | | ---------------- | ------- | -------------------------------------------------------------------------------- | | `info()` | - | Thông tin tổng quan công ty | | `shareholders()` | `mode` | Cơ cấu cổ đông và cổ đông lớn. Giá trị: `'detailed'` (mặc định) hoặc `'summary'` | | `officers()` | - | Danh sách quản lý cấp cao | | `subsidiaries()` | - | Danh sách công ty con | | `news()` | - | Tin tức công ty | | `events()` | - | Sự kiện công ty | **📝 Hướng Dẫn Sử Dụng** **1. Thông tin tổng quan (info)** Truy xuất hồ sơ cơ bản của doanh nghiệp, ngày niêm yết, số lượng cổ phiếu lưu hành. ```python from vnstock_data import Reference ref = Reference() df_profile = ref.company("TCB").info() ``` **2. Cơ cấu & danh sách cổ đông (shareholders)** Truy xuất cơ cấu sở hữu tổng hợp hoặc danh sách chi tiết và tỷ lệ sở hữu của các cổ đông lớn. - **Tham số:** `mode` (chuỗi): `'detailed'` (danh sách chi tiết cổ đông lớn - mặc định) hoặc `'summary'` (cơ cấu sở hữu tổng hợp như nhà nước, khối ngoại, v.v.). ```python df_detailed = ref.company("VIC").shareholders(mode="detailed") df_summary = ref.company("VIC").shareholders(mode="summary") ``` **3. Ban lãnh đạo (officers)** Lấy danh sách thành viên Hội đồng quản trị, Ban giám đốc. - **Tham số:** `filter_by` (chuỗi): `'working'` (đang làm việc - mặc định), `'resigned'` (đã nghỉ), hoặc `'all'`. ```python df_officers = ref.company("HPG").officers(filter_by="working") ``` **4. Công ty con (subsidiaries)** Tra cứu danh sách các công ty con, công ty liên kết của doanh nghiệp. - **Tham số:** `filter_by` (chuỗi): `'all'` (tất cả - mặc định), `'subsidiary'` (công ty con), hoặc `'affiliate'` (công ty liên kết). ```python df_subs = ref.company("TCB").subsidiaries(filter_by="subsidiary") ``` **5. Tin tức (news)** Danh sách các bài báo, tin tức mới nhất liên quan đến mã chứng khoán. - **Tham số:** `start` (ngày bắt đầu), `end` (ngày kết thúc), `length` (số ngày lùi lại mặc định 90), `limit` (giới hạn bài viết), `mode` (`'list'` hoặc `'detail'`), `**kwargs` (tuỳ chỉnh phụ thuộc từng nguồn dữ liệu).
Phân biệt vnstock_data và vnstock_news:
  • Hàm news() trong vnstock_data tập trung vào tin tức đã được phân loại cho một doanh nghiệp cụ thể (Bao gồm: thông báo nội bộ, công bố thông tin, tin từ sở giao dịch, tin tức trực tiếp về mã cổ phiếu).
  • Gói vnstock_news chuyên dùng để lấy tự động tin tức đại chúng chưa phân loại trực tiếp từ các trang báo (thích hợp làm nguyên liệu thô cho mô hình học máy hoặc AI phân tích ngữ nghĩa).
```python df_news_list = ref.company("TCB").news(length=90, mode='list') df_news_detail = ref.company("TCB").news(length=10, mode='detail', limit=50) ``` **6. Sự kiện (events)** Lấy lịch trả cổ tức, họp đại hội cổ đông... của riêng mã chứng khoán đó. ```python df_events = ref.company("TCB").events() ``` --- ## 2. Danh sách cổ phiếu (equity) **Nguồn:** VCI **Nhóm lệnh:** `equity` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------------------- | ------------------ | ---------------------------------- | | `list()` | - | Toàn bộ danh sách cổ phiếu | | `list_by_group()` | `group` | Cổ phiếu theo nhóm (VN30, HOSE...) | | `list_by_exchange()` | - | Cổ phiếu theo sàn (HSX, HNX...) | | `list_by_industry()` | `icb_code`, `lang` | Cổ phiếu theo ngành ICB | **📝 Hướng Dẫn Sử Dụng** **1. Toàn bộ danh sách cổ phiếu (list)** Tra cứu toàn bộ các mã cổ phiếu đang giao dịch trên thị trường. ```python from vnstock_data import Reference ref = Reference() all_symbols = ref.equity.list() ``` **2. Cổ phiếu theo nhóm (list_by_group)** Liệt kê các cổ phiếu thuộc các rổ chỉ số phổ biến hoặc nhóm thị trường. - **Tham số:** `group` (chuỗi): Mã nhóm chỉ số (VD: `"VN30"`, `"HNX30"`, `"HOSE"`...). ```python vn30 = ref.equity.list_by_group("VN30") ``` **3. Cổ phiếu theo sàn (list_by_exchange)** Trả về danh sách cổ phiếu được phân nhóm sẵn theo sàn giao dịch (HOSE, HNX, UPCOM). ```python exchange_stocks = ref.equity.list_by_exchange() ``` **4. Cổ phiếu theo ngành (list_by_industry)** Lọc cổ phiếu theo phân ngành ICB. - **Tham số:** - `icb_code` (chuỗi, tùy chọn): Mã phân ngành (Ví dụ: `"8773"`). Nếu không truyền sẽ trả về tất cả. - `lang` (chuỗi): Ngôn ngữ (`'vi'` hoặc `'en'`). Mặc định `'vi'`. ```python icb_stocks = ref.equity.list_by_industry(icb_code="8355", lang="vi") ``` --- ## 3. Danh sách chỉ số (index) **Nguồn:** KBS, VCI **Nhóm lệnh:** `index` **Danh sách hàm** | Hàm | Tham số | Mô tả | | ---------------------- | ------- | -------------------------------------- | | `list()` | - | Toàn bộ danh sách chỉ số kèm thông tin | | `groups()` | - | Liệt kê các nhóm chỉ số | | `members(group)` | `group` | Thành phần cổ phiếu của chỉ số | | `list_by_group(group)` | `group` | Chỉ số theo phân nhóm | **📝 Hướng Dẫn Sử Dụng** **1. Liệt kê tất cả chỉ số (list)** Liệt kê danh sách tất cả các chỉ số chuẩn (VN30, VN100, HNX30...) kèm theo thông tin chi tiết. ```python from vnstock_data import Reference ref = Reference() all_indices = ref.index.list() ``` **2. Nhóm chỉ số (groups)** Danh sách các phân nhóm chỉ số hiện có (VD: Chỉ số sàn HOSE, Chỉ số ngành). ```python groups = ref.index.groups() ``` **3. Thành phần chỉ số (members)** Liệt kê các mã cổ phiếu cấu thành nên một chỉ số (VD: 30 mã trong VN30). - **Tham số:** `group` (chuỗi): Tên chỉ số (VD: `"VN30"`). ```python vn30_members = ref.index.members("VN30") ``` **4. Chi tiết một chỉ số (info, description)** Xem thông tin hoặc mô tả chi tiết của một chỉ số bằng cách truyền thẳng mã vào nhóm lệnh. ```python vn30_detail = ref.index("VN30") print(vn30_detail.info()) print(vn30_detail.description()) ``` --- ## 4. Ngành kinh tế (industry) **Nguồn:** VCI **Nhóm lệnh:** `industry` **Danh sách hàm** | Hàm | Tham số | Mô tả | | ----------- | ------- | ----------------------------- | | `list()` | - | Toàn bộ danh sách ngành ICB | | `sectors()` | - | Phân loại cổ phiếu theo ngành | **📝 Hướng Dẫn Sử Dụng** **1. Toàn bộ ngành ICB (list)** Tra cứu cây phân loại nhóm ngành chuẩn quốc tế ICB (từ cấp 1 đến cấp 4) dành cho thị trường Việt Nam. - **Tham số:** `lang` (chuỗi): Ngôn ngữ trả về (`'vi'` hoặc `'en'`). Mặc định `'vi'`. ```python from vnstock_data import Reference ref = Reference() industries = ref.industry.list(lang="vi") ``` **2. Phân loại cổ phiếu theo ngành (sectors)** Liệt kê các mã cổ phiếu và đối chiếu với các nhóm ngành ICB tương ứng. - **Tham số:** - `icb_code` (chuỗi, tùy chọn): Lọc riêng một mã ngành cụ thể. Mặc định bỏ trống. - `lang` (chuỗi): Ngôn ngữ (`'vi'` hoặc `'en'`). Mặc định `'vi'`. ```python sectors = ref.industry.sectors() ``` --- ## 5. Quỹ đầu tư mở (fund) **Nguồn:** FMarket **Nhóm lệnh:** `reference.fund` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------- | ------- | ----------------------- | | `list()` | - | Danh sách quỹ đầu tư mở | **📝 Hướng Dẫn Sử Dụng** **1. Danh sách quỹ mở (list)** Tra cứu danh sách tất cả các quỹ mở đang hoạt động trên hệ thống FMarket. ```python from vnstock_data import Reference ref = Reference() funds = ref.fund.list() ``` **2. Thông tin chi tiết của quỹ** Truy xuất thông tin phân bổ tài sản và báo cáo tăng trưởng của một quỹ cụ thể. - **Cách dùng:** Có thể truyền mã quỹ vào nhóm lệnh (VD: `ref.fund("Mã_Quỹ")`). ```python fmarket = ref.fund("FUEVNFND") top_holdings = fmarket.top_holding() industry = fmarket.industry_holding() nav = fmarket.nav_report() ``` --- ## 6. Quỹ hoán đổi danh mục (etf) **Nguồn:** KBS **Nhóm lệnh:** `etf` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------- | ------- | -------------------- | | `list()` | - | Danh sách tất cả quỹ | **📝 Hướng Dẫn Sử Dụng** **Danh sách quỹ ETF (list)** Tra cứu toàn bộ các quỹ ETF đang niêm yết và giao dịch trên thị trường chứng khoán. ```python from vnstock_data import Reference ref = Reference() etf_list = ref.etf.list() ``` --- ## 7. Trái phiếu (bond) **Nguồn:** KBS, VCI **Nhóm lệnh:** `bond` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------- | ----------- | ------------------------------------------------------------------------------------------------- | | `list()` | `bond_type` | Danh sách trái phiếu. Các loại: `'all'`, `'corporate'` (doanh nghiệp), `'government'` (chính phủ) | | `info()` | - | Thông tin chi tiết trái phiếu (yêu cầu truyền mã trái phiếu) | **📝 Hướng Dẫn Sử Dụng** **1. Danh sách trái phiếu (list)** Liệt kê các mã trái phiếu đang được phát hành và giao dịch. - **Tham số:** `bond_type` (chuỗi): Lọc loại trái phiếu. Mặc định `'all'`. ```python from vnstock_data import Reference ref = Reference() all_bonds = ref.bond().list(bond_type="all") corp_bonds = ref.bond().list(bond_type="corporate") ``` **2. Thông tin chi tiết trái phiếu (info)** Lấy thông tin tóm tắt của một mã trái phiếu cụ thể. ```python bond_info = ref.bond("CII425021").info() ``` --- ## 8. Sự kiện (events) **Nguồn:** VCI, [Vnstock](https://github.com/thinh-vu/vnstock/blob/main/vnstock/core/utils/market_events.py) **Nhóm lệnh:** `events` **Danh sách hàm** | Hàm | Tham số | Mô tả | | ------------ | --------------------------------------------- | -------------------------------------------- | | `calendar()` | `start`, `end`, `event_type`, `page`, `limit` | Lịch sự kiện (cổ tức, họp đại hội, IPO...) | | `market()` | `start`, `end`, `event_type` | Sự kiện thị trường chung (nghỉ lễ, sự cố...) | **Loại sự kiện cho calendar():** - `'dividend'`: Cổ tức, phát hành cổ phiếu - `'insider'`: Giao dịch nội bộ - `'agm'`: Đại hội cổ đông - `'others'`: Các biến động khác **📝 Hướng Dẫn Sử Dụng** **1. Lịch sự kiện (calendar)** Tra cứu lịch chi trả cổ tức, họp cổ đông, giao dịch của ban lãnh đạo... theo thời gian. - **Tham số:** - `start`, `end` (chuỗi, tùy chọn): Khoảng thời gian tra cứu. - `event_type` (chuỗi, tùy chọn): Lọc theo loại sự kiện. - `page` (số nguyên): Số trang phân trang. - `limit` (số nguyên): Số lượng kết quả tối đa. ```python from vnstock_data import Reference ref = Reference() events = ref.events.calendar(start="2026-03-01", end="2026-03-31") dividends = ref.events.calendar( start="2026-03-01", end="2026-03-31", event_type="dividend" ) ``` **2. Sự kiện thị trường (market)** Tra cứu danh sách ngày nghỉ lễ giao dịch, ngày hệ thống bảo trì hoặc xảy ra sự cố. ```python market_events = ref.events.market() ``` --- ## 9. Tìm kiếm (search) **Nguồn:** MSN **Nhóm lệnh:** `search` **Danh sách hàm** | Hàm | Tham số | Mô tả | | ---------- | -------------------------- | --------------------------------------------------------------------------- | | `symbol()` | `query`, `locale`, `limit` | Tìm kiếm mã giao dịch trên toàn thế giới (cổ phiếu, tiền mã hóa, ngoại hối) | **📝 Hướng Dẫn Sử Dụng** **Tìm kiếm mã giao dịch (symbol)** Cung cụ tìm kiếm tự do cho phép gõ từ khóa (như tên công ty, tiền mã hóa, hàng hóa) để tìm mã giao dịch chính xác nhất. - **Tham số:** - `query` (chuỗi): Từ khóa (VD: `"VNM"`, `"Bitcoin"`, `"Vàng"`). - `locale` (chuỗi, tùy chọn): Ngôn ngữ và khu vực ưu tiên (VD: `"vi-vn"`, `"en-us"`). - `limit` (số nguyên, tùy chọn): Số lượng kết quả tối đa. ```python from vnstock_data import Reference ref = Reference() results = ref.search.symbol("VNM") btc = ref.search.symbol("Bitcoin", limit=5) ``` --- ## 10. Hợp đồng tương lai (futures) **Nguồn:** KBS, VCI **Nhóm lệnh:** `derivatives.futures` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------- | ------- | ----------------------------------------------- | | `list()` | - | Danh sách các hợp đồng tương lai | | `info()` | - | Thông tin chi tiết (yêu cầu truyền mã hợp đồng) | **📝 Hướng Dẫn Sử Dụng** **1. Danh sách hợp đồng tương lai (list)** Lấy toàn bộ danh sách các hợp đồng phái sinh đang giao dịch. ```python from vnstock_data import Reference ref = Reference() futures_list = ref.futures().list() ``` **2. Thông tin chi tiết (info)** Xem thông tin như ngày đáo hạn, mã tài sản cơ sở của một hợp đồng cụ thể. ```python futures_info = ref.futures("VN30F2503").info() ``` --- ## 11. Chứng quyền (warrant) **Nguồn:** KBS, VCI **Nhóm lệnh:** `derivatives.warrant` **Danh sách hàm** | Hàm | Tham số | Mô tả | | -------- | ------- | -------------------------------------------------- | | `list()` | - | Danh sách các chứng quyền | | `info()` | - | Thông tin chi tiết (yêu cầu truyền mã chứng quyền) | **📝 Hướng Dẫn Sử Dụng** **1. Danh sách chứng quyền (list)** Lấy danh sách toàn bộ các chứng quyền có bảo đảm trên thị trường. ```python from vnstock_data import Reference ref = Reference() warrant_list = ref.warrant().list() ``` **2. Thông tin chi tiết (info)** Xem tổ chức phát hành, tỷ lệ chuyển đổi, ngày đáo hạn và giá thực hiện. ```python warrant_info = ref.warrant("CACB2511").info() ``` --- ## 💡 Mẹo sử dụng Thông tin tham chiếu ít khi thay đổi trong phiên, do đó bạn nên lấy một lần và lưu lại vào biến để dùng nhiều lần thay vì liên tục gọi lại. ```python ref = Reference() all_stocks = ref.equity.list() # Truy vấn một lần và lưu lại for symbol in all_stocks['symbol'].tolist(): # Thực hiện các bước phân tích... pass ``` --- ## Document: Tính năng nâng cao Hướng dẫn này dành riêng cho việc sử dụng **Adapter API** hoặc gọi trực tiếp vào từng module gốc trong `vnstock_data`. Nếu bạn là người mới sử dụng hoặc muốn tìm kiếm sự ổn định ưu tiên, hãy sử dụng **Unified UI**. ## Danh sách các API tính năng nâng cao Dưới đây là các tài liệu chi tiết cho việc sử dụng API nâng cao: - [Thông tin niêm yết (Listing)](/docs/vnstock-data/trang-thai-niem-yet) - [Thông tin công ty (Company)](/docs/vnstock-data/thong-tin-cong-ty) - [Báo cáo tài chính (Finance)](/docs/vnstock-data/bao-cao-tai-chinh) - [Dữ liệu giao dịch (Trading & Quote)](/docs/vnstock-data/du-lieu-giao-dich) - [Thống kê thị trường (Market)](/docs/vnstock-data/thong-ke-thi-truong) - [Định giá thị trường (Insights)](/docs/vnstock-data/dinh-gia-thi-truong) - [Kinh tế vĩ mô (Macro)](/docs/vnstock-data/kinh-te-vi-mo) - [Thị trường hàng hoá (Commodity)](/docs/vnstock-data/thi-truong-hang-hoa) - [Dữ liệu quỹ mở (Fund)](/docs/vnstock-data/du-lieu-quy-mo) ### Điểm Nổi Bật & Trường Hợp Sử Dụng - **Ưu điểm**: Cho phép kiểm soát hoàn toàn truy vấn, tự trích xuất các thông tin nguyên bản hoặc dữ liệu ngách mà Unified UI có thể đã ẩn đi để chuẩn hóa. Giúp khai thác trọn vẹn toàn bộ khả năng của `vnstock_data`. - **Trường hợp sử dụng**: Phù hợp cho lập trình viên có kinh nghiệm, xây dựng pipeline tùy chỉnh, hoặc cần dữ liệu thô (raw data) đặc thù. --- ## Document: Giới Thiệu

Dành cho thành viên Sponsor

Các thư viện này được thiết kế dành riêng cho thành viên tài trợ Vnstock, cung cấp công cụ mạnh mẽ để tự động hóa quy trình thu thập, phân tích và xử lý dữ liệu thị trường chứng khoán Việt Nam. Tất cả thư viện được phát triển, bảo trì và cập nhật liên tục với tài liệu hướng dẫn đầy đủ.

## Tổng quan hệ sinh thái Bộ thư viện Vnstock Sponsor bao gồm 4 module chính, mỗi module giải quyết một nhu cầu cụ thể trong quy trình phân tích đầu tư.

Vnstock Data

Công cụ truy xuất dữ liệu tự động

Công cụ chạy trên máy của bạn, gửi truy vấn thẳng tới nguồn và chuẩn hoá dữ liệu ngay tại đó. Tốc độ tải nhanh 5X-8X với dữ liệu intraday, khối ngoại, BCTC và vĩ mô.

Yêu cầu: Bronze+ Tài liệu →

Vnstock TA

Phân tích kỹ thuật chuyên nghiệp

Giao diện đơn giản cho phân tích kỹ thuật với 60 chỉ báo kỹ thuật phổ biến tương thích với chuẩn từ TradingView. Hỗ trợ tự động vẽ biểu đồ, tích hợp dữ liệu Vnstock liền mạch.

Yêu cầu: Silver+ Tài liệu →

Vnstock News

Thu thập tin tức đa nguồn

Thu thập tin tức từ 10+ trang tin tài chính hàng đầu VN. Hỗ trợ RSS, Sitemap, trích xuất Markdown và phân tích xu hướng tích hợp sẵn cho nghiên cứu chuyên sâu.

Yêu cầu: Silver+
Tài liệu →

Vnstock Pipeline

Data pipeline tự động hiện đại

Tự động hóa toàn bộ quy trình kết nối dữ liệu với tốc độ nhanh 10X nhờ xử lý song song. Hỗ trợ xuất đa định dạng (CSV, Parquet, DuckDB) và kiến trúc linh hoạt.

Yêu cầu: Golden+ Tài liệu →
--- ## Lựa chọn gói tài trợ phù hợp Xem chi tiết các gói tài trợ và so sánh quyền lợi để chọn gói phù hợp với nhu cầu của bạn:
So sánh gói tài trợ Cài đặt & sử dụng
--- ## Lưu ý quan trọng

Bản quyền & Miễn trừ trách nhiệm

Dữ liệu bạn truy cập qua thư viện thuộc quyền của nguồn gốc. Vnstock không vận hành kho dữ liệu thị trường để bán lại; dữ liệu nghiệp vụ nằm trên hạ tầng do bạn cấu hình, còn dịch vụ tài khoản, giấy phép và hạn mức xử lý dữ liệu theo Chính sách quyền riêng tư.

Dự án Vnstock được cung cấp chỉ nhằm mục đích nghiên cứu, giáo dục và sử dụng cá nhân. Vnstock và người dùng chịu trách nhiệm trong phạm vi vai trò của mình: bạn chịu trách nhiệm về credential, mục đích sử dụng và việc phân phối kết quả; Vnstock chịu trách nhiệm về mô tả trung thực và thiết kế phần mềm. Trong phạm vi pháp luật cho phép, Vnstock và tác giả không chịu trách nhiệm đối với thiệt hại hay tổn thất phát sinh từ việc sử dụng thư viện. Vnstock không cung cấp tư vấn đầu tư hoặc tín hiệu giao dịch.

--- ## Document: Lịch sử phiên bản ## 06-09-2026 ### vnstock_data > Phát hành phiên bản v3.2.9 khắc phục các sai lệch của dữ liệu khớp lệnh trong phiên (`trades`/`intraday`), đặc biệt với nhóm phái sinh. - **Khối lượng khớp lệnh trở về đúng thực tế:** Khắc phục tình trạng tổng khối lượng bị gấp đôi so với số liệu sở công bố. - **Nhãn ATO/ATC chính xác hơn:** Nhận diện đúng phiên ATO 08:45–09:00 của hợp đồng tương lai, đồng thời không còn gán nhầm nhãn cho các lệnh khớp liên tục. Bổ sung nhãn `PLO` cho mã sàn HNX. - **Sửa lỗi giá và thời gian ở nguồn MAS:** Khắc phục tình trạng chỉ trả về vài chục dòng, sai đơn vị giá và mốc thời gian nhảy về năm 1970. - **Mặc định lấy trọn phiên cho phái sinh:** Nâng giới hạn mặc định lên 100.000 bản ghi để phủ hết phiên, thay vì 1.000 bản ghi chỉ đủ chạm cụm ATC cuối phiên. Thư viện cũng tự cảnh báo khi dữ liệu trả về chưa phủ hết phiên. - **Thêm nguồn khớp lệnh VND:** Hỗ trợ cả cổ phiếu, chứng quyền và hợp đồng tương lai, cấu trúc dữ liệu đồng nhất với các nguồn còn lại. - **Gọi mã phái sinh kiểu cũ vẫn ra dữ liệu:** Các mã như `VN30F1M` được tự động chuyển sang mã KRX ở mọi lớp truy xuất. Bổ sung `Market().future(...)` bên cạnh `Market().futures(...)`. - **Lưu ý về nguồn VCI:** Nhà cung cấp đã áp giới hạn 100 bản ghi mỗi lượt gọi cho dữ liệu khớp lệnh. Nếu cần dữ liệu cả phiên, bạn nên dùng KBS, MAS hoặc VND. - **Khôi phục cây API `show_api()`:** Cây hiển thị đầy đủ mọi nhóm tài sản kèm nguồn dữ liệu và mô tả chức năng của từng hàm.
Phiên bản này đổi nguồn mặc định của dữ liệu khớp lệnh cổ phiếu và làm số liệu khối lượng khác đi so với bản cũ. Xem hướng dẫn nâng cấp v3.2.9 để biết cần chỉnh gì.
## 16-08-2026 ### vnstock_data > Phát hành phiên bản v3.2.8 mang đến nâng cấp toàn diện cho hệ thống dữ liệu Báo cáo tài chính, chuẩn hoá hoàn toàn theo chuẩn mực kế toán VAS. - **Đồng nhất API Báo cáo tài chính (Finance):** Tất cả các nguồn cấp dữ liệu (VCI, MAS, KBS) giờ đây đã được đồng nhất về cùng một định dạng chuẩn **Tidy Data (Long-form)**, giúp loại bỏ hoàn toàn sự thiếu nhất quán giữa các nguồn. - **Chuẩn hoá mã định danh (Semantic ID):** Áp dụng bộ Taxonomy ID chuẩn mực (ví dụ: `BS_CASH_AND_PRECIOUS_METALS`) làm khoá chính, giúp mã nguồn phân tích định lượng không bị gãy sụp đổ khi tên hiển thị của chỉ tiêu thay đổi. - **Hệ thống tham số mới mạnh mẽ:** - Thay thế tham số `dropna` bằng `drop_empty`. - Hỗ trợ tuỳ chỉnh linh hoạt cấu trúc dữ liệu trả về thông qua tham số `format` (`'long'`, `'wide'`, `'time_series'`). - Thêm tham số `com_type` giúp hệ thống bóc tách chính xác báo cáo dựa trên loại hình công ty (`Regular`, `Bank`, `Securities`, `Insurance`) khi cơ chế nhận diện tự động không thành công. - **Nâng cấp tài liệu & Hướng dẫn (Migration):** Cung cấp bảng tham chiếu chi tiết và [tài liệu hướng dẫn nâng cấp](/docs/vnstock-data/nang-cap-phien-ban/v3.2.8) mã nguồn dành riêng cho các thay đổi của phiên bản cập nhật này. ## 03-08-2026 ### vnstock_data > Phát hành phiên bản v3.2.7 tập trung vào nâng cấp trải nghiệm truy xuất dữ liệu & vá lỗi - **Khắc phục lỗi tham số kỳ báo cáo cho Finance module - nguồn VCI**: Xử lý triệt để tình trạng dữ liệu báo cáo tài chính bị trộn lẫn. Hiện tại, khi gọi `Finance(..., period='year').balance_sheet()`, kết quả trả về sẽ hoàn toàn chuẩn xác theo cột năm (tránh lẫn với dữ liệu quý), giúp việc phân tích chuỗi thời gian liền mạch. - **Tự động lấy đủ dữ liệu giao dịch từ Trading module - nguồn CafeF**: Xóa bỏ giới hạn cứng 20 bản ghi mỗi trang của nguồn CafeF. Các hàm dữ liệu (lịch sử giá, giao dịch khối ngoại, tự doanh, thống kê đặt lệnh...) nay tự động lật trang ngầm để trả về đủ giới hạn `limit` bạn yêu cầu. - **Khắc phục lỗi cắt xén dữ liệu từ Trading module - nguồn VCI**: Xử lý tình trạng dữ liệu bị cắt cụt âm thầm (chỉ trả về ~100 dòng) khi gọi chuỗi thời gian dài. Giờ đây, chỉ cần truyền khoảng ngày `start` và `end`, thư viện sẽ tự động tính toán và phân trang ngầm để lấy trọn vẹn toàn bộ lịch sử giao dịch. ## 01-08-2026 ### vnstock_pipeline > Phát hành `vnstock_pipeline` phiên bản 2.3.2 - Hỗ trợ trích xuất và cập nhật dữ liệu tự động sang phần mềm AmiBroker trên máy tính Windows. **✨ Tính Năng Nổi Bật** - **Cập Nhật Dữ Liệu AmiBroker Trực Tiếp**: Tự động xuất và nạp dữ liệu giá (đã điều chỉnh và chưa điều chỉnh), chỉ số thị trường, cùng dữ liệu giao dịch Khối ngoại & Tự doanh thẳng vào phần mềm AmiBroker đang mở trên máy tính. - **Chế Độ Cập Nhật Liên Tục (Chạy Ngầm)**: Tự động theo dõi và nạp thêm dữ liệu mới nhất vào AmiBroker theo khoảng thời gian bạn cài đặt mà không cần thao tác thủ công. - **Thêm Các Câu Lệnh Tiện Ích**: Cung cấp các câu lệnh dễ dùng để thiết lập xuất dữ liệu và chạy tự động các nhóm tác vụ. **🔧 Cải Tiến Hệ Thống** - **Quản Lý Cài Đặt Tập Trung**: Sử dụng một file cấu hình duy nhất (`pipeline.toml`) để thiết lập nơi lưu trữ, định dạng file mặc định (ví dụ: `.csv`, `.parquet`) một cách dễ dàng. - **Hoạt Động Ổn Định Hơn**: Cải thiện tốc độ và tính an toàn khi chạy tải dữ liệu số lượng lớn, hệ thống tự động tạo sẵn các thư mục cần thiết và xử lý mượt mà hơn khi phát sinh lỗi kết nối. ## 22-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.6 giúp sửa lỗi và tối ưu hoá mã nguồn. - **Sửa lỗi trích xuất thuyết minh báo cáo tài chính (Nguồn VCI):** Cập nhật lại cấu trúc hàm trích xuất thuyết minh báo cáo tài chính để hàm hoạt động ổn định và trả về dữ liệu đầy đủ thay vì kết quả rỗng. ## 18-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.5 mang đến cho bạn nhiều lựa chọn dữ liệu hơn và nâng cao độ ổn định của hệ thống. - **Thêm nguồn dữ liệu giao dịch mới:** Tích hợp thêm nguồn `asean` và `mbk` giúp bạn có thêm các lựa chọn đáng tin cậy khi phân tích dữ liệu lịch sử giao dịch. - **Mở rộng tra cứu thông tin doanh nghiệp:** Bổ sung tính năng lấy dữ liệu thông tin niêm yết từ nguồn CafeF giúp bạn dễ dàng theo dõi các thông tin quan trọng của doanh nghiệp. - **Trải nghiệm mượt mà hơn với nguồn ASEAN:** Khắc phục hoàn toàn tình trạng lỗi kết nối khi lấy dữ liệu các nhóm hàm Insight, Sector và Trading từ nguồn ASEAN. ## 16-07-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.2.4 giúp quá trình truy xuất dữ liệu báo cáo tài chính từ nguồn KBS ổn định. - **Dữ liệu tài chính ổn định hơn:** Hệ thống giờ đây có khả năng tự động xử lý và phục hồi (fallback) khi nhà cung cấp dữ liệu KBS thay đổi định dạng, giúp bạn luôn lấy được đầy đủ báo cáo tài chính mà không lo bị ngắt quãng. ## 28-06-2026 ### vnstock_news > Phát hành `vnstock_data` phiên bản 3.2.3 hoàn thiện cấu trúc tin tức của công ty niêm yết và chuẩn hoá mô hình dữ liệu. - **Chuẩn hoá mô hình dữ liệu (Unified Schema) cho Tin tức doanh nghiệp:** Giao diện `Reference().company('MÃ_CK').news()` được chuẩn hoá hoàn toàn trên 3 nguồn `vci`, `kbs`, và `cafef` với chung 10 cột dữ liệu thống nhất (`id`, `symbol`, `title`, `summary`, `content`, `publish_time`, `source`, `url`, `category`, `image_url`). - **Nâng cấp tính năng lấy tin tức chi tiết:** Bổ sung tham số `mode='detail'` cho phép đọc full nội dung bài viết và bóc tách các link đính kèm trực tiếp từ `vci` và `cafef`. - **Hỗ trợ tuỳ chỉnh tham số linh hoạt:** Chuẩn hoá các tham số bộ lọc thời gian (`start`, `end`, `length`, `limit`) và nâng cấp khả năng truyền linh hoạt `**kwargs` xuống hàm của từng nguồn. ## 20-06-2026 ### vnstock_pipeline > Phát hành `vnstock_pipeline` phiên bản 2.3.1 cấu trúc lại toàn bộ kiến trúc lưu trữ dữ liệu, giới thiệu file cấu hình tập trung `pipeline.toml` và cải tiến mạnh mẽ CLI hỗ trợ quản trị cơ sở dữ liệu chứng khoán hiệu quả. **⚠️ Thay Đổi Mang Tính Phá Vỡ** - **Gỡ bỏ `DuckDBProcessor` & `FirebaseProcessor`**: Cấu trúc mới tập trung gom dữ liệu thô lưu trữ định dạng Parquet/CSV hiệu suất cao. Người dùng tự quản lý Data Warehouse (DuckDB/Supabase) theo nhu cầu. Thay đổi này ít tác động tới người dùng vì cách dùng này không được giới thiệu chính thức. - **Tự động hoá tham số `base_path`**: Không cần truyền `base_path` khi khởi tạo `Exporter` trong các pipeline tùy biến; đường dẫn sẽ tự động lấy từ cấu hình tập trung. - **Công cụ di chuyển dữ liệu cũ**: Bổ sung lệnh CLI `python -m vnstock_pipeline.cli storage migrate-legacy` hỗ trợ người dùng chuyển đổi kho dữ liệu cũ sang cấu trúc phân lớp tập trung mới một cách an toàn. **✨ Tính Năng Nổi Bật** - **Kiến Trúc Lưu Trữ Tập Trung (`pipeline.toml`)**: Quản lý thiết lập đường dẫn (`base_path`), chế độ lưu mặc định (`parquet`/`csv`/`excel`) và cơ chế ghi đè định dạng (`format_overrides`) cho từng nhóm dữ liệu ngay tại `~/.vnstock/config/pipeline.toml`. - **Linh Hoạt 2 Chế Độ Phân Cấp Thư Mục**: - **Flat Layout (Mặc định)**: Thân thiện cho người dùng cá nhân (ví dụ: `~/stock_db/ohlcv/ACB.parquet`). - **Nested Layout**: Phân cấp chuẩn mực (`[layer]/[domain]/...`), tối ưu cho người dùng chuyên sâu và AI Agent. - **Bảo Vệ An Toàn Cấu Trúc Dữ Liệu**: Tự động so sánh dữ liệu mới tải với cấu trúc chuẩn (`Baseline Schema`). Cách ly an toàn các file lỗi hoặc thay đổi cấu trúc nghiêm trọng vào `.tmp/.quarantine/` nhằm bảo vệ CSDL chính. - **Xử Lý Lỗi & Khôi Phục Thông Minh**: Tự động sinh file `error_log.csv` ghi nhận mã lỗi do rớt mạng hoặc thiếu dữ liệu. Cung cấp cờ `--retry-errors` để tải bù nhanh những mã thất bại thay vì chạy lại từ đầu. - **Công Cụ Quản Trị Bằng Dòng Lệnh (CLI)**: Cung cấp hàng loạt lệnh mới tiện dụng như kiểm toán CSDL (`storage audit`), đổi định dạng (`set-format`), dọn rác định kỳ (`cleanup`), trích xuất cấu trúc nhanh (`storage preview`). - **Khởi Tạo Rổ Thanh Khoản (Universe)**: Lệnh `universe build-liquidity` giúp quét và xếp hạng tính thanh khoản các cổ phiếu qua đa khung thời gian để sinh ra tệp theo dõi lưu mặc định vào cấu hình `liquidity_auto`. - **Template Pipeline Tích Hợp Sẵn**: Tự động hoá các tác vụ phức tạp như gom 5 bảng báo cáo tài chính vào Multi-sheet Excel, thu thập tin tức chống trùng lặp qua bộ đệm Streaming, và cập nhật sự kiện doanh nghiệp liền mạch. - **Trích Xuất Chuẩn Amibroker**: Tích hợp module quét Local Database với DuckDB, xuất cực nhanh toàn bộ dữ liệu ra định dạng `.csv` chuẩn tương thích Amibroker bằng một dòng lệnh. ## 24-05-2026 ### vnstock_data > Phát hành vnstock_data phiên bản 3.2.0 và cập nhật đồng loạt các thư viện trong gói sponsor với những tinh chỉnh nhỏ giúp tăng tính ổn định của hệ thống. - **Tích hợp Toàn diện Dữ liệu ASEAN (Unified UI)**: - Tích hợp luồng dữ liệu từ trung tâm phân tích của Asean Securities, mở rộng mạnh mẽ năng lực phân tích và giúp người dùng tiếp cận dữ liệu với góc nhìn đa chiều: - **Insights**: Cung cấp bộ công cụ chuyên sâu đo lường tâm lý thị trường (`sentiment`: breadth, heatmap, contribution), theo vết dòng tiền (`flow`: foreign, proprietary, active). Đào sâu phân tích cấp độ Ngành (`sector`) và Cổ phiếu (`equity`) thông qua biểu đồ Relative Rotation Graph (`rrg`), định giá (`valuation`), so sánh ngang hàng (`peer_compare`), và phân tích dòng lệnh (`order_flow`). - **Vĩ mô & Hàng hoá (Macro)**: Thay thế lõi truy xuất dữ liệu Vĩ mô (Kinh tế, Tiền tệ) sang nguồn ASEAN với độ trễ thấp hơn. Tăng cường khả năng tiếp cận tức thời các chỉ số toàn cầu như Lợi suất trái phiếu (`bond_yield`), Lãi suất Fed (`fed_rate`), và các rổ hàng hoá phái sinh chuẩn quốc tế trực tiếp qua `Macro().global` và `Macro().commodity()`. - **Tương thích & Ổn định**: - Khi người dùng truy xuất các hàng hoá đặc thù của Việt Nam (VD: Vàng SJC, Thép D10, Lợn Hơi) qua tham số `market="VN"`, hệ thống tự động fallback mượt mà về nguồn SPL cũ, đảm bảo không bị gián đoạn trải nghiệm phân tích số liệu cục bộ. - **Trải nghiệm Phát triển**: Toàn bộ các endpoints mới được dán nhãn `[Experimental]` khi gọi lệnh `show_api()`, giúp các nhà phân tích phân biệt và nắm bắt nhanh chóng kho công cụ mới này. **Chi tiết cấu trúc API Tree (Các hàm mới & nâng cấp):** ```bash ├── Insights │ ├── equity() │ │ ├── order_flow() -> DataFrame # Phân bổ dòng tiền chủ động │ │ ├── order_flow_history() -> DataFrame # Lịch sử giao dịch & dòng lệnh │ │ ├── peer_compare() -> DataFrame # So sánh với các mã cùng ngành │ │ └── rrg() -> DataFrame # Sức mạnh tương đối (RRG) │ ├── flow │ │ ├── active() -> DataFrame # Dòng tiền chủ động mua/bán │ │ ├── foreign() -> DataFrame # Giao dịch khối ngoại (FII) │ │ └── proprietary() -> DataFrame # Giao dịch tự doanh │ ├── sector() │ │ ├── flow() -> DataFrame # Dòng tiền tổng hợp toàn ngành │ │ ├── flow_intraday() -> DataFrame # Dòng tiền ngành trong ngày │ │ ├── index_intraday() -> DataFrame # Chỉ số ngành trong ngày │ │ ├── members() -> DataFrame # Chỉ số tài chính của các mã trong ngành │ │ ├── rrg() -> DataFrame # Sức mạnh tương đối ngành (RRG) │ │ └── valuation() -> DataFrame # Tỷ số định giá ngành │ └── sentiment │ ├── breadth() -> DataFrame # Độ rộng thị trường │ ├── contribution() -> DataFrame # Top đóng góp điểm số │ └── heatmap() -> DataFrame # Bản đồ nhiệt toàn thị trường └── Macro ├── commodity() │ ├── coke() -> DataFrame # Giá Hợp đồng tương lai Than Cốc │ ├── corn() -> DataFrame # Giá Ngô Mỹ │ ├── gas() -> DataFrame # Khí tự nhiên / Xăng dầu VN │ ├── gold() -> DataFrame # Vàng thế giới / Vàng SJC │ ├── iron_ore() -> DataFrame # Quặng sắt Trung Quốc │ ├── listing() -> DataFrame # Danh sách hàng hoá hỗ trợ │ ├── oil_crude() -> DataFrame # Dầu thô WTI │ ├── pork() -> DataFrame # Giá Lợn Hơi VN / TQ │ ├── related_industry() -> DataFrame # Nhóm ngành liên quan Hàng hoá │ ├── related_stock() -> DataFrame # Nhóm cổ phiếu liên quan Hàng hoá │ ├── soybean() -> DataFrame # Giá Đậu nành Mỹ │ ├── steel() -> DataFrame # Thép HRC thế giới / Thép D10 VN │ └── sugar() -> DataFrame # Giá Đường London ├── currency() │ ├── deposit_rate() -> DataFrame # Lãi suất huy động │ ├── exchange_rate() -> DataFrame # Tỷ giá trung tâm │ ├── interbank_rate() -> DataFrame # Lãi suất liên ngân hàng │ ├── omo() -> DataFrame # Nghiệp vụ thị trường mở (OMO) │ └── policy_rate() -> DataFrame # Lãi suất điều hành ├── economy() │ ├── cpi() -> DataFrame # Chỉ số giá tiêu dùng (CPI) │ ├── credit() -> DataFrame # Tăng trưởng tín dụng │ ├── fdi() -> DataFrame # Vốn đầu tư trực tiếp nước ngoài │ ├── gdp() -> DataFrame # Tổng sản phẩm quốc nội (GDP) │ ├── import_export() -> DataFrame # Xuất nhập khẩu │ ├── money_supply() -> DataFrame # Cung tiền M2 │ ├── state_budget() -> DataFrame # Thu ngân sách nhà nước │ └── total_investment() -> DataFrame # Tổng vốn đầu tư └── global ├── bond_yield() -> DataFrame # Lợi suất TPCP (VN / Mỹ) ├── fed_rate() -> DataFrame # Lãi suất Fed └── index() -> DataFrame # Các chỉ số thế giới (DXY, SPX...) ``` ## 19-05-2026 ### vnstock_pipeline > Cập nhật và sửa lỗi cho vnstock_pipeline phiên bản 2.2.3 - **Sửa `ceiling_price`**: Khắc phục lỗi cột giá trần (`ceiling_price`) bị gắn sai giá trị các cờ màu sắc (như `e`, `d`) do nhầm lẫn ánh xạ với trường `ca` (color_average) từ WebSocket. - **Thêm thông tin giá**: Tách và trích xuất chính xác giá trị số cho giá trần (`ceiling_actual`), giá sàn (`floor_price`), và giá tham chiếu (`reference_price`) cho cả cổ phiếu cơ sở và phái sinh. - **Sửa `market_id` cho Phái sinh**: Tự động chuẩn hóa và gán cứng sàn giao dịch thành `HNX` cho tất cả dữ liệu hợp đồng tương lai phái sinh (`stockps`). ## 18-05-2026 ### vnstock_pipeline > Phiên bản vnstock_pipeline 2.2.2 mang đến nhiều nâng cấp quan trọng giúp bạn xây dựng hệ thống quản lý tải dữ liệu và kết nối dữ liệu trong phiên qua WebSocket hiệu quả và đơn giản hơn bao giờ hết. Các cập nhật mới nhất giúp cải thiện độ tương thích của các thư viện trong hệ sinh thái Vnstock với chuẩn Unified UI mới nhất. ### Cảnh báo giao dịch & Dữ liệu thời gian thực Hệ thống luồng dữ liệu được tối ưu hoá với `redis`, cung cấp sẵn các kịch bản thường dùng trong giao dịch và theo dõi tín hiệu, giúp bạn: - **Nhận cảnh báo tức thì:** Tự động phát hiện các điều kiện chỉ báo (giao cắt MACD, quá mua/quá bán RSI, đột biến dòng tiền...) và gửi cảnh báo về kênh Discord của bạn qua Webhook. - **Hoạt động bền bỉ 24/7:** Thuật toán kết nối mới giúp hệ thống ổn định. Tự động phục hồi ngay lập tức nếu rớt mạng, đảm bảo bạn không bỏ lỡ bất kỳ biến động nào trong giờ giao dịch. - **Fan-out nội bộ:** Cung cấp sẵn mẫu phát lại luồng dữ liệu đã nhận cho các ứng dụng nội bộ của chính bạn trong cùng hệ thống, trong phạm vi tài khoản và quyền của bạn với nguồn; không chia sẻ credential, không cung cấp luồng dữ liệu cho bên thứ ba. ### Phân tích dữ liệu siêu tốc không cần mở trình soạn thảo Công cụ dòng lệnh tích hợp mới (`vnstock_pipeline`) giúp bạn tiết kiệm tối đa thời gian: - Xem nhanh tổng quan, dung lượng và cấu trúc của bất kỳ tệp dữ liệu chứng khoán nào chỉ với các lệnh CLI đơn giản mà AI Agent có thể sử dụng như một công cụ. - Lọc, tìm kiếm (ví dụ: lọc các mã có giá > 50) và xem thống kê dữ liệu ngay trên cửa sổ lệnh mà không cần phải khởi động các phần mềm phân tích nặng nề. ### Quản lý chất lượng & độ toàn vẹn dữ liệu - **Kiểm định chất lượng tự động:** Hệ thống tự động quét, phát hiện và cảnh báo mọi khoảng trống hay lỗi bất thường trước khi lưu trữ. - **Trực quan & Dễ tích hợp:** Toàn bộ tên mã chứng khoán và định dạng báo cáo tài chính đều được chuẩn hóa thống nhất, cực kỳ dễ đọc và dễ dàng đưa vào phần mềm riêng của bạn. ## 16-05-2026 ### vnstock_ta ### Cập nhật Vnstock Data 3.1.8 - **Chuẩn hoá Báo cáo Tài chính (Unified UI)**: - Đồng bộ Schema báo cáo tài chính cho các nguồn dữ liệu (MAS, VCI), xử lý triệt để lỗi lệch cột và lẫn lộn ngôn ngữ (mixed labels) bằng hệ thống Mapping chỉ số La Mã (Roman numeral). - Bổ sung thông tin kỳ báo cáo (`report_period`) cho nguồn VCI, đảm bảo dữ liệu hiển thị đầy đủ và tương thích với giao diện Unified UI. - **Thị trường Trái phiếu (Bond Market)**: - Tích hợp lớp domain `bond` vào hệ thống Unified UI, mở rộng khả năng tra cứu dữ liệu thị trường trái phiếu. ### Cập nhật Vnstock TA 1.0.3 > Phát hành bản cập nhật Vnstock TA 1.0.3 tập trung mang lại trải nghiệm phân tích mượt mà, trực quan và tối ưu nhất cho người dùng hệ sinh thái Vnstock. **✨ Bạn có thể làm gì với bản cập nhật này?** - **Sử dụng kho chỉ báo đa dạng**: Bổ sung toàn diện nhóm chỉ báo Thống kê (Statistics), chỉ báo sức mạnh xu hướng (Aroon) và mở rộng đáng kể các nhóm chỉ báo Xu hướng (Trend), Biến động (Volatility). - **Vẽ biểu đồ chuyên nghiệp với phong cách hiện đại**: Hệ thống Theme mới giúp biểu đồ có giao diện hiện đại và nhất quán. Các chỉ báo phức tạp nhiều đường (như StochRSI, ADX, PVO...) giờ đây đã có chú thích (legend) và nhãn dữ liệu rõ ràng, dễ đọc. **⚡ Tối ưu trải nghiệm sử dụng** - **Cài đặt nhanh, siêu nhẹ**: Thư viện đã được tối ưu và gỡ bỏ các gói phụ thuộc nặng như `pyecharts`, `panel` hướng tới loại bỏ tính năng vẽ đồ thị tương tác sau 31/8/2026. Giờ đây cài đặt vnstock_ta sẽ nhanh chóng và tốn cực ít tài nguyên. - **Dữ liệu ổn định và nhanh chóng**: Chuyển đổi toàn bộ việc lấy dữ liệu sang giao diện Unified UI của Vnstock, giúp tốc độ tính toán nhanh và độ tin cậy cao hơn. ## 12-05-2026 ### vnstock_data > Cập nhật vnstock installer GUI v3.1.2 & CLI v3.0.2 - **Nhận diện mẫu Venv**: Đồng bộ cơ chế nhận diện các tên thư mục môi trường ảo phổ biến (`venv`, `.venv`, `env`). - **Cảnh báo tương tác**: Bổ sung hộp thoại xác nhận khi người dùng cung cấp đường dẫn không theo quy chuẩn môi trường ảo. - **Cơ chế an toàn**: Kiểm tra sự tồn tại của tệp `pyvenv.cfg` và các mẫu định danh venv trước khi thực hiện thao tác sửa đổi thư mục môi trường ảo bị lỗi. - **Gợi ý đường dẫn thông minh**: Tự động gợi ý thêm hậu tố `.venv` nếu người dùng chọn thư mục dự án làm nơi cài đặt môi trường ảo. ## 05-05-2026 ### vnstock_data (v3.1.7) - Bổ sung khả năng truy xuất tài liệu và báo cáo tài chính cho từng mã chứng khoán. Người dùng có thể truy xuất hàng loạt liên kết đến file báo cáo tài chính định dạng PDF thông qua lập trình đơn giản. ```python from vnstock_data import Fundamental fun = Fundamental() fun.equity('FPT').filing(doc_type='annual_report') ``` - Tinh chỉnh chức năng hàm tiện ích `show_api` để hiển thị thông tin cây API trọn vẹn hơn theo từng cấp. - Ví dụ để xem tất cả cấu trúc bên dưới nhóm hàm `Reference` có thể gọi `show_api('Reference')` - Để xem chi tiết sâu hơn 1 cấp nữa, có thể sử dụng cú pháp chaining dạng `show_api('Reference.equity')` ## 02-05-2026 ### vnstock_data (v3.1.6) - Sửa lỗi xảy ra với `vnstock_data/explorer/vci/listing.py", line 35, in all_symbols` xung đột thư viện sau khi code bị làm rối. ## 01-05-2026 ### vnstock_data (v3.1.5) - Cập nhật khả năng tuỳ chỉnh điều kiện lọc cho hàm lọc dữ liệu cổ phiếu từ VCI trong giao diện hợp nhất tại lớp `Insights` - Sửa lỗi `ProxyConfig.update_forward_refs()` trong `vnstock_data/core/utils/client.py` khi gọi lệnh mẫu `Company(symbol='VIC', source='KBS').overview()` ## 29-04-2026 ### vnstock_data (v3.1.4) - Cập nhật CLI Installer phiên bản 3.1.4 - Bổ sung danh sách mapping chính xác các chỉ số index từ HNX, UPCOM để truy xuất dữ liệu lịch sử ohlcv từ VCI ## 23-04-2026 ### vnstock_data (v3.1.3) - **Chuẩn hoá & Mở rộng Báo cáo Tài chính (Fundamental & Financial Health)**: - Mở rộng Schema tài chính với các trường dữ liệu chi tiết từ nguồn MAS. - Định chuẩn hóa bộ tiêu chí đánh giá cho 4 nhóm ngành: Ngân hàng, Chứng khoán, Bảo hiểm và Đa ngành theo tiêu chuẩn phân tích chung tương tự giao diện tại TCBS. - **Hạ tầng & Tối ưu hóa (Infrastructure & Refactoring)**: - Nâng cấp các module tiện ích lõi (`client.py`, `user_agent.py`) để cải thiện hiệu năng kết nối và quản lý User-Agent. - **Sửa lỗi & Ổn định hệ thống (Bug Fixes)**: - Khắc phục triệt để lỗi sai tỷ lệ giá (price scaling) cho các tài sản Chỉ số (Index) và Phái sinh (Derivative) tại module `quote` (nguồn KBS). - Sửa lỗi truy xuất dữ liệu danh sách niêm yết (listing) và báo giá (quote) cho nguồn Dukascopy. - Xử lý các lỗi nhỏ trong UI Registry và logic phân loại ngành giúp hệ thống hoạt động chính xác hơn. - **Chuyển đổi giao thức dữ liệu VCI (API Migration)**: - Chuyển đổi toàn bộ quy trình lấy danh sách (Listing) và mã ngành (ICB) từ nguồn VCI từ GraphQL sang REST API để tăng độ ổn định và tốc độ phản hồi. ## 12-04-2026 ### vnstock_data > Phần mềm `vnstock_data` cập nhật phiên bản 3.1.0: Hoàn thiện bộ dữ liệu hợp nhất (Unified UI) và bổ sung bổ sung dữ liệu thị trường Quốc tế. - **Thị trường Quốc tế & Crypto**: - Tích hợp dữ liệu tiền mã hoá (Cryptocurrency) thông qua API Binance Spot (hỗ trợ dữ liệu `ohlcv`, `order_book`, `intraday`, `quote`). Khung kiến trúc được trang bị thuật toán chờ và gửi lại để duy trì kết nối khi gặp giới hạn truy vấn API. - Xây dựng kiến trúc Explorer cung cấp biểu đồ đa khung thời gian cho Ngoại hối (Forex), Hàng hoá (Commodity) và các chỉ số toàn cầu thông qua Dukascopy và ForexSB. Cung cấp bộ cấu hình Múi giờ gốc sang múi giờ Hệ thống (`Asia/Ho_Chi_Minh`). - **Thị trường Nội địa (Unified UI)**: - Nâng cấp API cho thị trường chỉ số (Index Market): Hệ thống hỗ trợ lấy bộ dữ liệu thống kê giao dịch lịch sử của tất cả các loại chỉ số thông qua phương thức `trade_history()`. Hỗ trợ tên chỉ số quy chuẩn để tra lệnh. - Bổ sung hàm tóm tắt bức tranh tài chính tổng hợp `financial_health` (tổ hợp 3 bảng báo cáo tài chính và các chỉ số tài chính). Chuẩn hoá chuyển ngữ thẻ Scorecard chuyên ngành: Ngân hàng, Chứng khoán, Bảo hiểm, hỗ trợ trích lọc linh hoạt. Quy chuẩn này lấy cảm hứng từ cấu trúc báo cáo của nền tảng TCBS, giúp duy trì sự nhất quán trong bộ tiêu chí cố định trong phân tích cơ bản cho doanh nghiệp, tránh phải xử lý bộ tiêu chí không thống nhất trong các báo cáo tài chính vốn có nhiều khác biệt giữa các nguồn khác nhau. Sử dụng bộ tiêu chí này giúp người dùng hạn chế phải thay đổi code khi nguồn dữ liệu gặp sự cố hoặc phiên bản phần mềm thay đổi ảnh hưởng tới bộ tiêu chí này. -Nguồn dữ liệu cung cấp dữ liệu tài chính cho các hàm tại Unified UI được chuyển đổi từ KBS sang MAS để tăng số kỳ báo cáo tài chính lên trên 10 năm, thay vì bị giới hạn 4 kỳ mặc định của API từ KBS. - Tối ưu tra cứu dữ liệu Vĩ mô (Macro) và Hàng hoá: Áp dụng kỹ thuật quét lùi tự động và đắp điền dữ liệu khuyết rỗng (Forward-fill) để xử lý hoàn thiện độ trễ công bố thông tin, giảm thiểu phát sinh lỗi. - Cải thiện khả năng chuẩn hoá symbol nhập nhập vào hàm của CafeF để nhận diện các chỉ số chính xác VNINDEX/HOSE, HNXINDEX/HNX, UPCOMINDEX/UPCOM và VN30. - Tái cấu trúc chuẩn thư viện: Áp dụng chuẩn hoá, bổ sung tham số định danh nhà cung cấp `source` theo yêu cầu từ phiên bản. - **Tài liệu Agent Guide**: - Cập nhật mô tả các hàm và nguồn dữ liệu bổ sung - Cung cấp schema dữ liệu chuẩn hoá giúp xác định mô hình dữ liệu và xây dựng sản phẩm tin cậy hơn, giảm thiểu việc phải chạy từng đoạn code để kiểm tra cấu trúc dữ liệu. - **Bổ sung bộ Notebook hoàn chỉnh**: - Bổ sung bộ Notebook hoàn chỉnh về các hàm tại Unified UI và theo kiểu gọi Adapter Pattern (thay đổi tham số source kiểu cũ) phản ánh đầy đủ trạng thái mới nhất của thư viện. ## 07-04-2026 ### vnstock_data > Phát hành `vnstock_data` phiên bản 3.0.1 sửa các lỗi quan trọng và tinh chỉnh trải nghiệm người dùng. - **Unified UI**: Bổ sung hàm `cash_flow` vào giao diện hợp nhất; cập nhật mô tả cho hàm `trade_history` (thống kê giao dịch, giá chứng khoán trước khi pha loãng). - **Nguồn KBS**: Sửa lỗi chia điểm index cho 1000 và lỗi 502 Bad Gateway do web phân định lại cấu trúc URL; tinh chỉnh chuẩn hoá tên chỉ tiêu tài chính và thông tin định danh User Agent. - **Nguồn MBK (Vĩ mô)**: Cải thiện thuật toán truy xuất dữ liệu theo tham số `length` và tự động *forward fill* để khắc phục lỗi trả về dữ liệu rỗng. - **Nguồn SPL (Hàng hoá)**: Sửa lỗi truy xuất dữ liệu null sinh ra do không khớp cấu hình múi giờ. - **Nguồn VCI**: Bổ sung cơ chế tương thích pandas cho hàm map và applymap để hoạt động tốt cho tất cả phiên bản từ 2.1.0 và trước đó. ## 03-04-2026 ### vnstock_news > **Phát hành vnstock_news 2.2.0: Công cụ truy xuất dữ liệu tin tức hiệu suất cao** > > Bản phát hành mới giải phóng bạn khỏi những lỗi xảy ra trong quá trình xử lý dữ liệu, mang tới sự ổn định khi trích xuất dữ liệu tin tức từ 21 trang tin nổi bật tại Việt Nam. ### ✨ Nâng cấp nổi bật - **Kiến trúc Crawler Hợp Nhất (Unified Crawler):** Khai thác song song và tự động dự phòng chéo (fallback) giữa luồng RSS và Sitemap, đảm bảo hệ thống bạn luôn có tin mới khi một trong hai luồng gặp sự cố. - **Trích xuất metadata linh hoạt:** Tăng cường khả năng bắt chính xác Selector qua các thuộc tính linh hoạt (`id`, `data-slot`, `rel`) thay vì phụ thuộc mỗi thẻ `class` theo CSS Selector truyền thống. Chủ động trích xuất thêm thẻ Tags, Lượt xem và Chuyên mục của bài. - **Làm sạch tự động & Xử lý thời gian:** - **Date Parser:** Tự động "thấu hiểu" và ép kiểu mọi định dạng thời gian lạ lẻ (như *15 phút trước*, *Thứ năm...*) về chuẩn ISO thống nhất cho Database. - **Spam/Media Link Filter:** Rà soát và loại bỏ link nhiễu phân trang, hình ảnh, URL rác đính kèm trong RSS. - Tự động bỏ qua lỗi chứng chỉ SSL để duy trì kết nối cho những tòa soạn chưa nâng cấp máy chủ hiện đại. ### 🐛 Vận hành trơn tru hơn - Sửa dứt điểm tình trạng trả về Data nhưng cột Nội dung trống rỗng (Missing Content 100%) gây ra bởi lỗi đọc JSON. - **Bổ sung đầu báo mới được hỗ trợ:** Bổ sung và tinh chỉnh cấu trúc CSS cho hàng loạt trang báo mới (Tiền Phong, Người Lao Động, Thanh Niên, Znews, Dân Trí, Đầu Tư, VnEconomy). - Bổ sung bộ kịch bản dùng thử "All-in-one" và tái cấu trúc tài liệu ví dụ, tự động dọn dẹp kết quả xuất file vào phân vùng tĩnh `/output/`.
Nhấp để xem danh sách 21 trang báo được hỗ trợ sẵn | STT | Tên Báo | Tên Config | Loại Hình | RSS | Sitemap | | --- | ------------------------- | ---------------------- | ------------ | --- | ------- | | 1 | **Nhân Dân** | nhandan | Cơ quan TW | ✅ | ✅ | | 2 | **Tiền Phong** | tienphong | Cơ quan TW | ✅ | ✅ | | 3 | **VietNamNet** | vietnamnet | Bộ Ngành | ✅ | ✅ | | 4 | **Dân Trí** | dantri | Bộ Ngành | ✅ | ✅ | | 5 | **VnExpress** | vnexpress | Bộ Ngành | ✅ | ✅ | | 6 | **Báo Đầu Tư** | baodautu | Bộ Ngành | ✅ | ✅ | | 7 | **Thời Báo Tài Chính** | thoibaotaichinhvietnam | Bộ Ngành | ✅ | ✅ | | 8 | **Thanh Niên** | thanhnien | Tổ chức TW | ✅ | ✅ | | 9 | **Tuổi Trẻ** | tuoitre | Địa phương | ✅ | ✅ | | 10 | **Người Lao Động** | nld | Địa phương | ✅ | ✅ | | 11 | **Pháp Luật TP.HCM** | plo | Địa phương | ✅ | ✅ | | 12 | **Kinh Tế Sài Gòn** | ktsg | Địa phương | ✅ | ✅ | | 13 | **VnEconomy** | vneconomy | Chuyên ngành | ✅ | ✅ | | 14 | **Diễn Đàn Doanh Nghiệp** | dddn | Chuyên ngành | ✅ | ✅ | | 15 | **PetroTimes** | petrotimes | Chuyên ngành | ✅ | ✅ | | 16 | **Znews (Tri thức)** | znews | Chuyên ngành | ✅ | ✅ | | 17 | **CafeF** | cafef | Trang tin | ✅ | ✅ | | 18 | **CafeBiz** | cafebiz | Trang tin | ✅ | ✅ | | 19 | **VietStock** | vietstock | Trang tin | ✅ | ✅ | | 20 | **24h** | 24h | Tổng hợp | ✅ | ✅ | | 21 | **Người Quan Sát** | nguoiquansat | Tổng hợp | ✅ | ✅ |
## 27-03-2026 ### vnstock_data - Cập nhật CLI Installer phiên bản 3.0.2 - Tự động nhận diện API Key đã lưu trong môi trường thay vì yêu cầu người dùng nhập lại. - Tinh chỉnh thiết lập để người dùng tiện cài đặt bộ thư viện trên Google Colab, không yêu cầu bắt buộc phải kết nối Google Drive. - Nâng cấp cơ chế bỏ qua thông báo chuyển đổi câu lệnh import từ vnstock sang vnstock_data gây phiền phức ## 11-03-2026 ### vnstock_data > **Phát hành vnstock_data 3.0.0: Thế hệ mới với Unified UI và Thị trường Quốc tế.** > > Phiên bản 3.0.0 không chỉ là một bản cập nhật thông thường, mà là bước chuyển mình quan trọng của hệ sinh thái Vnstock. Phiên bản này mang đến kiến trúc 7 lớp tiêu chuẩn nghiệp vụ và trải nghiệm lập trình (DX) được nâng cấp vượt trội. - **Kiến trúc 7 Lớp & Unified UI (U2)**: - Hoàn thiện mô hình **Unified UI** với 7 phân vùng chức năng rõ rệt: `Reference`, `Market`, `Fundamental`, `Analytics`, `Alternative`, `Macro`, và `Insights`. - Cách tiếp cận "Vấn đề là trên hết": Bạn không còn phải lo lắng về việc dữ liệu đến từ đâu, chỉ cần tập trung vào việc bạn muốn làm gì (định giá, xem bảng giá hay tra cứu thông tin cơ bản). Chất lượng và nguồn dữ liệu tốt nhất sẽ được Vnstock khuyến nghị. Bạn có thể cá nhân hoá nguồn dữ liệu như cách lập trình cũ nếu muốn để khai thác các chức năng có sẵn nhưng ẩn sâu trong mã nguồn. - Bổ sung thông tin hồ sơ (profile) chi tiết cho **Chứng quyền** và **Hợp đồng tương lai**, giúp bạn nắm bắt đầy đủ thông tin sản phẩm trước khi giao dịch. - Tích hợp **Lịch sự kiện thị trường** toàn diện: từ dữ liệu lịch sử (nghỉ lễ, sự cố thị trường... từ năm 2000) đến các sự kiện hiện tại và tương lai giúp bạn bao quát toàn cảnh thị trường một cách chuyên sâu. - **Trợ lý lập trình thông minh (Next-Gen DX)**: - Tái kích hoạt tính năng **Autocomplete** và **Docstring** vượt trội trên các IDE (VSCode, PyCharm), giúp việc viết code nhanh và ít lỗi hơn. - Bổ sung bộ công cụ khám phá API: `show_api()` để vẽ sơ đồ thư viện ngay trong terminal và `show_doc()` để đọc nhanh hướng dẫn sử dụng cho từng hàm. - Tài liệu (Docstrings) đã được chuyển đổi sang tiếng Anh chuẩn để dễ dàng tiếp cận và phù hợp với tiêu chuẩn lập trình hiện đại và tương tác với AI Agent. - **Chuẩn hóa & Tối ưu hóa hệ thống**: - **Chuẩn hoá dữ liệu bảng giá từ nguồn KBS**: Giải quyết triệt để các vấn đề về hiển thị lô chẵn, lô lẻ; đồng bộ hóa dữ liệu cho đa dạng loại tài sản từ cổ phiếu, phái sinh, chứng quyền đến trái phiếu. - Dữ liệu được **tự động chuẩn hóa (Normalization)** từ nhiều nguồn khác nhau về một định dạng duy nhất, giúp việc tính toán và phân tích nhất quán hơn. - Cơ chế **Lọc tham số (Kwargs Filtering)**: Giúp giảm thiểu lỗi runtime khi bạn vô tình truyền thừa tham số, tăng tính ổn định cho chương trình. - Tối ưu hóa tốc độ tải dữ liệu và cấu trúc nội bộ để sẵn sàng cho các bài toán phân tích dữ liệu lớn. - **Cập nhật Vnstock Agent Guide**: Tài liệu hướng dẫn chi tiết và các quy tắc cho AI Agent trong lập trình tự động được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) --- ## 05-03-2026 ### vnstock_data - **Cập nhật module Unified UI (U2)**: Cập nhật các lớp UI cung cấp cấu trúc lệnh hợp nhất với phân nhóm chặt chẽ lấy cảm hứng từ chuẩn FIX và Bloomberg Terminal giúp điều hướng dễ dàng theo mặc định do Vnstock thiết kế và người dùng không cần cài đặt nguồn dữ liệu. Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) - **Bổ sung hàm lấy thông tin Chứng quyền và hợp đồng tương lai**: - Cung cấp hàm trong giao diện U2 để lấy thông tin chứng quyền và hợp đồng tương lai thông qua Reference().derivatives().warrant() và Reference().derivatives().futures() - **Bổ sung hàm lấy thông tin bộ lọc cổ phiếu từ VCI** thông qua U2 tại `Insights().screener()` - **Cải thiện & bổ sung API nguồn Vĩ mô**: - Bổ sung method `interest_rate` để lấy dữ liệu Lãi suất bình quân & Doanh số trên thị trường liên ngân hàng. Hỗ trợ tham số `format='pivot'` (mặc định) để trả về bảng dạng nhóm cột (MultiIndex giống biểu diễn trên website) hoặc `format='long'` để trả về định dạng phẳng (raw format). - Tích hợp thêm tham số khoảng thời gian tương đối `length` (ví dụ: `90`, `1Y`, `30D`, `100b`) tương tự như cách sử dụng trong `quote.history`. Tính năng này áp dụng đồng bộ cho tất cả các hàm vĩ mô (`gdp`, `cpi`, `interest_rate`, `exchange_rate` v.v...) để bỏ qua việc nhập ngày bắt đầu `start` và kết thúc `end`. - Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) là 1 năm (`1Y`) để trả về thông tin ở khoảng thời gian phù hợp và nhẹ. - Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) - **Cải thiện trải nghiệm sử dụng module lấy dữ liệu hàng hoá**: - Tích hợp khả năng lấy thời gian tương đối thông qua tham số `length` tương tự như module `macro` và `quote.history`. - Thay đổi thời gian lấy dữ liệu mặc định (*khi không cung cấp `start`, `end`, hoặc `length`*) về 1 năm (`1Y`) thay vì lấy toàn bộ lịch sử như trước đây. - Tài liệu hướng dẫn chi tiết được cập nhật qua Agent Guide [tại đây](/onboard/vibe-coding) ## 31-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.4, sửa lỗi và cải thiện trải nghiệm người dùng - Chuẩn hoá định dạng dữ liệu giá thành dạng thập phân xx.xx (ngàn) thay vì xxxx (đồng) cho các hàm `history` và `intraday` trong lớp Quote của nguồn dữ liệu KBS. - Sửa lỗi không cho phép gọi tham số length trong hàm `history` của lớp Quote của nguồn dữ liệu VCI, VND, MAS khi không truyền tham số `start` và `end`. - Sửa lỗi không nhận diện nguồn VND cho lớp hàm Market - Cập nhật chương trình cài đặt vnstock installer chế độ GUI và CLI sử dụng `uv` là công cụ quản lý thư viện thay cho `pip`, tăng tốc độ cài đặt và giảm 30% thời gian hoàn thành. ## 28-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.2, sửa lỗi và cải thiện trải nghiệm người dùng - Chuẩn hoá tham số `period` để lấy dữ liệu báo cáo tài chính cho các phương thức trong lớp Finance của nguồn dữ liệu KBS - cho phép gọi tham số này khi khởi tạo lớp Finance thay vì gọi ở mỗi phương thức. - Bổ sung tham số `length` cho phép lấy dữ liệu hàng hoá theo cách tính thời gian tương đối so với hiện tại thay vì bắt buộc nhập ngày bắt đầu và kết thúc. - Tinh chỉnh nhỏ cho lớp Commodity giúp nạp thư viện chính xác, loại bỏ lỗi liên quan nested f-string sinh ra trong quá trình bảo mật mã nguồn. ## 27-01-2026 ### vnstock_data > Phát hành phiên bản 2.3.1, bổ sung tài liệu hướng dẫn chi tiết Vnstock Agent Guide. - Bổ sung hàm tiện ích `convert_derivative_symbol` giúp chuyển đổi mã hợp đồng tương lai kiểu cũ (VN30F1M) sang kiểu mới sau áp dụng KRX (tương đương 41I1G2000 tại thời điểm tháng 1/2026) - Cải thiện nguồn KBS - Sửa lỗi không nhận diện nguồn dữ liệu KBS từ Finance wrapper - Bổ sung khả năng lấy dữ liệu báo cáo tài chính nhiều năm thay vì cố định 4 năm như phiên bản trước - Tự động nhận diện và chuyển đổi mã hợp đồng tương lai sang kiểu mới để gọi các hàm `history` và `intraday` trong lớp hàm Quote. - Bổ sung khả năng lấy dữ liệu các mã index phổ biến HNXINDEX, HNXINDEX, UPCOMINDEX, VN30, VN100, HNX30 trong hàm `history` của lớp Quote. - Cải thiện chung - Hiện cảnh báo mã index không có dữ liệu `intraday`. ## 23-01-2026 ### vnstock_data - Phát hành phiên bản 2.2.0, bổ sung nguồn dữ liệu KBS cho phép truy cập từ các dịch vụ cloud của Google như Google Colab, Kaggle thay vì nguồn VCI bị chặn IP. - Bổ sung khả năng truy xuất thông tin các bộ chỉ số đầu tư và chỉ số ngành từ HOSE vào Listing class, truy cập được từ mọi giá trị source. - Cập nhật yêu cầu phiên bản gói phụ thuộc tương thích. ## 31-08-2025 ### vnstock_news > Phát hành phiên bản Vnstock News 2.1.0 nâng cấp toàn diện cơ chế tải dữ liệu và cung cấp khả năng tuỳ biến linh hoạt, bổ sung tài liệu hướng dẫn chi tiết.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/cai-dat-phan-mem). - Thay đổi hoàn toàn cấu trúc chương trình theo hướng chặt chẽ và module hoá - Cung cấp cơ chế tự xử lý link sitemap và rss linh hoạt đối với các website sử dụng cơ chế động ví dụ sitemap theo năm-tháng, sitemap với số đếm tăng dần. - Hỗ trợ đầy đủ 10 trang web có sẵn trong danh sách định nghĩa sẵn, người dùng có thể tự bổ sung thêm cấu hình để dùng vnstock_news như một chương trình crawler đọc tin tức hàng loạt. ## 29-08-2025 ### vnstock_pipeline > Phát hành phiên bản Vnstock Pipeline 2.0.1 nâng cấp cơ chế tải dữ liệu Intraday và streaming dữ liệu trong phiên qua WebSocket.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/cai-dat-phan-mem). - Bổ sung tài liệu hướng dẫn tuỳ biến chương trình - Cải thiện trải nghiệm sử dụng: tuỳ chọn địa điểm lưu file khi streaming, lọc dữ liệu mong muốn thay vì tự lưu toàn bộ. - Cải thiện khả năng truy cập dữ liệu intraday liên tục trong phiên giao dịch và ghép nối thông minh hơn. - Bổ sung tính năng Data Manager cho phép quản lý cấu trúc dữ liệu lưu trữ khoa học và chặt chẽ - Bổ sung khả năng lưu trữ dữ liệu định dạng parquet, nén dữ liệu ~75% so với CSV và tăng hiệu năng xử lý. ## 21-07-2025 ### vnstock_data > Phát hành phiên bản Vnstock Data 2.1.3 và nâng cấp cơ chế quản lý license chính xác hơn. Để thực hiện nâng cấp phiên bản, các bạn vui lòng chạy lại chương trình cài đặt, lưu ý nên chạy thử và trải nghiệm qua môi trường như Github Codespace để hình dung các thay đổi để không làm ảnh hưởng đến chương trình hiện có. Hệ thống **không thể quay lại phiên bản cú sau nâng cấp**.
Nâng cấp


### Ads Free Ẩn banner quảng cáo đối với người dùng đang duy trì gói sponsor trừ những thông báo đặc biệt liên quan đến trải nghiệm người dùng hoặc yêu cầu nâng cấp bắt buộc. ### Vnstock Data Explorer - Bổ sung nguồn Fmarket vào mã nguồn - Bổ sung và nâng cấp các API của nguồn VCI - Thay thế API các nhóm hàm Quote, Listing class gặp lỗi từ chối truy cập và đổi url - Bổ sung bộ API mới cho nhóm hàm thuộc Financial class - Cập nhật API mới - Cho phép sử dụng tiếp API cũ từ máy tính local nếu muốn. - Sửa đổi nhóm hàm Trading cho phép lấy dữ liệu phân tích lịch sử giao dịch & bảng giá - Thêm các hàm `foreign_trade` để lấy riêng thông tin giao dịch nước ngoài - Loại bỏ các hàm `trading_stats` và `side_stats` trong nhóm hàm thuộc Trading class để không trùng thông tin với hàm `price_board` ## 02-06-2025 ### vnstock_data ### Vnstock Data Explorer
Bổ sung hàm truy xuất dữ liệu lịch sử giao dịch từ VCI với Trading class thay thế dữ liệu từ CafeF gặp lỗi.
Chi tiết hàm bổ sung tại [Nguồn VCI - Thống kê giao dịch](/docs/vnstock-data/du-lieu-giao-dich) ## 22-04-2025 ### vnstock_data ### Vnstock Data Explorer > Phiên bản `vnstock_data` **2.1.0** đánh dấu bước tiến lớn trong khả năng quản lý và mở rộng dữ liệu, với việc áp dụng **cấu trúc Adapter** chuẩn hóa toàn bộ giao tiếp với nguồn cấp dữ liệu. #### ✨ Những Thay Đổi Quan Trọng | Hạng mục | Thay đổi | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cấu trúc thư viện** | Triển khai mô hình **Adapter Pattern** cho tất cả các lớp dữ liệu (Quote, Trading, Finance, Listing, Company, Macro, Commodity, v.v.). | | **Cách gọi hàm** | Các hàm khi sử dụng Adapter cần truyền **tham số `source`** để xác định rõ nhà cung cấp dữ liệu mong muốn. | | **Mặc định `source`** | Tham số `source` **không còn mặc định ngầm định** như phiên bản trước. Nếu không truyền `source` đúng, hàm có thể gây lỗi `NotSupportedError`. | | **Hướng dẫn chi tiết hơn** | Bổ sung [bảng tra cứu](/vnstock-insider-api/vnstock-data/kien-truc-thu-vien) phương thức hỗ trợ theo nguồn cấp dữ liệu, và sơ đồ hệ thống trực quan. | #### 🚨 Lưu Ý Ảnh Hưởng Đến Đoạn Mã Cũ Nếu bạn đang sử dụng `vnstock_data` theo cách cũ ```python from vnstock_data import Trading trading = Trading(symbol='MSN') quote.history(start="2024-01-01", end="2024-04-01") ``` ➡️ Từ phiên bản 2.1.0, đoạn code trên **sẽ lỗi** nếu thông tin `source` không trùng khớp với nguồn cấp dữ liệu hỗ trợ. Cụ thể, bạn cần sửa lại thành: ```python from vnstock_data import Trading quote = Quote(source="cafef", symbol="VCI") quote.history(start="2024-01-01", end="2025-04-18", interval="1D") ``` ## 06-05-2024 ### vnstock_data ### Vnstock Data Explorer
Cập nhật phiên bản Vnstock Data 2.1.1 sửa lỗi hàm Intraday sau khi triển khai hệ thống KRX từ 5/5/2025 và cải thiện trải nghiệm người dùng.
- [Issue 164](https://github.com/thinh-vu/vnstock/issues/164): Cập nhật tính năng thay đổi user_agent ngẫu nhiên không sử dụng gói fake_user_agent - [Issue 172](https://github.com/thinh-vu/vnstock/issues/172): Bổ sung hàm `price_board` cho Trading class thuộc nguồn dữ liệu VCI - [Issue 178](https://github.com/thinh-vu/vnstock/issues/178) và sửa lỗi dữ liệu Intraday sau cập nhật hệ thống KRX cho nguồn VCI và MAS. - Đóng [Issue 169](https://github.com/thinh-vu/vnstock/issues/169) vì dữ liệu khung thời gian `1W` đã được hỗ trợ sẵn trong thư viện. - [Issue 166](https://github.com/thinh-vu/vnstock/issues/166) Cập nhật thiết lập rate limit cho các nguồn dữ liệu trong gói tài trợ, tránh hiển thị nhầm thông báo nâng cấp. --- ## Document: Tự động nạp Agent Skills và tài liệu Cơ chế nạp Agent Skills giống nhau ở cả hai bản, nên chỉ có một tài liệu. Nội dung nằm tại [/docs/tai-lieu/vnstock-agent-skills](/docs/tai-lieu/vnstock-agent-skills). --- ## Document: Giới thiệu vnstock_news
vnstock_news là thư viện Python thuộc hệ sinh thái Vnstock, được thiết kế để tự động hóa quá trình thu thập, bóc tách và chuẩn hóa dữ liệu tin tức từ các báo điện tử, trong đó hỗ trợ cấu hình sẵn cho 21+ trang tin tức tại Việt Nam. Thư viện hỗ trợ công cụ AI Agent và ứng dụng trong nghiên cứu định lượng, xử lý ngôn ngữ tự nhiên và xây dựng hệ thống giám sát dữ liệu tin tức.
Tài liệu Agent Guide
## Các tính năng nổi bật * **Thu thập dữ liệu đa dạng:** Hỗ trợ trích xuất tiêu đề, mô tả ngắn, nội dung Markdown, thời gian xuất bản, danh mục, URL và tác giả từ 21 trang tin tức phổ biến của Việt Nam và các trang tương thích mà người dùng cung cấp cấu hình tuỳ chỉnh. * **Quản lý nguồn cấp dữ liệu linh hoạt:** Tự động xử lý cả RSS feeds và Sitemaps để lấy danh sách các bài viết mới nhất hoặc theo lịch sử theo nhiều năm. * **Cấu hình dễ dàng:** Đi kèm với cấu hình sẵn cho 21 trang tin tức, giúp bạn bắt đầu nhanh chóng mà không cần cấu hình thủ công phức tạp. * **Khả năng tùy biến cao:** Cho phép bạn định nghĩa cấu hình tùy chỉnh cho các trang web không có sẵn hoặc điều chỉnh các bộ chọn (selector) để phù hợp với thay đổi cấu trúc trang. * **Chế độ thu thập hàng loạt:** Hỗ trợ thu thập thông tin chi tiết của nhiều bài viết cùng lúc, tối ưu hóa hiệu suất. * **Ghi log chi tiết:** Cung cấp thông tin log rõ ràng giúp theo dõi quá trình thu thập và gỡ lỗi. ## Các trang báo được hỗ trợ sẵn **vnstock\_news** cấu hình sẵn cho **21 báo điện tử**, hỗ trợ hai cách truy xuất dữ liệu tiêu chuẩn là **RSS Feeds** (tin cập nhật mới) và **Sitemap XML** (dữ liệu lịch sử). Bạn có thể bổ sung cấu hình cho các trang web khác ngoài danh sách. | STT | Tên Báo | Tên Config | Loại Hình | RSS | Sitemap | Mô Tả / Cơ Quan Chủ Quản | | --- | ------------------------- | ------------------------ | ------------ | --- | ------- | --------------------------------------------------------- | | 1 | **Nhân Dân** | `nhandan` | Cơ quan TW | ✅ | ✅ | Cơ quan trung ương của Đảng Cộng Sản Việt Nam | | 2 | **Tiền Phong** | `tienphong` | Cơ quan TW | ✅ | ✅ | Cơ quan trung ương của Đoàn TNCS Hồ Chí Minh | | 3 | **VietNamNet** | `vietnamnet` | Bộ Ngành | ✅ | ✅ | Cơ quan thuộc Bộ Thông tin và Truyền thông | | 4 | **Dân Trí** | `dantri` | Bộ Ngành | ✅ | ✅ | Báo điện tử thuộc Bộ Lao động - Thương binh và Xã hội | | 5 | **VnExpress** | `vnexpress` | Bộ Ngành | ✅ | ✅ | Thuộc Bộ Khoa học và Công nghệ | | 6 | **Báo Đầu Tư** | `baodautu` | Bộ Ngành | ✅ | ✅ | Cơ quan của Bộ Kế hoạch và Đầu tư | | 7 | **Thời Báo Tài Chính** | `thoibaotaichinhvietnam` | Bộ Ngành | ✅ | ✅ | Báo điện tử thuộc Bộ Tài Chính | | 8 | **Thanh Niên** | `thanhnien` | Tổ chức TW | ✅ | ✅ | Diễn đàn của Hội Liên hiệp Thanh niên Việt Nam | | 9 | **Tuổi Trẻ** | `tuoitre` | Địa phương | ✅ | ✅ | Cơ quan báo của Thành Đoàn TP.HCM | | 10 | **Người Lao Động** | `nld` | Địa phương | ✅ | ✅ | Cơ quan của Thành ủy TP.HCM | | 11 | **Pháp Luật TP.HCM** | `plo` | Địa phương | ✅ | ✅ | Cơ quan chủ quản: UBND TP.HCM | | 12 | **Kinh Tế Sài Gòn** | `ktsg` | Địa phương | ✅ | ✅ | Tạp chí Kinh tế Sài Gòn (UBND TP.HCM) | | 13 | **VnEconomy** | `vneconomy` | Chuyên ngành | ✅ | ✅ | Tạp chí của Hội Khoa học Kinh tế Việt Nam | | 14 | **Diễn Đàn Doanh Nghiệp** | `dddn` | Chuyên ngành | ✅ | ✅ | Cơ quan của Liên đoàn Thương mại & Công nghiệp (VCCI) | | 15 | **PetroTimes** | `petrotimes` | Chuyên ngành | ✅ | ✅ | Tạp chí của Hội Dầu khí Việt Nam | | 16 | **Znews (Tri thức)** | `znews` | Chuyên ngành | ✅ | ✅ | Tạp chí điện tử của Hội Xuất bản Việt Nam | | 17 | **CafeF** | `cafef` | Trang tin | ✅ | ✅ | Trang thông tin kinh tế - tài chính khối VCCorp | | 18 | **CafeBiz** | `cafebiz` | Trang tin | ✅ | ✅ | Trang thông tin kinh doanh - khởi nghiệp khối VCCorp | | 19 | **VietStock** | `vietstock` | Trang tin | ✅ | ✅ | Cổng thông tin Tài chính & Chứng khoán Việt Nam | | 20 | **24h** | `24h` | Tổng hợp | ✅ | ✅ | Trang thông tin điện tử tổng hợp 24h | | 21 | **Người Quan Sát** | `nguoiquansat` | Tổng hợp | ✅ | ✅ | Trang thông tin điện tử chuyên sâu về kinh tế chứng khoán | ## Vai trò của thư viện `vnstock_news` hỗ trợ việc chuẩn bị dữ liệu đầu vào cho quy trình phân tích: * **Hệ thống cảnh báo:** Giám sát, tổng hợp báo cáo diễn biến vĩ mô và cập nhật thông tin doanh nghiệp định kỳ. * **Khoa học dữ liệu:** Đóng gói cơ sở văn bản (dataset) cho việc đào tạo hoặc tinh chỉnh mô hình học sâu, công nghệ Large Language Models (LLMs). * **Nghiên cứu định lượng:** Phân loại chỉ số cảm xúc tài chính (sentiment analysis) nhằm gia tăng hiệu quả các mô hình đánh giá thị trường chứng khoán.
vnstock_news là công cụ lập trình cấu trúc dữ liệu công khai trên Internet, cung cấp nội dung thuần túy nhằm phục vụ cho nghiên cứu và học thuật. Toàn bộ nội dung trích xuất thuộc về bản quyền của cơ quan báo chí chủ quản. Người dùng thư viện phải tuân thủ tuyệt đối quy định về Bản quyền, sở hữu trí tuệ, và giấy phép phân phối theo điều khoản hiện hành nếu có dự định sử dụng kết quả cho hoạt động thương mại, kinh doanh hoặc đăng tải trên các nền tảng công cộng.
Thay vì nghiên cứu cú pháp thư viện một cách thủ công, bạn được khuyến nghị sử dụng tài liệu **Agent Guide** cung cấp cho một trợ lý AI (AI Agent) trong môi trường như Google Antigravity, Claude Code, Cursor. Trợ lý AI sẽ tự động thiết lập và vận hành quá trình trích xuất dữ liệu tin tức chỉ với các câu lệnh ngôn ngữ tự nhiên. --- ## Document: Hướng dẫn Cơ bản
Các hàm và tham số dưới đây cung cấp kiến thức nền tảng về thư viện. Bạn cũng có thể tham khảo tài liệu Agent Guide để hỗ trợ các công cụ AI Agent tự động viết kịch bản thu thập dữ liệu theo yêu cầu.
## 1. Chi Tiết Các Lớp Crawler & Phương Thức API Thư viện `vnstock_news` cung cấp 4 lớp Crawler phục vụ các nhu cầu thu thập dữ liệu khác nhau: ### 1.1 `Crawler` - Giao diện thu thập đơn giản `Crawler` là lớp thu thập dữ liệu cơ bản, phù hợp với nhu cầu lấy nhanh bài viết mới hoặc kiểm tra cấu hình trang báo. #### Khởi tạo: ```python from vnstock_news import Crawler # Cách 1: Sử dụng cấu hình có sẵn của báo (ví dụ: vnexpress, tuoitre, cafef) crawler = Crawler(site_name="vnexpress") # Cách 2: Truyền cấu hình tùy chỉnh cho trang web mới custom_site_config = { "name": "Báo Mới Custom", "domain": "baomoicustom.vn", "rss_urls": ["https://baomoicustom.vn/rss/feed.xml"], "sitemap_url": "https://baomoicustom.vn/sitemap.xml", "config": { "title_selector": {"tag": "h1", "class": "title-detail"}, "content_selector": {"tag": "div", "class": "article-content"} } } crawler_custom = Crawler(custom_config=custom_site_config) ``` #### Phương thức chính: * **`get_articles_from_feed(limit_per_feed=20)`**: Lấy danh sách bài viết từ các kênh RSS Feed. * **`get_articles(sitemap_url=None, limit=10, limit_per_feed=None)`**: Ưu tiên lấy từ RSS Feed, nếu không có RSS sẽ chuyển sang lấy danh sách URL từ Sitemap. #### Bảng tham số `Crawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :--------------- | :----------- | :------- | :-------------------------------------------------------------------------- | | `site_name` | `str` | `None` | Tên định danh của báo trong SITES\_CONFIG (ví dụ: `"vnexpress"`, `"cafef"`) | | `custom_config` | `dict` | `None` | Dictionary chứa cấu hình bộ chọn và nguồn RSS/Sitemap tự định nghĩa | | `limit_per_feed` | `int` | `20` | Số lượng bài viết tối đa cần lấy từ mỗi nguồn RSS feed | | `limit` | `int` | `10` | Tổng số lượng bài viết thu thập khi gọi `get_articles()` | | `sitemap_url` | `str / list` | `None` | Đường dẫn Sitemap XML tùy chỉnh | *** ### 1.2 `BatchCrawler` - Thu thập đồng bộ dữ liệu lịch sử `BatchCrawler` thực hiện tải nội dung chi tiết bài viết theo cơ chế đồng bộ, hỗ trợ lưu dữ liệu tạm để tiếp tục tiến trình nếu bị gián đoạn. #### Ví dụ sử dụng: ```python from vnstock_news import BatchCrawler # Khởi tạo BatchCrawler với khoảng trễ 1.5 giây giữa các yêu cầu crawler = BatchCrawler( site_name="cafef", request_delay=1.5, output_path="./output_data" ) # Tải nội dung chi tiết của 100 bài viết từ Sitemap df_articles = crawler.fetch_articles(limit=100) print(f"Tổng số bài viết đã bóc tách: {len(df_articles)}") ``` #### Bảng tham số `BatchCrawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :-------------- | :----------- | :--------- | :------------------------------------------------------ | | `site_name` | `str` | *Bắt buộc* | Tên định danh báo trong hệ thống cấu hình | | `request_delay` | `float` | `1.0` | Thời gian tạm dừng (giây) giữa các lần gửi yêu cầu HTTP | | `output_path` | `str` | `"./data"` | Thư mục lưu trữ tập tin tạm | | `limit` | `int` | `10` | Số lượng bài viết tối đa cần bóc tách chi tiết | | `sitemap_url` | `str / list` | `None` | URL sitemap cụ thể cần quét dữ liệu | | `debug` | `bool` | `False` | Bật/tắt chế độ ghi log chi tiết | *** ### 1.3 `AsyncBatchCrawler` - Thu thập bất đồng bộ `AsyncBatchCrawler` sử dụng thư viện `aiohttp` và `asyncio`, hỗ trợ tải song song nhiều bài viết cùng lúc để tăng tốc độ thu thập. #### Ví dụ sử dụng: ```python import asyncio from vnstock_news import AsyncBatchCrawler async def run_async_pipeline(): crawler = AsyncBatchCrawler( site_name="tuoitre", max_concurrency=5 # Giới hạn tối đa 5 yêu cầu gửi đi đồng thời ) # Lấy 200 bài viết từ Sitemap của Báo Tuổi Trẻ df_result = await crawler.fetch_articles_async( sources=["https://tuoitre.vn/news-sitemap.xml"], top_n=200 ) return df_result df_tuoitre = asyncio.run(run_async_pipeline()) print(f"Thu thập thành công {len(df_tuoitre)} bài viết.") ``` #### Bảng tham số `AsyncBatchCrawler`: | Tham Số | Kiểu Dữ Liệu | Mặc Định | Mô Tả | | :---------------- | :----------- | :--------- | :------------------------------------------------------ | | `site_name` | `str` | *Bắt buộc* | Tên định danh trang báo | | `max_concurrency` | `int` | `5` | Số lượng kết nối song song tối đa | | `sources` | `list` | *Bắt buộc* | Danh sách đường dẫn Sitemap XML nguồn | | `top_n` | `int` | `10` | Số lượng bài viết tối đa cần bóc tách từ danh sách URLs | *** ### 1.4 `EnhancedNewsCrawler` - Động cơ thu thập mở rộng `EnhancedNewsCrawler` tích hợp bộ nhớ đệm (Cache), cơ chế làm sạch văn bản, kiểm tra tính hợp lệ dữ liệu và tự động thử lại khi gặp lỗi kết nối. #### Ví dụ sử dụng: ```python import asyncio from vnstock_news import EnhancedNewsCrawler async def run_enhanced_pipeline(): crawler = EnhancedNewsCrawler( cache_enabled=True, cache_ttl=86400, # Thời gian lưu bộ nhớ đệm 24 giờ max_concurrency=5 ) df_data = await crawler.fetch_articles_async( sources=["https://cafef.vn/latest-news-sitemap.xml"], site_name="cafef", top_n=100, clean_content=True # Tự động loại bỏ các thẻ HTML rác và quảng cáo ) return df_data df_enhanced = asyncio.run(run_enhanced_pipeline()) ``` *** ## 2. So Sánh Nguồn Dữ Liệu: RSS Feeds và Sitemap XML Việc lựa chọn nguồn thu thập phụ thuộc vào mục đích sử dụng cụ thể: | Tiêu Chí So Sánh | RSS Feeds (Tin Mới) | Sitemap XML (Lịch Sử) | | :------------------- | :-------------------------------------------------- | :------------------------------------------------------ | | **Tốc độ thu thập** | Nhanh | Phụ thuộc số bài và thời gian trễ | | **Phạm vi dữ liệu** | Chứa các bài mới phát hành gần đây | Chứa danh sách bài viết theo thời gian lưu trữ của báo | | **Độ sâu thông tin** | Có sẵn thông tin tóm tắt và ngày đăng | Cần gửi thêm yêu cầu HTTP để bóc tách nội dung chi tiết | | **Mục đích sử dụng** | Giám sát tin tức mới, nhận thông báo tin bài | Xây dựng bộ dữ liệu phân tích, huấn luyện mô hình | | **Cơ chế dự phòng** | Tự động chuyển sang Sitemap nếu RSS không hoạt động | Tự động phân giải các Sitemap động theo tháng/năm | **Gợi ý:** Bạn có thể kết hợp sử dụng **RSS Feeds** để cập nhật bài viết mới định kỳ và quét **Sitemap XML** để bổ sung các bài viết bị sót. *** ## 3. Cấu Trúc Dữ Liệu Trả Về Dữ liệu bài viết sau khi bóc tách từ các lớp Crawler được trả về dưới dạng **Pandas DataFrame** hoặc `List[Dict]` với **11 trường dữ liệu chuẩn hóa**: | Cột Dữ Liệu | Kiểu Dữ Liệu | Mô Tả Chi Tiết | Ví Dụ Dữ Liệu Mẫu | | :------------------ | :----------- | :--------------------------------- | :------------------------------------------------------ | | `url` | `str` | Đường dẫn URL của bài viết | `"https://cafef.vn/thi-truong-chung-khoan-2026.chn"` | | `title` | `str` | Tiêu đề bài viết | `"Thị trường chứng khoán bật tăng mạnh phiên đầu tuần"` | | `short_description` | `str` | Đoạn tóm tắt / Sapo bài viết | `"Dòng tiền khối ngoại quay trở lại mua ròng..."` | | `content` | `str` | Nội dung văn bản (đã loại bỏ HTML) | `"Nội dung chi tiết các đoạn văn bản trong bài..."` | | `publish_time` | `datetime` | Thời gian xuất bản (dạng ISO) | `2026-04-15 09:30:00` | | `author` | `str` | Tên tác giả hoặc nguồn dẫn | `"Nguyễn Văn A"` / `"Theo CafeF"` | | `category` | `str` | Chuyên mục tin tức | `"Chứng khoán"` / `"Tài chính vĩ mô"` | | `tags` | `str` | Danh sách từ khóa / Tags bài viết | `"VN-Index, Chứng khoán, Lãi suất"` | | `view_counts` | `int` | Số lượt xem (nếu báo có hiển thị) | `15200` | | `image_url` | `str` | Đường dẫn ảnh đại diện bài viết | `"https://cdn.cafef.vn/thumb_w/640/image.jpg"` | | `source` | `str` | Tên định danh nguồn báo | `"cafef"` / `"vnexpress"` | Dữ liệu trả về ở dạng Pandas DataFrame giúp bạn dễ dàng thực hiện lọc, nhóm, lưu trữ ra tập tin CSV/Parquet hoặc nạp vào các quy trình xử lý dữ liệu tiếp theo. --- ## Document: Lịch sử phiên bản ## 28-06-2026 > Phát hành `vnstock_data` phiên bản 3.2.3 hoàn thiện cấu trúc tin tức của công ty niêm yết và chuẩn hoá mô hình dữ liệu. - **Chuẩn hoá mô hình dữ liệu (Unified Schema) cho Tin tức doanh nghiệp:** Giao diện `Reference().company('MÃ_CK').news()` được chuẩn hoá hoàn toàn trên 3 nguồn `vci`, `kbs`, và `cafef` với chung 10 cột dữ liệu thống nhất (`id`, `symbol`, `title`, `summary`, `content`, `publish_time`, `source`, `url`, `category`, `image_url`). - **Nâng cấp tính năng lấy tin tức chi tiết:** Bổ sung tham số `mode='detail'` cho phép đọc full nội dung bài viết và bóc tách các link đính kèm trực tiếp từ `vci` và `cafef`. - **Hỗ trợ tuỳ chỉnh tham số linh hoạt:** Chuẩn hoá các tham số bộ lọc thời gian (`start`, `end`, `length`, `limit`) và nâng cấp khả năng truyền linh hoạt `**kwargs` xuống hàm của từng nguồn. ## 03-04-2026 > **Phát hành vnstock_news 2.2.0: Công cụ truy xuất dữ liệu tin tức hiệu suất cao** > > Bản phát hành mới giải phóng bạn khỏi những lỗi xảy ra trong quá trình xử lý dữ liệu, mang tới sự ổn định khi trích xuất dữ liệu tin tức từ 21 trang tin nổi bật tại Việt Nam. ### ✨ Nâng cấp nổi bật - **Kiến trúc Crawler Hợp Nhất (Unified Crawler):** Khai thác song song và tự động dự phòng chéo (fallback) giữa luồng RSS và Sitemap, đảm bảo hệ thống bạn luôn có tin mới khi một trong hai luồng gặp sự cố. - **Trích xuất metadata linh hoạt:** Tăng cường khả năng bắt chính xác Selector qua các thuộc tính linh hoạt (`id`, `data-slot`, `rel`) thay vì phụ thuộc mỗi thẻ `class` theo CSS Selector truyền thống. Chủ động trích xuất thêm thẻ Tags, Lượt xem và Chuyên mục của bài. - **Làm sạch tự động & Xử lý thời gian:** - **Date Parser:** Tự động "thấu hiểu" và ép kiểu mọi định dạng thời gian lạ lẻ (như *15 phút trước*, *Thứ năm...*) về chuẩn ISO thống nhất cho Database. - **Spam/Media Link Filter:** Rà soát và loại bỏ link nhiễu phân trang, hình ảnh, URL rác đính kèm trong RSS. - Tự động bỏ qua lỗi chứng chỉ SSL để duy trì kết nối cho những tòa soạn chưa nâng cấp máy chủ hiện đại. ### 🐛 Vận hành trơn tru hơn - Sửa dứt điểm tình trạng trả về Data nhưng cột Nội dung trống rỗng (Missing Content 100%) gây ra bởi lỗi đọc JSON. - **Bổ sung đầu báo mới được hỗ trợ:** Bổ sung và tinh chỉnh cấu trúc CSS cho hàng loạt trang báo mới (Tiền Phong, Người Lao Động, Thanh Niên, Znews, Dân Trí, Đầu Tư, VnEconomy). - Bổ sung bộ kịch bản dùng thử "All-in-one" và tái cấu trúc tài liệu ví dụ, tự động dọn dẹp kết quả xuất file vào phân vùng tĩnh `/output/`.
Nhấp để xem danh sách 21 trang báo được hỗ trợ sẵn | STT | Tên Báo | Tên Config | Loại Hình | RSS | Sitemap | | --- | ------------------------- | ---------------------- | ------------ | --- | ------- | | 1 | **Nhân Dân** | nhandan | Cơ quan TW | ✅ | ✅ | | 2 | **Tiền Phong** | tienphong | Cơ quan TW | ✅ | ✅ | | 3 | **VietNamNet** | vietnamnet | Bộ Ngành | ✅ | ✅ | | 4 | **Dân Trí** | dantri | Bộ Ngành | ✅ | ✅ | | 5 | **VnExpress** | vnexpress | Bộ Ngành | ✅ | ✅ | | 6 | **Báo Đầu Tư** | baodautu | Bộ Ngành | ✅ | ✅ | | 7 | **Thời Báo Tài Chính** | thoibaotaichinhvietnam | Bộ Ngành | ✅ | ✅ | | 8 | **Thanh Niên** | thanhnien | Tổ chức TW | ✅ | ✅ | | 9 | **Tuổi Trẻ** | tuoitre | Địa phương | ✅ | ✅ | | 10 | **Người Lao Động** | nld | Địa phương | ✅ | ✅ | | 11 | **Pháp Luật TP.HCM** | plo | Địa phương | ✅ | ✅ | | 12 | **Kinh Tế Sài Gòn** | ktsg | Địa phương | ✅ | ✅ | | 13 | **VnEconomy** | vneconomy | Chuyên ngành | ✅ | ✅ | | 14 | **Diễn Đàn Doanh Nghiệp** | dddn | Chuyên ngành | ✅ | ✅ | | 15 | **PetroTimes** | petrotimes | Chuyên ngành | ✅ | ✅ | | 16 | **Znews (Tri thức)** | znews | Chuyên ngành | ✅ | ✅ | | 17 | **CafeF** | cafef | Trang tin | ✅ | ✅ | | 18 | **CafeBiz** | cafebiz | Trang tin | ✅ | ✅ | | 19 | **VietStock** | vietstock | Trang tin | ✅ | ✅ | | 20 | **24h** | 24h | Tổng hợp | ✅ | ✅ | | 21 | **Người Quan Sát** | nguoiquansat | Tổng hợp | ✅ | ✅ |
## 31-08-2025 > Phát hành phiên bản Vnstock News 2.1.0 nâng cấp toàn diện cơ chế tải dữ liệu và cung cấp khả năng tuỳ biến linh hoạt, bổ sung tài liệu hướng dẫn chi tiết.
Xem hướng dẫn


Để cài đặt bản cập nhật, vui lòng chạy lại chương trình cài đặt của Vnstock [tại đây](/onboard-member/cai-dat-go-loi/cai-dat-phan-mem). - Thay đổi hoàn toàn cấu trúc chương trình theo hướng chặt chẽ và module hoá - Cung cấp cơ chế tự xử lý link sitemap và rss linh hoạt đối với các website sử dụng cơ chế động ví dụ sitemap theo năm-tháng, sitemap với số đếm tăng dần. - Hỗ trợ đầy đủ 10 trang web có sẵn trong danh sách định nghĩa sẵn, người dùng có thể tự bổ sung thêm cấu hình để dùng vnstock_news như một chương trình crawler đọc tin tức hàng loạt. --- ## Document: Mẫu Chương trình Cập nhật Tin tức
Phần này giới thiệu cách thiết lập hệ thống cập nhật tin tức tự động dựa trên thư viện vnstock_news, từ việc chạy công cụ dòng lệnh đến việc triển khai các kịch bản Python ghi log hệ thống, lọc bài trùng lặp và xử lý dữ liệu hàng loạt.
## Sử dụng qua Dòng Lệnh (CLI) Sau khi cài đặt `vnstock_news`, bạn có thể chạy chương trình theo dõi tin tức trực tiếp từ dòng lệnh Terminal để kiểm thử quá trình thu thập và lưu trữ dữ liệu: ```bash vnstock-news-crawler ``` Bạn có thể xem thêm tài liệu **Agent Guide** bên dưới để hướng dẫn các công cụ AI Agent (Google Antigravity, Claude Code, Cursor) tự động xây dựng kịch bản thu thập dữ liệu theo yêu cầu.
Truy cập tài liệu Agent Guide
![Khởi động chương trình Vnstock News từ Terminal của macOS](/images/khoi-dong-vnstock-news-che-do-dong-lenh.png "Khởi động chương trình Vnstock News từ Terminal của macOS") Khi khởi chạy, chương trình kết nối nguồn tin công khai của các báo, thực hiện trích xuất dữ liệu theo thời gian yêu cầu và lưu kết quả dưới dạng tập tin CSV tại thư mục `output`. ![Nội dung dữ liệu tin tức được chuẩn hoá từ Vnstock News](/images/bang-tinh-noi-dung-tin-tuc-chuan-hoa-vnstock-news.png "Nội dung dữ liệu tin tức được chuẩn hoá từ Vnstock News") Khung báo cáo sau thống kê sẽ xuất về tệp tĩnh mang tên `news_summary.txt`: ```text News Monitor Report - 2026-04-15 ================================================== STATISTICS -------------------------------------------------- Total articles collected: 580 TRENDING TOPICS -------------------------------------------------- 1. chứng khoán: 107 mentions 2. thị trường: 76 mentions 3. lãi suất: 45 mentions ... ``` Giao diện vận hành thực tế minh họa trên Google Colab: ![Tóm tắt kết quả chương trình khi kết nối và phân tích tin tức trên Google Colab](/images/tom-tat-ket-qua-thuc-thi-vnstock-news.png "Tóm tắt kết quả chương trình khi kết nối và phân tích tin tức trên Google Colab") *** ## Kịch Bản Python 1: Giám Sát Tin Tức Qua RSS Feed Kịch bản Python dưới đây vận hành luồng kiểm tra tin mới định kỳ, ghi log quá trình chạy và lọc bài viết trùng lặp để tránh lưu lại bài viết đã thu thập. ```python import os import time import logging from datetime import datetime import pandas as pd from vnstock_news import Crawler # Cấu hình ghi log hệ thống logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s - %(message)s", handlers=[ logging.FileHandler("news_monitor.log", encoding="utf-8"), logging.StreamHandler() ] ) logger = logging.getLogger("RealTimeNewsMonitor") class ProductionNewsMonitor: def __init__(self, target_sites: list, poll_interval_seconds: int = 300, output_dir: str = "./news_data"): self.target_sites = target_sites self.poll_interval = poll_interval_seconds self.output_dir = output_dir self.seen_urls = set() os.makedirs(self.output_dir, exist_ok=True) logger.info(f"Đã khởi tạo News Monitor cho các báo: {self.target_sites}") def poll_once(self) -> int: """Thực hiện một lượt quét tin mới từ danh sách RSS feeds.""" collected_articles = [] for site in self.target_sites: try: logger.info(f"Đang kiểm tra RSS feed từ: {site}") crawler = Crawler(site_name=site) articles = crawler.get_articles_from_feed(limit_per_feed=15) new_in_site = 0 for item in articles: url = item.get("url") if url and url not in self.seen_urls: self.seen_urls.add(url) collected_articles.append(item) new_in_site += 1 logger.info(f"[{site}] Phát hiện {new_in_site} tin bài mới.") except Exception as e: logger.error(f"Lỗi khi thu thập tin từ site '{site}': {e}", exc_info=True) # Lưu tin bài mới ra file CSV theo ngày nếu có dữ liệu mới if collected_articles: df = pd.DataFrame(collected_articles) today_str = datetime.now().strftime("%Y-%m-%d") filename = os.path.join(self.output_dir, f"realtime_news_{today_str}.csv") # Ghi nối tiếp (append) vào file CSV nếu file đã tồn tại file_exists = os.path.exists(filename) df.to_csv(filename, mode="a", index=False, header=not file_exists, encoding="utf-8-sig") logger.info(f"Đã ghi nhận và lưu {len(collected_articles)} bài viết mới vào: {filename}") return len(collected_articles) def start_continuous_monitoring(self): """Khởi chạy vòng lặp giám sát định kỳ.""" logger.info(f"Khởi chạy vòng lặp giám sát định kỳ (chu kỳ: {self.poll_interval}s)...") try: while True: total_new = self.poll_once() logger.info(f"Hoàn thành chu kỳ. Tổng tin bài mới thu thập: {total_new}. Tạm dừng {self.poll_interval}s...") time.sleep(self.poll_interval) except KeyboardInterrupt: logger.info("Đã nhận tín hiệu dừng từ người dùng (Ctrl+C). Dừng hệ thống an toàn.") if __name__ == "__main__": # Khởi tạo monitor cho các báo có RSS (VnExpress, Tuổi Trẻ, Thanh Niên) monitor = ProductionNewsMonitor( target_sites=["vnexpress", "tuoitre", "thanhnien"], poll_interval_seconds=180, # Quét tin 3 phút 1 lần output_dir="./output_stream" ) # Thực hiện 1 lượt quét ngay lập tức monitor.poll_once() ``` *** ## Kịch Bản Python 2: Thu Thập Dữ Liệu Hàng Loạt Qua Sitemap Đối với các bài toán xây dựng bộ dữ liệu lịch sử phục vụ phân tích, kịch bản dưới đây sử dụng `EnhancedNewsCrawler` với bộ nhớ đệm và tự động làm sạch nội dung bài viết: ```python import asyncio import logging from vnstock_news import EnhancedNewsCrawler # Cấu hình logging logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s") logger = logging.getLogger("BatchPipeline") async def run_batch_extraction_pipeline(): logger.info("Khởi động quy trình bóc tách dữ liệu lịch sử hàng loạt...") # Khởi tạo EnhancedNewsCrawler với bộ nhớ đệm SQLite crawler = EnhancedNewsCrawler( cache_enabled=True, cache_type="sqlite", cache_ttl=86400, # Đệm dữ liệu trong 24 giờ max_concurrency=5 # Giới hạn 5 luồng tải song song ) # Danh sách sitemap mục tiêu từ các báo điện tử tài chính sitemap_sources = [ "https://cafef.vn/latest-news-sitemap.xml", "https://tuoitre.vn/news-sitemap.xml" ] logger.info("Bắt đầu thu thập bất đồng bộ từ Sitemap sources...") df_corpus = await crawler.fetch_articles_async( sources=sitemap_sources, site_name="cafef", top_n=100, clean_content=True # Tự động loại bỏ HTML thừa, quảng cáo ) if not df_corpus.empty: logger.info(f"Đã trích xuất và chuẩn hóa thành công {len(df_corpus)} bài viết.") # Xem thông tin dữ liệu print("\n--- THÔNG TIN BỘ DỮ LIỆU ---") print(df_corpus.info()) print("\n--- MẪU 3 BÀI VIẾT ĐẦU TIÊN ---") print(df_corpus[["title", "author", "publish_time", "source"]].head(3)) # Xuất dữ liệu ra file CSV output_file = "news_corpus_batch_export.csv" df_corpus.to_csv(output_file, index=False, encoding="utf-8-sig") logger.info(f"Dữ liệu đã được xuất ra file: {output_file}") else: logger.warning("Không thu thập được dữ liệu bài viết nào từ nguồn sitemap đã cho.") if __name__ == "__main__": asyncio.run(run_batch_extraction_pipeline()) ``` Các kịch bản trên hỗ trợ tự động hóa quy trình thu thập dữ liệu tin tức từ các báo điện tử một cách ổn định. --- ## Document: Tùy biến Nâng cao
Phần này hướng dẫn tùy chỉnh chi tiết từ cấu trúc SiteConfig, thiết lập danh sách bộ chọn CSS dự phòng, trích xuất dữ liệu cấu trúc trong thẻ script (JSON-LD, DataLayer) đến việc tự bổ sung cấu hình cho các trang báo mới.
## 1. Cấu Trúc `SiteConfig` và Sitemap Động (`DynamicSitemapResolver`) Cấu hình của từng trang báo được lưu trữ tại bảng từ điển `SITES_CONFIG` trong `vnstock_news.config.sites`. Mỗi cấu hình bao gồm các thông tin: * **`name`**: Tên hiển thị của báo (ví dụ: `"Báo CafeF"`). * **`domain`**: Tên miền chính (ví dụ: `"cafef.vn"`). * **`rss`**: Danh sách đường dẫn RSS Feed (`urls: [...]`). * **`sitemap_url`**: Đường dẫn tới Sitemap XML chính. * **`sitemap`**: Cấu hình Sitemap động khi trang báo chia sitemap theo thời gian (`pattern_type` dạng `"monthly"` hoặc `"incremental"`). * **`config`**: Danh sách bộ chọn CSS/XPath để bóc tách tiêu đề, sapo, nội dung, thời gian xuất bản, tác giả và chuyên mục. ### Xử lý Sitemap Động Một số trang báo (như Báo Pháp luật TP.HCM - PLO, Thời báo Kinh tế Sài Gòn) phân chia sitemap theo từng tháng hoặc dạng lũy tiến. Lớp `DynamicSitemapResolver` trong `vnstock_news` hỗ trợ tự động xác định đường dẫn Sitemap theo thời gian: ```python from vnstock_news.config.sitemap_resolver import DynamicSitemapResolver from vnstock_news.config.sites import SITES_CONFIG # 1. Khởi tạo resolver ở chế độ ghi log resolver = DynamicSitemapResolver(debug=True) # 2. Lấy cấu hình của báo có sitemap động (ví dụ: PLO) plo_config = SITES_CONFIG["plo"] # 3. Tính toán URL sitemap phù hợp với thời điểm hiện tại (năm - tháng) resolved_url = resolver.get_sitemap_url("plo", plo_config) print(f"Sitemap URL được tạo: {resolved_url}") # Kết quả trả về dạng: https://plo.vn/sitemaps/news-2026-8.xml ```
Khi thêm một trang báo mới có đường dẫn sitemap thay đổi theo tháng (như news-2026-08.xml) hoặc theo ngày, bạn có thể thiết lập thuộc tính sitemap với pattern_type: "monthly" hoặc "incremental" cùng chuỗi định dạng format tương ứng.
*** ## 2. Thiết Lập Bộ Chọn CSS Dự Phòng Khi cấu hình giao diện bài viết giữa các chuyên mục không đồng nhất, `vnstock_news` hỗ trợ truyền danh sách nhiều bộ chọn (CSS Selectors) theo thứ tự ưu tiên. Thư viện sẽ lần lượt thử nghiệm các bộ chọn trong danh sách cho đến khi tìm thấy dữ liệu. ### Các bộ chọn chuẩn trong `config` Dictionary `config` hỗ trợ các khóa sau: * `title_selector`: Tiêu đề bài viết. * `short_desc_selector`: Đoạn tóm tắt / Sapo. * `content_selector`: Nội dung chính bài viết. * `publish_time_selector`: Thời gian xuất bản. * `author_selector`: Tên tác giả. * `category_selector`: Chuyên mục. * `tags_selector`: Từ khóa / Tags. * `image_url_selector`: Ảnh đại diện bài viết. ### Cấu hình bộ chọn dự phòng và thuộc tính thẻ Một bộ chọn có thể cấu hình tìm kiếm theo thẻ HTML (`tag`), tên lớp (`class`) hoặc lấy trực tiếp thuộc tính thẻ (`attr` như `content`, `datetime`, `src`): ```python custom_advanced_selectors = { # Tiêu đề: Thử class "detail-title" trước, nếu không có chuyển sang thẻ meta "title_selector": [ {"tag": "h1", "class": "detail-title"}, {"tag": "meta", "attr": "property", "value": "og:title", "extract": "content"} ], # Sapo bài viết (phần tóm tắt ở đầu) "short_desc_selector": [ {"tag": "h2", "class": "sapo-detail"}, {"tag": "div", "class": "sapo"} ], # Nội dung bài viết "content_selector": {"tag": "div", "class": "detail-content"}, # Thời gian xuất bản: Lấy thuộc tính datetime trong thẻ