Chào mừng bạn đến với tài liệu hướng dẫn tích hợp API của Vietstats – nền tảng dữ liệu kinh tế, xã hội và thị trường được thiết kế để hỗ trợ doanh nghiệp ra quyết định nhanh chóng và chính xác hơn. Tài liệu này cung cấp hướng dẫn chi tiết giúp bạn dễ dàng tích hợp các API của Vietstats vào hệ thống của mình. Bao gồm:
- Tổng quan về hệ thống API
- Hướng dẫn xác thực và kết nối
- Mô tả chi tiết các endpoint và tham số
- Ví dụ request/response thực tế
- Các lưu ý về bảo mật và xử lý lỗi
Hệ thống API của Vietstats được xây dựng nhằm cung cấp quyền truy cập linh hoạt và bảo mật vào kho dữ liệu kinh tế – xã hội – thị trường được chuẩn hóa và cập nhật liên tục. Thông qua API, doanh nghiệp và nhà phát triển có thể tích hợp dữ liệu trực tiếp vào hệ thống nội bộ, ứng dụng web hoặc các nền tảng phân tích một cách nhanh chóng và hiệu quả
** NOTE: Nếu bạn cần hỗ trợ thêm trong quá trình tích hợp, vui lòng liên hệ đội ngũ kỹ thuật của Vietstats qua email: support@Vietstats.vn
- Tự động hóa quá trình truy xuất và cập nhật dữ liệu.
- Tiết kiệm thời gian cho các tác vụ thu thập và xử lý dữ liệu thủ công.
- Tăng khả năng mở rộng cho các sản phẩm sử dụng dữ liệu kinh tế – xã hội.
Hệ thống API Vietstats tuân thủ chuẩn RESTful, với phương thức giao tiếp chủ yếu là HTTP/HTTPS, sử dụng định dạng dữ liệu JSON cho cả request và response.
| Thành phần | Mô tả |
|---|---|
| Base URL | Được cung cấp khi đăng kí tích hợp |
| Method | GET |
| Format | Application/json |
| Authentication | API key (Được cấp riêng khi mua gói dịch vụ) |
Tất cả các request phải được xác thực bằng API Key đi kèm trong phần headers. Ngoài ra, hệ thống cũng hỗ trợ giới hạn tốc độ truy cập (rate limiting) để đảm bảo tính ổn định và công bằng giữa các bên sử dụng.
- Nhanh chóng, ổn định, dễ mở rộng.
- Tài liệu rõ ràng, có ví dụ mẫu.
- Được hỗ trợ trực tiếp bởi đội ngũ kỹ thuật Vietstats.
Sau khi đăng ký mua gói dịch vụ có tính năng tích hợp API, bạn sẽ được Vietstats cấp một API Key. Mỗi API Key gắn liền với thông tin tài khoản, giới hạn truy cập, thời gian sử dụng và quyền sử dụng dữ liệu
Khi gửi request đến API, bạn cần đính kèm API Key trong phần headers của HTTP request như sau:
http
Content-Type: application/json
x-api-key: your_api_key_here{BaseURL}/{endpoint}
- Không chia sẻ API Key công khai (đặc biệt trên frontend hoặc GitHub).
- Có thể yêu cầu cấp lại hoặc thu hồi nếu bị lộ.
- Một số hệ thống hỗ trợ tạo nhiều API Key để phân quyền theo từng dịch vụ hoặc môi trường (dev, staging, production).
bash
curl -X GET "{BaseURL}/{endpoint}?id=G00101&is_structure=1&is_object_one_time=0&type=bar&page_size=10&page_limit=1" -H "x-api-key: your_api_key_here"| No | Fields name | Description |
|---|---|---|
| 01 | id | Id của chỉ số muốn gắn API. Được cung cấp khi đăng ký tích hợp API qua email |
| 02 | is_structure | Loại chỉ số, được cung cấp khi đăng ký tích hợp thông qua email |
| 03 | is_object_one_time | Loại chỉ số, được cung cấp khi đăng ký tích hợp thông qua email |
| 04 | type | Loại chỉ số, được cung cấp khi đăng ký tích hợp thông qua email |
| 05 | page_size | Vị trí bắt đầu của giá trị muốn trả về, bắt đầu là 1. Mặc định nếu không truyền sẽ trả về toàn bộ. |
| 06 | page_limit | Số lượng giá trị muốn trả về 1 lần gọi. Mặc định không truyền vào sẽ trả về toàn bộ |
{BaseURL}/{endpoint}
| No | Field name | Type | Required | Description |
|---|---|---|---|---|
| 1 | id | string | ● | ID của chỉ số đang gọi |
| 2 | name | string | ● | Tên của chỉ số |
| 3 | unit | string | ● | Đơn vị tính của chỉ số |
| 4 | original | string | ● | Nguồn dữ liệu |
| 5 | note | string | ● | Ghi chú |
| 6 | summary | string | ● | Tổng quan chỉ số |
| 7 | dataType | string | ● | Loại dữ liệu: [day, month, quarter, year] |
| 8 | values | Array<Object> | Dữ liệu của chỉ số. Nếu is_structure = 0, is_object_one_time=0 | |
| 9 | year | string | Năm tổng hợp dữ liệu | |
| 10 | quarter | string | Quý tổng hợp dữ liệu | |
| 11 | month | string | Tháng tổng hợp dữ liệu | |
| 12 | day | string | Ngày tổng hợp dữ liệu | |
| 13 | value | string | Giá trị của chỉ số | |
| 14 | children | Array<Object> | Chỉ số con, chứa dữ liệu để làm rõ chỉ số cha. Nếu is_structure = 1, is_object_one_time=0 | |
| 15 | name | string | Tên của chỉ số con | |
| 16 | unit | string | Đơn vị tính của chỉ số con | |
| 17 | original | string | Nguồn dữ liệu | |
| 18 | note | string | Ghi chú | |
| 19 | summary | string | Tổng quan chỉ số con | |
| 20 | dataType | string | Loại dữ liệu: [day, month, quarter, year] | |
| 21 | values | Array<Object> | Dữ liệu của chỉ số con | |
| 22 | year | string | Năm tổng hợp dữ liệu | |
| 23 | quarter | string | Quý tổng hợp dữ liệu | |
| 24 | month | string | Tháng tổng hợp dữ liệu | |
| 25 | day | string | Ngày tổng hợp dữ liệu | |
| 26 | value | string | Giá trị của chỉ số con | |
| 27 | children | Array<Object> | Chỉ số làm rõ dữ liệu. Nếu is_structure = 0, is_object_one_time=1 | |
| 28 | name | string | Tên của chỉ số | |
| 29 | unit | string | Đơn vị tính của chỉ số | |
| 30 | original | string | Nguồn dữ liệu | |
| 31 | note | string | Ghi chú | |
| 32 | summary | string | Tổng quan chỉ số | |
| 33 | dataType | string | Loại dữ liệu: [day, month, quarter, year] | |
| 34 | child | Array<Object> | Chỉ số làm rõ dữ liệu | |
| 35 | name | string | Tên của chỉ số | |
| 36 | unit | string | Đơn vị tính của chỉ số | |
| 37 | original | string | Nguồn dữ liệu | |
| 38 | note | string | Ghi chú | |
| 39 | summary | string | Tổng quan chỉ số | |
| 40 | dataType | string | Loại dữ liệu: [day, month, quarter, year] | |
| 41 | values | Array<Object> | Dữ liệu của chỉ số | |
| 42 | year | string | Năm tổng hợp dữ liệu | |
| 43 | quarter | string | Quý tổng hợp dữ liệu | |
| 44 | month | string | Tháng tổng hợp dữ liệu | |
| 45 | day | string | Ngày tổng hợp dữ liệu | |
| 46 | value | string | Giá trị của chỉ số |
| Mã lỗi | Ý nghĩa | Gợi ý xử lý |
|---|---|---|
| 400 Bad Request | Tham số không hợp lệ | Kiểm tra lại định dạng, kiểu dữ liệu và giá trị các tham số truyền vào. |
| 401 Unauthorized | Thiếu hoặc sai API key | Thêm hoặc kiểm tra lại google-api-key trong header. |
| 403 Forbidden | Không có quyền truy cập | Kiểm tra quyền truy cập với Vietstats. Có thể API key bị giới hạn quyền. |
| 404 Not Found | Endpoint hoặc ID không tồn tại | Kiểm tra lại URL hoặc tham số ID. |
| 429 Too Many Requests | Gọi API quá giới hạn | Chờ một khoảng thời gian rồi gọi lại. Có thể cần gọi thêm để gói API. |
| 500 Internal Server Error | Lỗi hệ thống | Thử lại sau hoặc liên hệ với đội kỹ thuật Vietstats. |
Chúng tôi tin rằng dữ liệu không chỉ là những con số – mà là nền tảng để đưa ra quyết định đúng đắn, tạo nên giá trị và thúc đẩy sự phát triển bền vững. Với hệ thống API của Vietstats, bạn đang nắm trong tay một công cụ mạnh mẽ để tiếp cận, khai thác và ứng dụng dữ liệu một cách linh hoạt và hiệu quả. Tài liệu này được xây dựng nhằm đồng hành cùng bạn trong quá trình tích hợp, giúp đơn giản hóa các bước kỹ thuật và tối ưu thời gian triển khai. Chúng tôi luôn sẵn sàng hỗ trợ khi bạn cần – vì sự thành công của bạn cũng chính là mục tiêu mà Vietstats hướng đến. Nếu có bất kỳ thắc mắc, góp ý hoặc nhu cầu tùy biến nâng cao, đừng ngần ngại liên hệ với đội ngũ kỹ thuật của chúng tôi. Cảm ơn bạn đã lựa chọn Vietstats làm đối tác dữ liệu đáng tin cậy.