1. OpenAPI là gì?
Mục đích
OpenAPI là cách an toàn để khách hàng, đối tác và ứng dụng kết nối với nền tảng chứng khoán thông qua các API đã được phê duyệt.Tổng quan
OpenAPI giúp người dùng xem thông tin thị trường, kiểm tra tài khoản, theo dõi danh mục và đặt lệnh mà không cần thực hiện thủ công trên web cho từng thao tác.Khi nào nên dùng
Sử dụng OpenAPI khi bạn muốn xây dựng ứng dụng giao dịch, cổng khách hàng, dashboard nội bộ, công cụ báo cáo hoặc quy trình tự động hóa.Hướng dẫn từng bước
1
Đăng ký tài khoản
Đăng ký tài khoản với công ty chứng khoán.
2
Đăng ký dịch vụ OpenAPI
Đăng ký sử dụng dịch vụ OpenAPI nếu được yêu cầu.
3
Nhận thông tin truy cập
Nhận thông tin truy cập cho môi trường sandbox hoặc production.
4
Xác thực ứng dụng
Xác thực ứng dụng của bạn.
5
Gọi API
Gọi các API cần cho market data, portfolio hoặc trading.
6
Xử lý phản hồi
Xử lý phản hồi, lỗi và kiểm tra quyền cẩn thận.
Ví dụ minh họa: Một nhà đầu tư cá nhân sử dụng ứng dụng giao dịch hiển thị giá theo thời gian thực, giá trị danh mục và các lệnh hiện tại. Ứng dụng dùng OpenAPI để lấy dữ liệu và gửi lệnh.
2. Bắt đầu với OpenAPI
Đăng ký tài khoản
Đăng ký với công ty chứng khoán bằng quy trình onboarding đã được phê duyệt và cung cấp các thông tin doanh nghiệp hoặc cá nhân theo yêu cầu.Quy trình đăng ký sử dụng API
Sau khi đăng ký, vui lòng chờ cấp quyền OpenAPI và hoàn tất các bước phê duyệt do công ty chứng khoán quy định.Môi trường Sandbox và Production
Dùng sandbox cho mục đích kiểm thử và phát triển. Chỉ dùng production cho hoạt động thực tế sau khi thông tin đăng nhập và quyền truy cập đã được phê duyệt.Hướng dẫn từng bước
1
Xác nhận tài khoản
Tạo hoặc xác nhận tài khoản chứng khoán của bạn.
2
Gửi yêu cầu truy cập
Gửi yêu cầu truy cập OpenAPI.
3
Chờ phê duyệt
Chờ phê duyệt và nhận hướng dẫn thiết lập.
4
Kiểm thử trên Sandbox
Dùng thông tin sandbox để kiểm thử.
5
Chuyển sang Production
Chuyển sang production chỉ khi đã xác thực hoàn tất.
Ví dụ minh họa: Một nhóm phát triển kiểm thử đăng nhập, market data và đặt lệnh trong sandbox trước khi kích hoạt cùng quy trình đó cho người dùng thật ở production.
3. OpenAPI hoạt động như thế nào?
Luồng xác thực
Ứng dụng của bạn gửi thông tin xác thực qua quy trình xác thực đã được phê duyệt. Sau khi xác minh, hệ thống trả về access token.Khái niệm Access Token
Access token là một khóa số tạm thời chứng minh ứng dụng của bạn được phép gửi yêu cầu.Luồng Request → Response
- Ứng dụng gửi request đến một API endpoint.
- Request bao gồm access token.
- Nền tảng kiểm tra token, quyền truy cập và môi trường.
- Nền tảng trả về dữ liệu, thông báo thành công hoặc lỗi.
Quy trình API điển hình
1
Xác thực
Xác thực ứng dụng của bạn.
2
Lấy access token
Lấy access token.
3
Gọi API
Gọi API cần thiết.
4
Đọc phản hồi
Đọc phản hồi.
5
Xử lý lỗi
Xử lý lỗi hoặc thử lại khi phù hợp.
Ví dụ minh họa: Một ứng dụng portfolio đăng nhập, nhận access token, yêu cầu thông tin tài khoản, sau đó hiển thị số dư tiền mặt và vị thế trên màn hình.
4. API dữ liệu thị trường
Dữ liệu thị trường có sẵn
Tùy theo quyền truy cập và cấu hình sản phẩm, market data có thể bao gồm giá khớp gần nhất, thông tin giá mua và bán, giá cao nhất và thấp nhất, khối lượng, giá trị giao dịch, thông tin tham chiếu mã và trạng thái thị trường.Trường hợp sử dụng phổ biến
- Hiển thị giá realtime
- Báo giá cho ticket đặt lệnh
- Theo dõi danh sách quan tâm
- Biểu đồ và tổng hợp thị trường
- Dashboard báo cáo cho khách hàng
Tình huống thực tế
Một ứng dụng quản lý tài sản hiển thị giá cổ phiếu để người dùng quyết định thời điểm mua. Một công cụ nghiên cứu hiển thị snapshot thị trường cho chuyên viên phân tích. Một nhân viên hỗ trợ chi nhánh kiểm tra báo giá khi đang trao đổi với khách hàng.Hướng dẫn từng bước
1
Xác thực
Xác thực ứng dụng của bạn.
2
Chọn endpoint
Chọn endpoint market data phù hợp.
3
Gửi request
Gửi request với token hợp lệ.
4
Hiển thị phản hồi
Hiển thị phản hồi theo cách dễ hiểu.
5
Làm mới dữ liệu
Làm mới dữ liệu theo nhu cầu ứng dụng và giới hạn rate limit.
Ví dụ minh họa: Người dùng mở trang chi tiết một mã cổ phiếu. Ứng dụng gọi Market Data APIs, lấy giá mới nhất và chênh lệch giá, rồi hiển thị tóm tắt kèm biểu đồ và chỉ báo biến động.
5. API tài khoản và danh mục
Thông tin tài khoản
Thông tin tài khoản có thể bao gồm số tài khoản, loại tài khoản, loại tiền, số dư tiền mặt, sức mua và trạng thái tài khoản.Thông tin tài sản
Thông tin tài sản có thể bao gồm mã chứng khoán, symbol, tên, sàn giao dịch và các chi tiết định giá hiện tại.Thông tin vị thế
Thông tin vị thế thường hiển thị số lượng, giá vốn trung bình, giá trị thị trường, lãi/lỗ chưa thực hiện và số lượng khả dụng.Theo dõi danh mục
Theo dõi danh mục giúp người dùng theo dõi mức độ phân bổ, tập trung tỷ trọng, hiệu suất và các thay đổi theo thời gian.Hướng dẫn từng bước
1
Xác thực phiên
Xác thực phiên của người dùng.
2
Gọi endpoint tài khoản
Gọi endpoint thông tin tài khoản.
3
Lấy dữ liệu tài sản
Lấy dữ liệu tài sản và vị thế.
4
Tóm tắt trong portfolio
Tóm tắt thông tin trong màn hình portfolio.
5
Làm mới định kỳ
Làm mới dữ liệu thường xuyên để đảm bảo theo dõi chính xác.
Ví dụ minh họa: Một nhà đầu tư mở ứng dụng và thấy bản tóm tắt danh mục. Hệ thống lấy chi tiết tài khoản, danh mục đang nắm giữ và giá trị vị thế để nhà đầu tư có thể xem nhanh khoản đầu tư của mình.
6. API giao dịch
Đặt lệnh
Một request đặt lệnh sẽ bắt đầu một giao dịch mới. Ứng dụng nên kiểm tra mã chứng khoán, số lượng, chiều lệnh và loại sản phẩm trước khi gửi.Sửa lệnh
Một request sửa lệnh sẽ cập nhật lệnh hiện có, chẳng hạn thay đổi giá hoặc số lượng, nếu lệnh đó vẫn còn đủ điều kiện sửa.Hủy lệnh
Một request hủy lệnh sẽ xóa một lệnh đang mở nếu lệnh đó chưa được khớp hoàn toàn.Theo dõi trạng thái lệnh
Theo dõi trạng thái lệnh giúp người dùng xem tiến trình của lệnh qua các trạng thái như pending, accepted, partially filled, filled, canceled hoặc rejected.Hướng dẫn từng bước
1
Xác nhận quyền giao dịch
Xác thực và xác nhận quyền giao dịch.
2
Tạo request lệnh
Tạo request lệnh với mã, số lượng và loại giá phù hợp.
3
Gửi lệnh
Gửi lệnh.
4
Lưu mã tham chiếu
Lưu phản hồi hoặc mã tham chiếu của lệnh.
5
Kiểm tra trạng thái
Kiểm tra trạng thái cho đến khi lệnh được khớp, bị từ chối, bị hủy hoặc hết hạn.
Ví dụ minh họa: Một khách hàng muốn mua cổ phiếu của một công ty. Ứng dụng gửi request đặt lệnh, hiển thị phản hồi, rồi cập nhật màn hình lệnh cho đến khi lệnh hoàn tất.
7. Ví dụ quy trình API phổ biến
Đăng nhập → Lấy dữ liệu thị trường → Đặt lệnh
1
Xác thực người dùng
2
Lấy giá thị trường mới nhất
3
Hiển thị báo giá trong ticket đặt lệnh
4
Gửi lệnh mua hoặc bán
5
Theo dõi phản hồi và trạng thái lệnh
Đăng nhập → Lấy danh mục → Theo dõi vị thế
1
Xác thực người dùng
2
Lấy chi tiết tài khoản
3
Tải danh mục hiện tại và giá trị tài sản
4
Hiển thị portfolio dashboard
5
Làm mới dữ liệu để theo dõi thay đổi theo thời gian
Ví dụ minh họa: Một ứng dụng giao dịch trên mobile sử dụng quy trình đầu tiên cho giao dịch chủ động và quy trình thứ hai cho việc xem danh mục hằng ngày.
8. Giới hạn API và thực hành tốt nhất
Giới hạn số lượng request
Rate limits kiểm soát số lượng request mà ứng dụng của bạn có thể gửi trong một khoảng thời gian nhất định. Chúng giúp bảo vệ hệ thống và duy trì sự ổn định của dịch vụ.Khuyến nghị bảo mật
- Giữ bí mật thông tin xác thực
- Dùng đúng môi trường
- Lưu access token an toàn
- Loại bỏ quyền không cần thiết
- Ghi log lỗi nhưng không để lộ dữ liệu nhạy cảm
Hướng dẫn xử lý lỗi
Kiểm tra thông báo lỗi, xác nhận token, rà soát quyền truy cập và chỉ thử lại khi lỗi là tạm thời và an toàn để retry.Hướng dẫn từng bước
1
Theo dõi tần suất request
2
Dùng đúng quy trình xác thực
3
Chỉ retry khi lỗi là tạm thời
4
Tránh để lộ bí mật trong log hoặc trên màn hình
5
Xác thực dữ liệu giao dịch trước khi gửi request
Ví dụ minh họa: Một ứng dụng gửi quá nhiều request báo giá và chạm giới hạn. Hệ thống giảm tốc độ request và dùng cache để người dùng vẫn có thể tiếp tục làm việc mượt mà.
9. Câu hỏi thường gặp
Nhóm vấn đề chung
Vấn đề đăng ký
Vấn đề đăng ký
Kiểm tra xem thông tin doanh nghiệp, thông tin liên hệ và các tài liệu phê duyệt đã được gửi đúng chưa.
Vấn đề xác thực
Vấn đề xác thực
Xác nhận thông tin đăng nhập chính xác, token còn hiệu lực và ứng dụng đang gọi đúng môi trường.
Quyền giao dịch
Quyền giao dịch
Hãy chắc chắn rằng quyền giao dịch đã được phê duyệt cho tài khoản bạn đang dùng.
Truy cập môi trường
Truy cập môi trường
Kiểm tra rằng bạn đang dùng sandbox credentials trong sandbox và production credentials trong production.
Câu hỏi cụ thể
Tôi không thể đăng ký. Tôi nên kiểm tra gì đầu tiên?
Tôi không thể đăng ký. Tôi nên kiểm tra gì đầu tiên?
Xác minh thông tin tài khoản, thông tin công ty và các tài liệu phê duyệt bắt buộc.
Vì sao tôi gặp lỗi xác thực?
Vì sao tôi gặp lỗi xác thực?
Nguyên nhân phổ biến là token hết hạn, thông tin đăng nhập sai hoặc đang dùng sai môi trường.
Vì sao tôi xem được dữ liệu nhưng không đặt lệnh được?
Vì sao tôi xem được dữ liệu nhưng không đặt lệnh được?
Bạn có thể chỉ đang có quyền xem market data hoặc account. Có thể chưa được cấp quyền giao dịch.
Vì sao sandbox chạy được nhưng production lại lỗi?
Vì sao sandbox chạy được nhưng production lại lỗi?
Production thường có các kiểm soát nghiêm ngặt hơn về quyền, thông tin đăng nhập và tuân thủ.