Boxme Levelling — API Developer Portal

Production URL

boxme-levelling.pages.dev/api

Local Dev URL

localhost:5173/api

Format

REST / JSON

Auth Header

X-User-Id

API Endpoints

60+ endpoints chia thành 12 nhóm chức năng. Click vào Swagger UI để test trực tiếp.

🔐

Auth 1 ep

Đăng nhập, lấy thông tin user. Demo mode chấp nhận mọi password.

📊

Dashboard 2 ep

KPI tổng quan: số nhân viên, phân bổ PPH, vi phạm chờ, top performers, trend.

👥

Employees 4 ep

CRUD nhân viên, lịch sử điểm, lịch sử vi phạm theo từng người.

⚠️

Violations 7 ep

Ghi nhận, xác nhận, miễn trừ, khiếu nại vi phạm. Auto-tạo recovery khi confirm.

📚

Recovery & Training 4 ep

Quản lý bản ghi khắc phục, duyệt/từ chối, auto-expire khi quá hạn.

🎁

Bonuses 3 ep

Tạo và duyệt điểm thưởng cho nhân viên (chứng chỉ, sáng kiến, v.v.).

📈

Scores 5 ep

Tính điểm kỳ, submit review, duyệt manager → HR finalize. Workflow 4 bước.

🏥

Benefits 5 ep

Đủ điều kiện phúc lợi, tính lương tháng 13, duyệt hàng loạt.

✅

Approvals 2 ep

Hàng đợi phê duyệt chung: bonus, appeal, score, initiative, recovery.

⚙️

Config 20+ ep

CRUD cấu hình hệ thống: PPH thresholds, violation types/levels, bonus types, skill courses, benefit rules, v.v.

📥

Export 4 ep

Xuất CSV cho payroll, benefit eligibility, lương tháng 13, export log.

📋

Reports 5 ep

Báo cáo quản lý: executive summary, PPH performance, violations analysis, weekly, early warning.

🔐 Authentication

Gọi POST /api/auth/login để lấy token. Sử dụng header X-User-Id cho các request tiếp theo.

Demo Accounts

Username	Password	Role	Warehouse
`admin`	`admin`	BOD	Tất cả
`manager_hn`	`manager_hn`	Warehouse Manager	HN-W01
`leader_hn_1`	`leader_hn_1`	Warehouse Leader	HN-W01
`hr_team`	`hr_team`	HR	Tất cả
`manager_hcm`	`manager_hcm`	Warehouse Manager	HCM-W01

🚀 Getting Started

3 bước để bắt đầu tích hợp với Boxme Levelling API.

Bước 1 — Đăng nhậpcURL
curl -X POST https://boxme-levelling.pages.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'

# Response: { "success": true, "user": { "id": 1, "role": "bod", ... }, "token": "demo_token_1_bod" }

Bước 2 — Lấy danh sách nhân viêncURL
curl https://boxme-levelling.pages.dev/api/employees?page=1&limit=10 \
  -H "X-User-Id: 1"

# Response: { "data": [...], "total": 85, "page": 1, "limit": 10 }

Bước 3 — Lấy dashboard KPIscURL
curl "https://boxme-levelling.pages.dev/api/dashboard/stats?period=2026-02" \
  -H "X-User-Id: 1"

# Response: { "total_employees": 85, "pph_distribution": [...], "pending_violations": 12, ... }

📦 Response Format

Tất cả response trả về JSON. Dưới đây là các format phổ biến.

Success (List)

{
  "data": [ ... ],
  "total": 85,
  "page": 1,
  "limit": 20
}

Success (Action)

{
  "success": true,
  "id": 42
}

Error

{
  "error": "Not found"
}

HTTP Status: 400, 401, 404, 500