1. Tổng quan

1.1 Các yêu cầu được đề cập

1.2 Nguyên tắc API

• Thiết kế RESTful
• Yêu cầu/Phản hồi dạng JSON
• Phiên bản hóa qua đường dẫn URL (/v1/)
• Không trạng thái (Xác thực JWT)
• Hệ thống vai trò hai cấp:
  • Vai trò cấp hệ thống (được quản lý bởi AUTH): user (tự đăng ký), super_admin (chỉ tạo bởi quản trị viên)
  • Vai trò cấp tổ chức (được quản lý trong tổ chức): HR, Candidate, Employer
• Endpoint dựa trên vai trò cấp tổ chức: /candidate/, /hr/, /employer/

1.3 Xác thực

Tất cả các endpoint đều yêu cầu JWT Bearer token trừ khi được đánh dấu là Công khai. JWT chứa vai trò cấp hệ thống của người dùng.

Authorization: Bearer <access_token>

// JWT Payload includes:
{
  "sub": "user_id",
  "email": "[email protected]",
  "role": "user" | "super_admin"
}

// Note: Organization-level roles (HR, Candidate, Employer)
// are managed within organizations, not in the system JWT.

2. Định dạng Phản hồi

2.1 Phản hồi thành công

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req-abc-123",
    "timestamp": "2026-07-31T10:30:00Z"
  }
}

2.2 Phản hồi lỗi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

3. Mã lỗi

4. Giới hạn tốc độ yêu cầu

5. Các Endpoint

5.2 Endpoint cho Ứng viên

Lưu ý: Các endpoint này yêu cầu vai trò tổ chức Ứng viên trong ngữ cảnh tổ chức đang hoạt động. Vai trò Ứng viên được gán bởi chủ/quản trị viên tổ chức, không phải khi đăng ký hệ thống.

GET /recr/jobs FR-003

Duyệt danh sách tin tuyển dụng. Endpoint công khai (không yêu cầu xác thực).

Tham số truy vấn: search, location, salary_min, employment_type, page, limit

POST /recr/applications FR-004, FR-038

Nộp đơn ứng tuyển. Yêu cầu vai trò candidate.

Phụ thuộc liên module: ApplicationService gọi FileService (FILE) để xác minh resume_file_id tồn tại và là tệp danh mục RESUME. resume_file_id được đóng băng (sao chép) vào bản ghi đơn ứng tuyển tại thời điểm nộp.

Tóm tắt luồng

1. Frontend gửi đơn ứng tuyển với job_id, cover_letter và resume_file_id (hoặc resume_id từ danh sách hồ sơ của ứng viên)
2. ApplicationService kiểm tra ứng viên tồn tại và chưa nộp đơn cho vị trí này
3. ApplicationService gọi FileService (FILE) để xác minh resume_file_id tồn tại và có thể truy cập bởi ứng viên
4. ApplicationService tạo bản ghi đơn ứng tuyển với resume_file_id đã đóng băng
5. ApplicationService phát sự kiện application.submitted
6. ApplicationService trả về 201 Created với chi tiết đơn ứng tuyển

Request Body

{
  "job_id": 1,
  "cover_letter": "I am interested in this position...",
  "resume_file_id": "550e8400-e29b-41d4-a716-446655440000"
}

Phản hồi 201

{
  "success": true,
  "data": {
    "id": 1,
    "job_id": 1,
    "candidate_id": 101,
    "resume_file_id": "550e8400-e29b-41d4-a716-446655440000",
    "cover_letter": "I am interested in this position...",
    "status": "submitted",
    "applied_at": "2026-08-17T10:00:00Z"
  }
}

Phản hồi lỗi

409 Xung đột -- Đã nộp đơn:

{
  "success": false,
  "error": {
    "code": "APPLICATION_EXISTS",
    "message": "Candidate already applied to this job"
  }
}

400 Yêu cầu không hợp lệ -- Tệp hồ sơ không hợp lệ:

{
  "success": false,
  "error": {
    "code": "INVALID_RESUME_FILE",
    "message": "Resume file not found or does not belong to candidate"
  }
}

400 Yêu cầu không hợp lệ -- Sai danh mục tệp:

{
  "success": false,
  "error": {
    "code": "INVALID_FILE_CATEGORY",
    "message": "Only RESUME category files can be linked to applications"
  }
}

Quy tắc kinh doanh

GET /recr/candidate/applications FR-005

Xem đơn ứng tuyển của tôi. Yêu cầu vai trò candidate.

PATCH /recr/candidate/profile FR-006

Cập nhật hồ sơ. Yêu cầu vai trò candidate.

POST /recr/candidate/resume FR-007, FR-037

Tải lên tệp hồ sơ vào danh sách hồ sơ của ứng viên. Yêu cầu vai trò candidate. Tệp được lưu trữ thông qua module FILE.

Phụ thuộc liên module: ProfileService gọi FileService (FILE) để lấy URL tải lên đã ký, sau đó tệp được tải lên module FILE. ProfileService lưu file_id được trả về trong bảng recr_candidate_resumes.

Tóm tắt luồng

1. Frontend yêu cầu URL tải lên đã ký từ RECR (hoặc gọi trực tiếp module FILE)
2. Frontend tải tệp lên module FILE thông qua URL đã ký
3. Frontend gọi POST /recr/candidate/resume với file_id từ module FILE
4. ProfileService kiểm tra file_id tồn tại trong module FILE và là danh mục RESUME
5. ProfileService tạo bản ghi trong recr_candidate_resumes với tham chiếu file_id
6. ProfileService trả về 201 Created với metadata hồ sơ

Request Body

{
  "file_id": "550e8400-e29b-41d4-a716-446655440000"
}

Phản hồi 201

{
  "success": true,
  "data": {
    "resume_id": 1,
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "john_doe_resume.pdf",
    "mime_type": "application/pdf",
    "file_size": 245760,
    "is_primary": false,
    "uploaded_at": "2026-08-17T10:00:00Z"
  }
}

Phản hồi lỗi

400 Yêu cầu không hợp lệ -- Tệp không hợp lệ:

{
  "success": false,
  "error": {
    "code": "INVALID_FILE",
    "message": "File not found in FILE module or is not a RESUME category file"
  }
}

400 Yêu cầu không hợp lệ -- Tệp quá lớn:

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size must not exceed 10MB"
  }
}

Quy tắc kinh doanh

GET /recr/candidate/resumes FR-037

Liệt kê tất cả hồ sơ của ứng viên hiện tại. Yêu cầu vai trò candidate.

Phản hồi 200

{
  "success": true,
  "data": {
    "resumes": [
      {
        "id": 1,
        "file_id": "550e8400-e29b-41d4-a716-446655440000",
        "file_name": "john_doe_resume.pdf",
        "mime_type": "application/pdf",
        "file_size": 245760,
        "is_primary": true,
        "created_at": "2026-08-17T10:00:00Z"
      },
      {
        "id": 2,
        "file_id": "660e8400-e29b-41d4-a716-446655440001",
        "file_name": "john_doe_resume_v2.docx",
        "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "file_size": 189440,
        "is_primary": false,
        "created_at": "2026-08-15T14:30:00Z"
      }
    ]
  }
}

DELETE /recr/candidate/resumes/:id FR-037

Xóa hồ sơ khỏi danh sách của ứng viên. Yêu cầu vai trò candidate. Chỉ được phép khi hồ sơ chưa liên kết với đơn ứng tuyển nào đã nộp.

Phản hồi 200

{
  "success": true,
  "data": {
    "message": "Resume deleted successfully"
  }
}

Phản hồi lỗi

409 Xung đột -- Hồ sơ liên kết với đơn ứng tuyển:

{
  "success": false,
  "error": {
    "code": "RESUME_LINKED",
    "message": "Cannot delete resume that is linked to a submitted application"
  }
}

GET /recr/candidate/applications/:id/resume FR-038

Lấy URL tải xuống đã ký cho hồ sơ đã đóng băng của đơn ứng tuyển. Yêu cầu vai trò candidate. Ứng viên chỉ có thể xem hồ sơ từ đơn ứng tuyển của chính mình.

Phụ thuộc liên module: ApplicationController gọi FileService (FILE) để tạo URL tải xuống đã ký có thời hạn cho resume_file_id đã đóng băng.

Phản hồi 200

{
  "success": true,
  "data": {
    "download_url": "https://file-storage.example.com/presigned/...",
    "expires_at": "2026-08-17T11:00:00Z",
    "file_name": "john_doe_resume.pdf"
  }
}

5.3 Endpoint cho HR

Lưu ý: Các endpoint này yêu cầu vai trò tổ chức HR trong ngữ cảnh tổ chức đang hoạt động. Vai trò HR được gán bởi chủ/quản trị viên tổ chức.

GET /recr/hr/applications FR-008

Xem đơn ứng tuyển. Yêu cầu vai trò hr.

Tham số truy vấn: job_id, status, page, limit

PATCH /recr/hr/applications/:id/status FR-009

Cập nhật trạng thái đơn ứng tuyển. Yêu cầu vai trò hr.

POST /recr/hr/interviews FR-010

Lên lịch phỏng vấn. Yêu cầu vai trò hr.

Yêu cầu:

{
  "application_id": 1,
  "interviewer_id": 201,
  "scheduled_at": "2026-08-05T14:00:00Z",
  "duration_minutes": 60,
  "location": "Meeting Room A",
  "meeting_link": "https://meet.google.com/abc-defg-hij"
}

POST /recr/hr/evaluations FR-011

Gửi đánh giá. Yêu cầu vai trò hr.

POST /recr/hr/offers FR-012

Tạo đề nghị tuyển dụng. Yêu cầu vai trò hr.

GET /recr/hr/pipeline FR-014

Xem quy trình tuyển dụng. Yêu cầu vai trò hr.

GET /recr/hr/reports FR-015

Tạo báo cáo. Yêu cầu vai trò hr.

5.4 Endpoint cho Nhà tuyển dụng

Lưu ý: Các endpoint này yêu cầu vai trò tổ chức Nhà tuyển dụng trong ngữ cảnh tổ chức đang hoạt động. Vai trò Nhà tuyển dụng thường được gán cho chủ/quản trị viên tổ chức tạo tin tuyển dụng.

POST /recr/employer/jobs FR-017

Tạo tin tuyển dụng. Yêu cầu vai trò employer.

Yêu cầu:

{
  "title": "Senior Software Engineer",
  "description": "We are looking for a senior engineer...",
  "department": "Engineering",
  "location": "Ho Chi Minh City",
  "salary_min": 20000000,
  "salary_max": 40000000,
  "employment_type": "full_time",
  "requirements": [
    { "type": "skill", "description": "5+ years Node.js", "is_mandatory": true }
  ]
}

GET /recr/employer/jobs FR-018

Liệt kê tin tuyển dụng của tôi. Yêu cầu vai trò employer.

PATCH /recr/employer/jobs/:id FR-018

Cập nhật tin tuyển dụng. Yêu cầu vai trò employer.

GET /recr/employer/jobs/:id/applicants FR-019

Xem người nộp đơn. Yêu cầu vai trò employer.

PATCH /recr/employer/jobs/:id/submit FR-020

Gửi để HR phê duyệt. Yêu cầu vai trò employer.

GET /recr/employer/analytics FR-021

Xem phân tích. Yêu cầu vai trò employer.

6. Phân trang

Tất cả các endpoint danh sách hỗ trợ phân trang offset.

GET /recr/jobs?page=2&limit=20

7. Sự kiện Webhook

8. Nhật ký thay đổi