Khóa API

Khóa API mở quyền truy cập lập trình vào dAio Business. Chúng cho phép các ứng dụng, tập lệnh và hệ thống của riêng bạn truy vấn trực tiếp nền tảng — dữ liệu thời tiết, chất lượng không khí, phấn hoa, điều kiện hàng hải, trí tuệ theo ngành — mà không cần thông qua giao diện web. Đây là điểm khởi đầu để công nghiệp hóa các tích hợp của bạn: cấp dữ liệu cho một hệ thống ERP, kích hoạt một quy trình nghiệp vụ, hiển thị dự báo trên bảng điều khiển của riêng bạn.

Mỗi khóa xác thực các lệnh gọi nhân danh tổ chức của bạn và kế thừa các quyền của tổ chức. Kết hợp với webhook, khóa mang lại cho bạn một kênh hoàn chỉnh: bạn truy vấn dAio theo yêu cầu qua API, và dAio thông báo cho bạn theo thời gian thực qua webhook.

Mẹo: hãy tạo một khóa riêng cho từng mục đích sử dụng (một dịch vụ, một môi trường, một đối tác). Bạn sẽ có thể thu hồi một khóa mà không làm gián đoạn các khóa khác, và theo dõi chính xác tích hợp nào tiêu thụ cái gì.

Khóa API dùng để làm gì

Nhu cầu	Khóa API cho phép…
Tích hợp	Kết nối dAio với hệ thống thông tin của bạn (ERP, GMAO, BI) mà không cần can thiệp thủ công.
Tự động hóa	Khởi chạy các quy trình theo lịch (lấy dự báo hằng ngày, chấm điểm rủi ro).
Phân phối	Hiển thị dữ liệu dAio trong các ứng dụng hoặc cổng thông tin của riêng bạn.
Chia sẻ có kiểm soát	Cấp cho một đối tác quyền truy cập giới hạn và có thể thu hồi, mà không cần tạo tài khoản người dùng.

Thông tin: quyền truy cập API chỉ dành cho các gói trả phí. Một tổ chức không có gói đăng ký đang hoạt động sẽ nhận được phản hồi 403 (« API access requires a paid plan ») trên mỗi lệnh gọi.

Tạo khóa

Việc tạo khóa chỉ dành cho chủ sở hữu (owner) và quản trị viên (admin) của tổ chức. Các vai trò khác không thể tạo hoặc thu hồi khóa.

1. Truy cập Cài đặt > Khóa API.
2. Nhấp vào Khóa mới ở góc trên bên phải.
3. Nhập một tên mô tả xác định mục đích sử dụng của khóa (ví dụ « Backend production », « Bộ kết nối Power BI », « Tích hợp đối tác X »).
4. Nhấp vào Tạo.
5. Khóa đầy đủ hiển thị trong một dải màu xanh lá: sao chép ngay lập tức bằng nút sao chép.

Lưu ý: khóa đầy đủ chỉ hiển thị một lần duy nhất, vào thời điểm tạo. Sau đó nó không bao giờ được hiển thị lại — nền tảng chỉ lưu giữ một dấu vân tay đã mã hóa của nó. Nếu bạn làm mất, bạn sẽ phải tạo một khóa mới. Hãy lưu trữ nó ngay lập tức trong một trình quản lý bí mật (Vault, AWS Secrets Manager, biến môi trường đã mã hóa).

Sau khi được tạo, khóa xuất hiện trong danh sách cùng với tên, tiền tố (vài ký tự đầu, để nhận diện mà không tiết lộ), một chỉ báo trạng thái (xanh lá = đang hoạt động, đỏ = đã thu hồi) và ngày sử dụng gần nhất.

Sử dụng khóa

Mọi yêu cầu gửi đến dAio API phải bao gồm khóa của bạn trong tiêu đề HTTP X-API-Key. Địa chỉ cơ sở của API là https://api-dev.daio.app, và các điểm truy cập B2B được thêm tiền tố /api/v1/.

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

Lưu ý: tiêu đề được mong đợi chính là X-API-Key, chứ không phải Authorization: Bearer. Một khóa không hợp lệ, đã bị thu hồi hoặc được truyền trong một tiêu đề khác sẽ trả về phản hồi 401 (« Invalid API key »).

Hãy tham khảo tài liệu kỹ thuật của API để biết danh sách đầy đủ các điểm truy cập (thời tiết, dự báo theo giờ, chất lượng không khí, phấn hoa, hàng hải, xử lý theo lô) và định dạng phản hồi.

Giới hạn tốc độ

Để đảm bảo dịch vụ ổn định, mỗi khóa đều chịu một giới hạn tốc độ theo giờ. Bộ đếm là riêng của từng khóa và được đặt lại sau mỗi giờ.

Gói	Số yêu cầu mỗi giờ
Free / no subscription	Không có quyền truy cập API
Solo · Team · Enterprise (dAio Business)	20 000

Khi đạt đến giới hạn, API trả về phản hồi 429 (« Rate limit exceeded ») kèm theo một tiêu đề Retry-After cho biết thời gian chờ trước khi thử lại.

Thông tin: giới hạn theo giờ này khác với hạn ngạch yêu cầu hằng tháng đã bao gồm trong gói của bạn. Hãy xem chi tiết hạn ngạch theo từng gói trong phần Gói đăng ký.

Xoay vòng khóa

Xoay vòng tái tạo một khóa nhưng vẫn giữ nguyên tên và vị trí của nó trong danh sách. Hãy dùng nó để định kỳ làm mới các bí mật mà không cần cấu hình lại toàn bộ tích hợp.

1. Trong danh sách, nhấp vào biểu tượng xoay vòng (mũi tên vòng tròn) bên cạnh khóa.
2. Xác nhận thao tác.
3. Giá trị mới hiển thị một lần duy nhất — sao chép ngay lập tức.
4. Cập nhật các ứng dụng của bạn với giá trị mới này.

Mẹo: hãy lên lịch xoay vòng mỗi 90 ngày, và một cách hệ thống sau khi một nhân viên từng có quyền truy cập các bí mật rời đi hoặc khi nghi ngờ có rò rỉ.

Thu hồi khóa

Để cắt quyền truy cập của một khóa bị xâm phạm hoặc không còn dùng:

1. Trong danh sách, nhấp vào biểu tượng xóa (thùng rác) bên cạnh khóa.
2. Xác nhận việc thu hồi.

Việc thu hồi có hiệu lực ngay lập tức và không thể đảo ngược. Mọi yêu cầu sử dụng khóa đã thu hồi sẽ lập tức nhận được phản hồi 401. Khóa vẫn hiển thị trong danh sách, được đánh dấu Đã thu hồi, để lưu lịch sử.

Bảo mật khóa

Một khóa API tương đương với một mật khẩu: bất kỳ ai nắm giữ nó đều có thể truy vấn API với các quyền của tổ chức bạn.

Lưu ý: tuyệt đối không bao giờ commit một khóa vào mã nguồn hoặc một kho lưu trữ Git, kể cả kho riêng tư. Một khóa bị đẩy nhầm lên một kho lưu trữ được coi là đã bị xâm phạm — hãy thu hồi và xoay vòng nó ngay không chậm trễ. Đừng bao giờ truyền nó qua e-mail, ứng dụng nhắn tin hoặc phiếu hỗ trợ ở dạng văn bản rõ.

• Lưu trữ các khóa trong một trình quản lý bí mật hoặc các biến môi trường, không bao giờ ghi cứng trong mã.
• Không để lộ chúng ở phía máy khách (ứng dụng web, di động, JavaScript trình duyệt): một lệnh gọi API phải xuất phát từ máy chủ của bạn.
• Phân tách: một khóa cho mỗi môi trường (sản xuất, kiểm thử) và mỗi mục đích sử dụng.
• Giám sát ngày sử dụng gần nhất: một khóa không hoạt động đã lâu là một khóa cần thu hồi.

Thực hành tốt

• Đặt tên rõ ràng cho từng khóa theo mục đích sử dụng và môi trường của nó để nhận biết ngay khóa đó cấp dữ liệu cho cái gì.
• Áp dụng đặc quyền tối thiểu: hãy tạo các khóa chuyên dụng và có thể thu hồi thay vì một khóa duy nhất dùng chung cho mọi tích hợp.
• Tự động hóa việc xoay vòng mỗi 90 ngày và tích hợp nó vào quy trình khi nhân viên nghỉ việc.
• Xử lý các lỗi 429 ở phía máy khách: tuân thủ tiêu đề Retry-After và dàn đều các lệnh gọi thay vì gửi liên tiếp các yêu cầu.
• Thu hồi ngay lập tức bất kỳ khóa nào bị nghi ngờ đã bị xâm phạm — việc thu hồi có hiệu lực không chậm trễ.
• Lập tài liệu nội bộ về khóa nào dùng vào việc gì và ai chịu trách nhiệm về nó, để các cuộc kiểm toán an ninh diễn ra suôn sẻ.

Mẹo: hãy kết hợp các khóa API của bạn với webhook để có một tích hợp hoàn chỉnh — truy vấn dAio theo yêu cầu, và để dAio thông báo cho bạn về các sự kiện theo thời gian thực.