Nhà phát triển

API & tích hợp

Tài liệu cho công cụ nội bộ, chatbot, HRIS và automation kết nối Cổng HR FPT Telecom. Mọi phản hồi JSON dùng envelope chuẩn; import OpenAPI vào Postman hoặc Insomnia để thử nhanh.

Base URL

Môi trường hiện tại: https://bhxh.orangecloud.vn

OpenAPI 3.1: https://bhxh.orangecloud.vn/api/openapi.json

Xác thực

Chọn cơ chế phù hợp với loại tích hợp. Không gửi secret qua query string.

Không xác thực
Chỉ dùng cho tài liệu hoặc health check công khai.
Cloudflare Turnstile
Gửi `turnstileToken` trong JSON body sau khi widget xác minh trên trình duyệt. Server kiểm tra qua siteverify.
Cookie employee_session
Đăng nhập OTP qua `/api/v1/auth/otp/*`. Cookie HttpOnly được set sau verify.
Cookie cms_session
Đăng nhập CMS qua `POST /api/auth/login`. Dùng cho thao tác admin có session.
Bearer CACHE_REVALIDATE_SECRET
Header `Authorization: Bearer <secret>` cho cron và automation nội bộ (HRIS sync, crawl, cache).
Bearer MEDIA_INGEST_TOKEN
Header `Authorization: Bearer <token>` cho ingest media tự động (tùy chọn).

Định dạng phản hồi

Thành công

{
  "success": true,
  "data": "{ ... }"
}

Lỗi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR | UNAUTHORIZED | ...",
    "message": "Mô tả lỗi tiếng Việt",
    "details": "optional"
  }
}

API công khai

Tra cứu, calculator và ticket HR. Một số endpoint yêu cầu Cloudflare Turnstile.

POST/api/search

Công khai

Tra cứu BHXH/BHYT/BHTN

Hỏi bằng ngôn ngữ tự nhiên; trả về answer card, citations và danh sách hit.

Xác thực: Cloudflare Turnstile
Giới hạn: 30/phút/IP (PUBLIC_API_RATE_LIMIT_*)

Ví dụ request

{
  "query": "Nghỉ không lương 14 ngày có đóng BHXH không?",
  "employeeGroup": "OFFICIAL",
  "categorySlug": "bhxh",
  "hitLimit": 12,
  "turnstileToken": "<token>"
}

Ví dụ response

{
  "success": true,
  "data": {
    "query": "…",
    "hits": [],
    "answer": {
      "shortAnswer": "…",
      "citations": [],
      "confidenceLevel": "HIGH",
      "needsHrReview": false
    }
  }
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/search" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Nghỉ không lương 14 ngày có đóng BHXH không?",
  "employeeGroup": "OFFICIAL",
  "categorySlug": "bhxh",
  "hitLimit": 12,
  "turnstileToken": "<token>"
}'

POST/api/ask

Công khai

Ghi log câu hỏi

Ghi nhận câu hỏi analytics (không trả answer card đầy đủ).

Xác thực: Cloudflare Turnstile
Giới hạn: 30/phút/IP

Ví dụ request

{
  "question": "Mức đóng BHXH tối thiểu là bao nhiêu?",
  "turnstileToken": "<token>"
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/ask" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Mức đóng BHXH tối thiểu là bao nhiêu?",
  "turnstileToken": "<token>"
}'

POST/api/ask-hr/send

Công khai

Tạo ticket HR

Tạo ticket HR/C&B và gửi email thông báo. Gắn userId nếu có session nhân viên.

Xác thực: Cloudflare Turnstile
Giới hạn: 5/15 phút/IP (ASK_HR_RATE_LIMIT_*)

Ví dụ request

{
  "question": "Em muốn xác nhận mức đóng BHXH tháng 5",
  "topic": "bhxh",
  "urgent": "normal",
  "replyEmail": "employee@fpt.com",
  "turnstileToken": "<token>"
}

Ví dụ response

{
  "success": true,
  "data": {
    "ticketId": "…",
    "ticketNumber": "HR-2026-00042",
    "status": "OPEN",
    "notifyEmailSent": true,
    "hrContact": "hr-cnb@example.com"
  }
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/ask-hr/send" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Em muốn xác nhận mức đóng BHXH tháng 5",
  "topic": "bhxh",
  "urgent": "normal",
  "replyEmail": "employee@fpt.com",
  "turnstileToken": "<token>"
}'

POST/api/calculators/salary-tax

Công khai

Tính lương & thuế TNCN

Tính gross↔net, bảng khấu trừ BHXH/BHYT/BHTN và thuế theo cấu hình hiện hành.

Xác thực: Không xác thực

Không yêu cầu Turnstile — phù hợp tích hợp calculator nội bộ.

Ví dụ request

{
  "mode": "gross-to-net",
  "grossSalary": 35000000,
  "insuranceSalaryBase": 35000000,
  "region": "I",
  "dependentCount": 0
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/calculators/salary-tax" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "gross-to-net",
  "grossSalary": 35000000,
  "insuranceSalaryBase": 35000000,
  "region": "I",
  "dependentCount": 0
}'

POST/api/calculators/social-insurance-contribution

Công khai

Tính mức đóng BHXH

Ước tính phần NLĐ/NSDLĐ đóng theo mức lương đóng BH.

Xác thực: Không xác thực

Ví dụ request

{
  "salaryBase": 20000000
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/calculators/social-insurance-contribution" \
  -H "Content-Type: application/json" \
  -d '{
  "salaryBase": 20000000
}'

Đăng nhập nhân viên

OTP qua email công ty; session cookie cho Cổng HR.

POST/api/v1/auth/otp/request

Nhân viên

Gửi OTP đăng nhập nhân viên

Gửi mã OTP tới email công ty nếu tài khoản hợp lệ.

Xác thực: Cloudflare Turnstile
Giới hạn: 10/15 phút/IP (LOGIN_RATE_LIMIT_*)

Ví dụ request

{
  "email": "employee@fpt.com",
  "turnstileToken": "<token>"
}

Ví dụ response

{
  "success": true,
  "data": {
    "message": "Nếu email thuộc tài khoản nhân viên hợp lệ, mã OTP đã được gửi."
  }
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/v1/auth/otp/request" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "employee@fpt.com",
  "turnstileToken": "<token>"
}'

POST/api/v1/auth/otp/verify

Nhân viên

Xác minh OTP

Xác minh mã OTP và thiết lập cookie `employee_session`.

Xác thực: Cloudflare Turnstile

Ví dụ request

{
  "email": "employee@fpt.com",
  "code": "123456",
  "turnstileToken": "<token>"
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/v1/auth/otp/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "employee@fpt.com",
  "code": "123456",
  "turnstileToken": "<token>"
}'

DELETE/api/v1/auth/otp/verify

Nhân viên

Đăng xuất nhân viên

Hủy session nhân viên và xóa cookie.

Xác thực: Cookie employee_session

CMS / quản trị

Đăng nhập HR/Admin cho thao tác quản trị có session.

POST/api/auth/login

CMS / HR

Đăng nhập CMS

Email + mật khẩu cho HR/Admin; set cookie `cms_session`.

Xác thực: Cloudflare Turnstile
Giới hạn: 10/15 phút/IP

Ví dụ request

{
  "email": "admin@fpt.com",
  "password": "••••••••",
  "turnstileToken": "<token>"
}

cURL

curl -sS -X POST "https://bhxh.orangecloud.vn/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "admin@fpt.com",
  "password": "••••••••",
  "turnstileToken": "<token>"
}'

DELETE/api/auth/login

CMS / HR

Đăng xuất CMS

Hủy session CMS và xóa cookie.

Xác thực: Cookie cms_session

Automation & cron

Job nội bộ (HRIS sync, crawl, cache). Chỉ gọi từ Worker cron hoặc CI có secret.

POST/api/cron/hris-sync

Automation

Đồng bộ HRIS

Pull nhân viên từ adapter (mock hoặc Microsoft CSV).

Xác thực: Bearer CACHE_REVALIDATE_SECRET

Tương đương `pnpm hr:sync`.

POST/api/cron/daily-official-crawl

Automation

Crawl pháp luật

Cron crawl nguồn chính thống (06:00 ICT).

Xác thực: Bearer CACHE_REVALIDATE_SECRET

POST/api/cron/db-schema-sync

Automation

Đồng bộ schema HR

Chạy một lần sau deploy Cổng HR (migration idempotent).

Xác thực: Bearer CACHE_REVALIDATE_SECRET

POST/api/admin/revalidate-cache

Automation

Xóa KV cache

Làm mới cache FAQ, legal updates, admin queue.

Xác thực: Bearer CACHE_REVALIDATE_SECRET

POST/api/media/ingest

Automation

Ingest media (R2)

Tải/generate ảnh vào R2 — automation hoặc session CMS.

Xác thực: Bearer MEDIA_INGEST_TOKEN

UI admin dùng session CMS thay vì bearer.

Gợi ý tích hợp

Calculator / payroll tool: dùng POST /api/calculators/salary-tax — không cần Turnstile.
Chatbot nội bộ: POST /api/search với Turnstile invisible hoặc server-side token từ domain được phép.
HRIS / cron: Bearer CACHE_REVALIDATE_SECRET cho /api/cron/* và revalidate cache.
Tổng cộng 16 endpoint được liệt kê — cập nhật từ src/lib/api/api-catalog.ts.