Đăng nhập và dòng lệnh

Cài thư viện vnstock thế hệ 5 xong, bạn có thêm lệnh vnstock trong terminal. Lệnh này lo phần tài khoản và chẩn đoán: đăng nhập, xem cấp, xem hạn mức, kiểm môi trường. Lấy dữ liệu vẫn viết bằng Python.

Lệnh nào cũng nhận --json để in kết quả cho máy đọc (script, CI, trợ lý AI). Không lệnh nào in khoá API hay định danh thiết bị đầy đủ.

Các lệnh

Gõ vnstock --help hoặc vnstock <lệnh> --help để xem đủ tham số.

Đăng nhập

vnstock register              # hỏi khoá, gõ không hiện ra màn hình
vnstock status                # kiểm lại cấp và hạn

Lấy khoá tại trang tài khoản. Khoá cấp Cộng đồng miễn phí cho cá nhân, học tập và nghiên cứu. Không đăng nhập thì thư viện chạy ở cấp Khách, với giới hạn chặt hơn.

Chạy trong script hay CI, đưa khoá qua stdin để khoá không nằm trên dòng lệnh và không vào lịch sử shell:

printf '%s' "$VNSTOCK_API_KEY" | vnstock register --stdin

Trong notebook, dùng bốn hàm ở gốc gói:

import os
import vnstock

vnstock.login(os.environ["VNSTOCK_API_KEY"])   # một lần trên mỗi máy
vnstock.status()     # dict: tier, authenticated, expires_at, device_id, release…
vnstock.usage()      # dict: limits, used, rule
vnstock.logout()     # xoá khoá khỏi máy

vnstock.setup_api_key(key) là tên khác của vnstock.login(key), giữ cho các hướng dẫn cũ.

Đừng dán khoá thẳng vào notebook hay tệp mã sẽ đẩy lên Git. Đặt khoá trong biến môi trường hoặc tệp .env không đưa lên kho mã.

Ví dụ vnstock status khi chưa đăng nhập:

Cấp: Khách (chưa đăng nhập)
Đã đăng nhập: chưa
Hạn: không
Thiết bị: xxxx…xxxx
Phiên bản: vnstock 5.0.0 (core 5.0.0)
Hạn dùng bản vnstock 5.0.0: 11/10/2027 (giờ Việt Nam), còn 365 ngày

Hạn mức và giới hạn của cấp

vnstock usage cho biết hạn mức chung của tài khoản còn bao nhiêu phần trăm trong giờ, ngày, tháng này và khi nào đặt lại. Hạn mức dùng chung cho mọi thư viện Vnstock trên mọi thiết bị, nên con số khớp với trang tài khoản. Cấp của bạn được bao nhiêu kỳ báo cáo, bao nhiêu ngày lịch sử, những hàm nào thì xem ở Cấp tài khoản và giới hạn.

Khi một kết quả bị cắt theo cấp, thư viện phát một cảnh báo cho mỗi loại cắt trong một phiên chạy. Con số nằm trong df.attrs:

from vnstock import Fundamental

df = Fundamental().equity("FPT").income_statement(period="quarter")
print({k: v for k, v in df.attrs.items() if k.startswith("tier_cap_")})

Danh mục (danh sách mã, phân ngành, danh sách chỉ số) không bị cắt ở cấp nào. Khớp lệnh trong phiên ở cấp Khách và Cộng đồng nhận tối đa 5.000 dòng mỗi lần gọi.

Hàm hay nguồn chưa mở cho cấp của bạn thì báo EntitlementError (mã VNSTOCK_TIER_ROUTE hoặc VNSTOCK_TIER_SOURCE) trước khi gửi bất kỳ truy vấn nào.

Chẩn đoán

vnstock doctor

doctor chạy bảy phép kiểm và dừng ở gợi ý sửa cho phép đầu tiên không đạt. Mã thoát là 1 nếu có phép không đạt, nên dùng được trong CI. Khi cần nhờ hỗ trợ, gửi kèm kết quả của vnstock doctor và vnstock version.

Ngôn ngữ hiển thị

Lỗi, cảnh báo và đầu ra của lệnh vnstock hiện cả tiếng Việt lẫn tiếng Anh, tiếng Việt trước. Hai cách chọn một ngôn ngữ:

vnstock settings language vi       # lưu lâu dài: chỉ tiếng Việt
vnstock settings language en       # chỉ tiếng Anh
vnstock settings language default  # trở lại song ngữ
VNSTOCK_LANG=en python script.py   # chỉ cho một lần chạy, thắng cài đặt đã lưu

Trong mã, mọi lỗi giữ cả hai bản ở e.message_vi và e.message_en. Đầu ra --json không dịch.

Hạn dùng của bản đang cài

Mỗi bản vnstock dùng được 365 ngày tính từ ngày được duyệt cho tải. vnstock status hiện ngày hết hạn và số ngày còn lại.

• Còn dưới 30 ngày, lần lấy dữ liệu đầu tiên trong phiên phát một FutureWarning.
• Hết hạn thì mọi lệnh lấy dữ liệu báo UnsupportedError mã VNSTOCK_RELEASE_EXPIRED, kèm lệnh cập nhật. status, policy, register vẫn chạy.

Cập nhật:

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

pip install -U vnstock trơn sẽ lấy bản thế hệ 4 trên PyPI, không phải thế hệ 5.

Thư viện bổ sung

vnstock install --list      # thư viện bổ sung và cấp tối thiểu của từng thư viện
vnstock install             # cài mọi thư viện bổ sung mà khoá của bạn được dùng
vnstock install --dry-run   # xem lệnh sẽ chạy, không cài

Lệnh đọc khoá đã lưu và cài vào đúng trình thông dịch Python đang chạy. Khoá không xuất hiện trên dòng lệnh hay trong lịch sử shell. Gõ sai tên thì cả lệnh bị từ chối, không cài nhầm gói khác.

Giao diện tương tác

Gõ vnstock không kèm lệnh trong terminal để mở một dấu nhắc. Gõ / để xem lệnh, Tab để hoàn tất tên lệnh (macOS, Linux), /exit hoặc Ctrl-D để thoát. Các lệnh như /login, /status, /usage, /doctor, /language vi, /version gọi lại đúng lệnh tương ứng ở trên. /data price FPT in một bảng giá ngắn kèm dòng Python tạo ra nó.