Tài liệu API dữ liệu
taichinh.com mở một số điểm truy cập JSON trên cùng bộ dữ liệu với trang web: ba feed mở phục vụ nhúng và trích dẫn, và các endpoint mở rộng dùng khoá x-api-key do quản trị viên cấp. Mỗi con số trong phản hồi kèm nguồn công bố và thời điểm ghi nhận.
Feed mở
Ba feed dưới đây không cần khoá, phục vụ nhúng và trích dẫn. Chúng giữ nguyên cấu trúc đã công bố; xem thêm widget nhúng nếu bạn chỉ cần bảng giá hiển thị sẵn.
| Đường dẫn | Nội dung | Tham số | Nhịp cập nhật | Cache |
|---|---|---|---|---|
/api/v1/gold | Giá vàng miếng SJC theo thương hiệu, kèm giá vàng thế giới | Không có | Nhiều lần trong ngày theo bảng giá doanh nghiệp | Cache chung 4 phút |
/api/v1/fx | Tỷ giá ngoại tệ: mua tiền mặt, mua chuyển khoản, bán ra; kèm tỷ giá trung tâm | Không có | Trong ngày theo bảng niêm yết của ngân hàng | Cache chung 30 phút |
/api/v1/rates | Mức lãi suất tiết kiệm phù hợp điều kiện, theo ngân hàng và kỳ hạn | amount (tuỳ chọn) - số tiền gửi bằng đồng nguyên | Theo biểu lãi suất từng ngân hàng công bố | Cache chung 1 giờ; có tham số thì không cache chung |
Endpoint mở rộng, cần khoá x-api-key
Mọi endpoint dưới đây yêu cầu header x-api-key hợp lệ trong từng request. Thiếu khoá hoặc khoá đã thu hồi: trả 401. Vượt hạn mức gọi trong phút của khoá: trả 429. Tham số ngoài danh sách của từng endpoint bị từ chối với mã 400. Gọi thẳng từ trình duyệt được: khoá nằm trong header, không nằm trong cookie, và các endpoint trả CORS mở.
| Đường dẫn | Nội dung | Tham số | Nhịp cập nhật | Cache |
|---|---|---|---|---|
/api/v1/tax/tncn | Tính thuế thu nhập cá nhân từ tiền lương, theo biểu luỹ tiến và giảm trừ đang áp dụng, kèm kỳ hiệu lực và văn bản gốc | thu_nhap (bắt buộc) - đồng mỗi tháng; nguoi_phu_thuoc (tuỳ chọn) - số nguyên 0 đến 20 | Theo văn bản pháp luật | Không cache; kết quả riêng theo tham số |
/api/v1/fuel | Giá bán lẻ xăng dầu vùng 1 và vùng 2, kỳ điều hành mới nhất và kỳ liền trước | Không có | Theo kỳ điều hành, thường 7 ngày một kỳ | Cache chung 1 giờ |
/api/v1/gold/history | Chuỗi giá bán vàng miếng SJC dài hạn: điểm ngày cho 24 tháng gần, điểm tuần cho phần cũ hơn | Không có | Bổ sung điểm mới trong ngày; số liệu quá khứ giữ nguyên | Cache chung 1 giờ |
/api/v1/macro | Chỉ tiêu vĩ mô Việt Nam: bảng chỉ tiêu theo năm và CPI theo tháng | Không có | Theo kỳ công bố tháng và năm của nguồn | Cache chung 1 ngày |
/api/v1/glossary/{slug} | Nội dung một thuật ngữ tài chính đã xuất bản: định nghĩa, công thức, thuật ngữ liên quan | slug nằm trong đường dẫn; slug lạ trả 404 | Khi nội dung biên tập thay đổi | Cache chung 1 ngày |
Xin khoá
Khoá do quản trị viên taichinh.com cấp. Gửi đề nghị tới [email protected], nêu tên ứng dụng và mục đích sử dụng dữ liệu. Khoá hạng đọc bắt đầu bằng tc_doc_ và chỉ hiển thị đúng một lần lúc cấp: hệ thống lưu bản băm thay cho khoá gốc, nên không tra lại được khoá đã mất; khi đó đề nghị cấp khoá mới. Mỗi khoá có hạn mức gọi theo phút; khoá dùng sai điều khoản có thể bị thu hồi và trả 401 từ request kế tiếp.
Gửi khoá qua header x-api-key, ví dụ với khoá giả định:
curl -H "x-api-key: tc_doc_vi_du_0123456789abcdef" \ "https://taichinh.com/api/v1/fuel"
Điều khoản
- Dẫn nguồn khi hiển thị lại. Mỗi con số trong payload kèm khối nguồn công bố và thời điểm ghi nhận. Khi hiển thị lại cho người đọc của bạn, nêu nguồn công bố gốc và thời điểm đó; có thể ghi thêm "truy cập qua taichinh.com". taichinh.com không cấp thêm quyền đối với dữ liệu của bên thứ ba - xem nguyên tắc trích dẫn.
- Hợp đồng v1. Trong cùng phiên bản, thay đổi duy nhất là thêm trường mới; trường hiện có không đổi tên, không đổi kiểu, không đổi nghĩa. Bên gọi đọc theo tên trường và bỏ qua trường chưa biết.
- Phạm vi sử dụng. Số liệu dùng để tham khảo và đối chiếu, không phải khuyến nghị đầu tư. Quy định đầy đủ tại Quy định sử dụng.