Tham khảo API

Swagger UI

Tài liệu API tương tác có sẵn tại:

http://localhost:3000/api/docs

Swagger tự động generate từ NestJS decorators (@ApiTags, @ApiOperation, @ApiResponse, ...). Tất cả endpoint đều có mô tả chi tiết request/response.

Để lấy OpenAPI spec dạng JSON:

curl http://localhost:3000/api/docs-json

Base URL và Convention

Thuộc tính	Giá trị
Base URL	/api
Format	JSON
Versioning	Không dùng versioning (monolith)

Xác thực (Authentication)

SmartCK Hub sử dụng JWT lưu trong httpOnly cookies:

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "Admin@123"
}

Response: Set cookies access_token + refresh_token tự động. Các request tiếp theo không cần gửi header Authorization -- browser tự gửi cookie.

Cookie	Mục đích	Thời hạn
access_token	JWT access	15 phút
refresh_token	JWT refresh	7 ngày

Auto-refresh

Khi access token hết hạn, backend tự động dùng refresh token để cấp token mới. Frontend không cần xử lý thủ công.

Tổng quan Endpoints

IAM

Method	Endpoint	Mô tả
POST	/api/auth/login	Đăng nhập
POST	/api/auth/logout	Đăng xuất
POST	/api/auth/refresh	Refresh token
POST	/api/auth/forgot-password	Gửi email reset mật khẩu
GET	/api/admin/users	Danh sách users
GET	/api/admin/roles	Danh sách roles
GET	/api/admin/permissions	Danh sách permissions
GET	/api/admin/menus	Menu hệ thống
GET	/api/profile	Profile user hiện tại
POST	/api/upload	Upload file

Commercial

Method	Endpoint	Mô tả
GET	/api/customers	Danh sách khách hàng
POST	/api/customers	Tạo khách hàng mới
GET	/api/contracts	Danh sách hợp đồng
POST	/api/contracts	Tạo hợp đồng
GET	/api/service-packages	Danh sách gói dịch vụ

Delivery

Method	Endpoint	Mô tả
GET	/api/projects	Danh sách dự án
GET	/api/operations/sprints	Danh sách sprints
GET	/api/operations/tasks	Danh sách tasks
GET	/api/operations/posts	Danh sách posts
GET	/api/shooting-sessions	Phiên chụp/quay
GET	/api/support-tickets	Phiếu hỗ trợ

Organization

Method	Endpoint	Mô tả
GET	/api/organization/departments	Phòng ban
GET	/api/organization/positions	Chức vụ
GET	/api/organization/employees	Nhân viên
GET	/api/organization/pods	POD

Auto-generated API Client

Frontend sử dụng Orval để tự động generate typed React Query hooks từ OpenAPI spec.

Cách generate

# Đảm bảo backend đang chạy (cần Swagger JSON endpoint)
pnpm api:generate

Sử dụng trong Frontend

import { useGetProjects, useGetProjectsId, usePostProjects } from '@smartck/api-client';

// GET danh sách
const { data, isLoading } = useGetProjects({ page: 1, limit: 20 });

// GET chi tiết
const { data: project } = useGetProjectsId(projectId);

// POST tạo mới
const { mutate } = usePostProjects();
mutate({ data: { name: 'Dự án mới' } });

Error Response Format

Tất cả error trả về theo format nhất quán:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Email không hợp lệ"
    }
  ],
  "timestamp": "2026-03-16T10:00:00.000Z",
  "path": "/api/customers"
}

HTTP Code	Ý nghĩa
400	Validation error
401	Chưa xác thực (token missing)
403	Không có quyền
404	Resource không tồn tại
409	Conflict (duplicate)
500	Server error

Pagination Pattern

Các endpoint danh sách hỗ trợ pagination qua query params:

GET /api/customers?page=1&limit=20&search=abc&sortBy=createdAt&sortOrder=desc

Response:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Service PaginationService tại src/shared/common/services/pagination.service.ts chuẩn hóa logic pagination cho toàn bộ backend.