API Reference

REST API v1 đầy đủ cho tích hợp ngoài. Spec OpenAPI 3.1, xác thực Bearer token (Personal Access Token).

Quyền truy cập: Owner / Admin / user có quyền API_TOKEN_CREATEĐiều hướng:

Cấu hình & tạo token: Cài đặt > Quản lý dịch vụ > Kết nối API
Tài liệu Swagger UI live: https://<customer-domain>/manage/api/v1/docs
OpenAPI Spec JSON: https://<customer-domain>/manage/api/v1/openapi.json

Truy cập tài liệu API

Mỗi khách hàng có URL Swagger riêng theo domain của tenant. Thay <customer-domain> bằng domain thực tế của tổ chức:

https://acme.noova.io/manage/api/v1/docs        ← khách hàng "acme"
https://hr.example.com/manage/api/v1/docs       ← khách hàng custom domain
https://demo.noova.io/manage/api/v1/docs        ← demo

Trang hướng dẫn API hỗ trợ:

Xem chi tiết từng endpoint (method, path, params, request body, response codes)
Thử request trực tiếp (Try it out) với PAT đã nhập
Generate cURL / fetch / axios snippet
Download spec OpenAPI JSON
Filter theo tag (Nhân sự / Khoá học / Lương / ...)

Lưu ý: Trang /manage/api/v1/docs chỉ khả dụng khi đã bật Mở kết nối API (eweb.allowOpenAPI === true) trong Cài đặt > Quản lý dịch vụ > Kết nối API. Nếu chưa bật, browser sẽ trả về 404 / 503.

Xác thực

Personal Access Token (PAT)

Mọi request cần header:

http

Authorization: Bearer <YOUR_PAT>

Cách lấy PAT:

Vào Cài đặt > Quản lý dịch vụ > Kết nối API
Bật Mở kết nối API (nếu chưa bật)
Nhấp Tạo API Token
Copy token và lưu nơi an toàn - chỉ hiển thị 1 lần

PAT có scope = scope của user sở hữu (cùng vai trò, cùng phạm vi qua Permission Scope Engine).

Thu hồi PAT

Vào lại trang Kết nối API, nhấp Reset token mới để vô hiệu hoá token cũ và sinh token mới.

Cấu trúc API

API tổ chức theo 56 tag (module). Mỗi tag là một nhóm endpoint thao tác trên một tài nguyên.

Nhóm Xác thực & danh tính

Tag	Mô tả
`Authentication`	Personal Access Token: tạo, liệt kê, thu hồi
`Users`	Quản lý tài khoản Meteor + thao tác admin (khoá, mở khoá, xác minh, đổi vai trò)
`User Groups`	Nhóm tài khoản
`Roles`	Vai trò + cấp quyền
`Policies`	Chính sách quyền có scope + gán cho user
`Login Tokens`	Admin tạo token đăng nhập cho user khác (impersonation deep link)

Nhóm Tổ chức

Tag	Mô tả
`Employees`	Danh bạ + xuất CSV + dòng thời gian + thao tác hàng loạt
`Employee Groups`	Nhóm hồ sơ nhân sự HR
`Positions`	Chức danh + bậc lương + yêu cầu năng lực/kỹ năng
`Position Groups`	Nhóm chức danh (job family)
`Org Units`	Cây tổ chức, ma trận, thành viên

Nhóm Đào tạo (LMS)

Tag	Mô tả
`Courses`	Khoá học
`Lessons`	Bài học
`Enrollments`	Ghi danh khoá học
`Quizzes`	Bài kiểm tra
`Surveys`	Khảo sát
`Certificates`	Chứng chỉ

Nhóm Chương trình đào tạo

Tag	Mô tả
`Training Programs`	Danh mục chương trình đào tạo
`Training Plans`	Kế hoạch đào tạo năm
`Training Needs`	Phân tích nhu cầu (TNA)
`Training Enrollments`	Ghi danh chương trình + nhóm học viên
`Training Calendar`	Lịch đào tạo + check khả dụng giảng viên
`Training Assessments`	Đánh giá trước/sau đào tạo
`Training Effectiveness`	Kirkpatrick L1-L4 reports
`Instructors`	Giảng viên / facilitator

Nhóm Hiệu suất & nhân tài

Tag	Mô tả
`Goals`	OKR / KPI / SMART
`Reviews`	Chu kỳ đánh giá hiệu suất
`Feedback`	Phản hồi 360° / liên tục
`Assessments`	Đánh giá năng lực (competency assessment)
`Competencies`	Khung năng lực
`Skill Evidence`	Bằng chứng kỹ năng
`Succession Planning`	Quy hoạch nhân sự kế thừa
`Career Pathing`	Lộ trình nghề nghiệp
`IDP`	Kế hoạch phát triển cá nhân

Nhóm Tuyển dụng

Tag	Mô tả
`Candidates`	Ứng viên
`Job Postings`	Tin tuyển dụng
`Interviews`	Phỏng vấn + nhận xét
`Applications`	Đơn ứng tuyển + chuyển trạng thái

Nhóm Vòng đời nhân sự

Tag	Mô tả
`Onboarding`	Quy trình nhận việc
`Offboarding`	Quy trình thôi việc

Nhóm Chấm công

Tag	Mô tả
`Time & Attendance`	Clock-in / clock-out
`Shifts`	Định nghĩa ca làm việc
`Shift Assignments`	Phân ca
`Holidays`	Lịch ngày lễ
`Overtime Requests`	Quy trình tăng ca
`Attendance Policies`	Chính sách chấm công
`Attendance Analytics`	Báo cáo & phân tích

Nhóm Lương thưởng

Tag	Mô tả
`Compensation & Payroll`	Lương + thưởng + phụ cấp + bảng lương

Nhóm Cuộc họp

Tag	Mô tả
`Meetings`	Quản lý cuộc họp
`Meeting Templates`	Mẫu cuộc họp tái sử dụng
`Meeting Series`	Cuộc họp định kỳ
`Meeting Minutes`	Biên bản + action items
`Meeting Analytics`	Báo cáo hiệu quả

Nhóm Gắn kết & cộng đồng

Tag	Mô tả
`Emulation`	Thi đua, ghi nhận, trao thưởng
`Engagement`	Khảo sát gắn kết (engagement pulse)
`Community`	Bài đăng, bình luận, sự kiện cộng đồng
`Announcements`	Thông báo nội bộ

Nhóm Tích hợp ngoài

Tag	Mô tả
`LDAP`	Trigger sync + check status

Pattern chung

Pagination

Endpoint danh sách trả về { data: [...], total, page, perPage }. Query params:

Param	Mặc định	Mô tả
`page`	1	Số trang (1-indexed)
`perPage`	50	Số bản ghi mỗi trang (max 200)
`sort`	`-createdAt`	Sort field, prefix `-` = descending

Filter

Endpoint danh sách hỗ trợ filter qua query string:

GET /api/v1/employees?orgUnitId=ABC&status=active&search=nguyen

Response codes

Code	Ý nghĩa
200	OK
201	Created
204	No Content (delete thành công)
400	Bad Request (validation lỗi)
401	Unauthorized (PAT sai/hết hạn)
403	Forbidden (không đủ quyền)
404	Not Found
409	Conflict (vd: trùng email)
422	Unprocessable Entity (business rule violation)
429	Too Many Requests (rate limit)
503	Service Unavailable (API bị disable)

Error response shape

json

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Employee email already exists",
  "code": "EMPLOYEE_EMAIL_DUPLICATE",
  "details": {
    "field": "email",
    "value": "duplicate@example.com"
  }
}

Timezone & dates

Mọi Date field trả về UTC ISO 8601 (vd: 2026-05-23T08:58:58.000Z). Khi gửi date input:

Date-only: "2026-05-23" (parse theo timezone tenant)
Date-time: "2026-05-23T08:58:58.000Z" (UTC instant)

Tenant timezone đọc qua GET /api/v1/users/me → field eweb.timezone.

Phụ thuộc Feature Toggle

Nhiều endpoint phụ thuộc vào việc tính năng tương ứng được bật trong Cài đặt > Quản lý dịch vụ > Tính năng. Ví dụ:

Endpoint	Phụ thuộc tính năng
`/api/v1/candidates/*`	`allowRecruitment`
`/api/v1/time-attendance/*`	`allowTimeAttendance`
`/api/v1/compensation-payroll/*`	`allowCompensation` + `allowPayroll`
`/api/v1/succession-planning/*`	`allowSuccession`
`/api/v1/community/*`	`allowCommunity`

Tính năng tắt → endpoint trả về 404 + bị ẩn khỏi /openapi.json filter.

Rate limit

Mặc định 120 request/phút/PAT. Vượt → 429. Header response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716800000

Phiên bản hoá

API v1 cam kết không thay đổi breaking trong cùng major version. Endpoint mới được thêm vào v1, endpoint cũ giữ nguyên contract. Breaking changes sẽ release dưới /api/v2/.

Ví dụ

Lấy danh sách nhân sự

bash

curl -X GET "https://acme.noova.io/manage/api/v1/employees?page=1&perPage=20" \
  -H "Authorization: Bearer noova_pat_xxx" \
  -H "Accept: application/json"

Tạo nhân sự mới

bash

curl -X POST "https://acme.noova.io/manage/api/v1/employees" \
  -H "Authorization: Bearer noova_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Nguyễn Văn A",
    "email": "nguyenvana@acme.io",
    "orgUnitId": "ABC123",
    "positionId": "POS456"
  }'

Trigger LDAP sync

bash

curl -X POST "https://acme.noova.io/manage/api/v1/ldap/sync" \
  -H "Authorization: Bearer noova_pat_xxx"

Lưu ý

PAT khác với SSO token: PAT dùng cho integration ngoài; SSO token chỉ tồn tại trong session người dùng đăng nhập qua trình duyệt.
PAT không hết hạn theo session: thu hồi thủ công khi không dùng nữa, hoặc khi nghi ngờ bị lộ.
Không hardcode PAT trong source code public - dùng env var hoặc secret manager.
Test trực tiếp trên Swagger UI: không cần Postman cho POC - vào /manage/api/v1/docs, paste PAT vào nút Authorize, click "Try it out".
Spec OpenAPI có thể được import vào: Postman, Insomnia, Bruno, Hoppscotch, hoặc dùng để generate SDK qua openapi-generator.

Xem thêm

Quản lý dịch vụ - Bật allowOpenAPI + tạo PAT
SSO - Tích hợp SSO cho người dùng nội bộ
LDAP / Active Directory - Sync user từ LDAP qua API
Vai trò và phân quyền - Cấp quyền API_TOKEN_CREATE cho user con

API Reference ​

Truy cập tài liệu API ​

Xác thực ​

Personal Access Token (PAT) ​

Thu hồi PAT ​

Cấu trúc API ​

Nhóm Xác thực & danh tính ​

Nhóm Tổ chức ​

Nhóm Đào tạo (LMS) ​

Nhóm Chương trình đào tạo ​

Nhóm Hiệu suất & nhân tài ​

Nhóm Tuyển dụng ​

Nhóm Vòng đời nhân sự ​

Nhóm Chấm công ​

Nhóm Lương thưởng ​

Nhóm Cuộc họp ​

Nhóm Gắn kết & cộng đồng ​

Nhóm Tích hợp ngoài ​

Pattern chung ​

Pagination ​

Filter ​

Response codes ​

Error response shape ​

Timezone & dates ​

Phụ thuộc Feature Toggle ​

Rate limit ​

Phiên bản hoá ​

Ví dụ ​

Lấy danh sách nhân sự ​

Tạo nhân sự mới ​

Trigger LDAP sync ​

Lưu ý ​

Xem thêm ​

API Reference

Truy cập tài liệu API

Xác thực

Personal Access Token (PAT)

Thu hồi PAT

Cấu trúc API

Nhóm Xác thực & danh tính

Nhóm Tổ chức

Nhóm Đào tạo (LMS)

Nhóm Chương trình đào tạo

Nhóm Hiệu suất & nhân tài

Nhóm Tuyển dụng

Nhóm Vòng đời nhân sự

Nhóm Chấm công

Nhóm Lương thưởng

Nhóm Cuộc họp

Nhóm Gắn kết & cộng đồng

Nhóm Tích hợp ngoài

Pattern chung

Pagination

Filter

Response codes

Error response shape

Timezone & dates

Phụ thuộc Feature Toggle

Rate limit

Phiên bản hoá

Ví dụ

Lấy danh sách nhân sự

Tạo nhân sự mới

Trigger LDAP sync

Lưu ý

Xem thêm