Thuật ngữ chuẩn
Bảng thuật ngữ chuẩn của HiTechCloud Developers: endpoint, webhook, xác thực, khoá API, access token, giới hạn tần suất, phân trang, chữ ký, sandbox và giao dịch.
Tài liệu HiTechCloud dùng một bộ thuật ngữ thống nhất cho mọi sản phẩm. Một số từ tiếng Anh đã phổ biến với lập trình viên thì giữ nguyên (vd endpoint, webhook, token); phần còn lại dùng thuật ngữ tiếng Việt chuẩn dưới đây.
Giao thức & Yêu cầu
| Thuật ngữ | Tiếng Anh | Quy ước dùng |
|---|---|---|
| endpoint | endpoint | Giữ nguyên endpoint — một đường dẫn API cụ thể (vd GET /v1/orders). |
| yêu cầu | request | yêu cầu cho request; phản hồi cho response. |
| phản hồi | response | Nội dung máy chủ trả về. |
| tham số đường dẫn | path parameter | Biến trong đường dẫn, vd {id}. |
| tham số truy vấn | query parameter | Tham số sau dấu ?, vd ?page=2. |
| thân yêu cầu | request body | Dữ liệu gửi kèm (thường JSON). |
| header | header | Giữ nguyên header. |
| khung phản hồi | response envelope | Cấu trúc bọc ngoài: status / data / meta. |
| phân trang | pagination | page / per_page và meta.pagination. |
| giới hạn tần suất | rate limit | Số yêu cầu tối đa trong một khoảng thời gian. |
| idempotency | idempotency | Tính bất biến khi lặp — gửi lại cùng yêu cầu không tạo thêm bản ghi. |
Xác thực & Bảo mật
| Thuật ngữ | Tiếng Anh | Quy ước dùng |
|---|---|---|
| xác thực | authentication | Xác minh danh tính (đăng nhập, khoá API). |
| phân quyền | authorization | Cấp quyền truy cập tài nguyên. |
| khoá API | API key | khoá API — gửi qua header X-API-Key. |
| access token | access token | Token truy cập, gửi qua Authorization: Bearer .... |
| phạm vi | scope | phạm vi (scope) — quyền giới hạn của một khoá/token. |
| chữ ký | signature | Chữ ký HMAC/JWS để xác minh webhook hoặc yêu cầu. |
| webhook | webhook | Giữ nguyên webhook — HiTechCloud gọi ngược về URL của bạn. |
| callback | callback | URL nhận kết quả sau một hành động. |
| danh sách IP cho phép | IP allowlist | Giới hạn IP được gọi API. |
Môi trường & Giao dịch
| Thuật ngữ | Tiếng Anh | Quy ước dùng |
|---|---|---|
| môi trường thử nghiệm | sandbox | môi trường thử nghiệm (sandbox) — dữ liệu giả, không tính tiền thật. |
| môi trường thật | production | môi trường thật (production) — dữ liệu và giao dịch thật. |
| trạng thái | status / state | Trạng thái của bản ghi hoặc giao dịch. |
| giao dịch | transaction | Một lần thanh toán/thao tác tài chính. |
| đơn vị bán | merchant | đơn vị bán (merchant) — bên nhận thanh toán. |
| cổng thanh toán | payment gateway | Lớp trung gian xử lý thanh toán. |
| SDK | SDK | Bộ thư viện mẫu theo ngôn ngữ. |
| OAuth2 / OIDC | OAuth2 / OpenID Connect | Giữ nguyên — chuẩn uỷ quyền / định danh. |
Nếu một trang dùng từ khác với bảng này, bảng này là chuẩn. Thông báo cho đội tài liệu để đồng bộ.