API
Cây route, xác thực và các mã lỗi chuẩn.
Tiền tố route
Mọi endpoint đều nằm dưới /api/v1.
| Tiền tố | Đối tượng | Ghi chú |
|---|---|---|
/api/v1/app/* | App người dân | Xác thực bằng cookie phiên khách. |
/api/v1/admin/* | Trang quản trị | Xác thực bằng cookie phiên nhân viên. |
/api/v1/* (không tiền tố) | Dùng chung | Ví dụ /api/v1/orders, /api/v1/photos, /api/v1/invoices. |
Phân biệt đối tượng bằng cookie, không bằng tiền tố
API xác định người gọi là khách hay nhân viên dựa trên cookie phiên. Hai cây route tách biệt nhưng chạy trong cùng một tiến trình và cùng một cơ sở dữ liệu.
Các nhóm endpoint chính
| Nhóm | Đường dẫn gốc | Việc gì |
|---|---|---|
| Kiểm tra sức khoẻ | GET /healthz, GET /readyz | Giám sát và triển khai. |
| Đăng nhập nhân viên | POST /api/v1/admin/auth/login | Đăng nhập bằng email. |
| Đăng nhập khách | POST /api/v1/app/auth/otp/send, /otp/verify, /register, /refresh, /logout | OTP, đăng ký, làm mới phiên. |
| Đặt lịch và đơn | /api/v1/admin/orders, /api/v1/app/orders | Duyệt, từ chối, phân xe, sửa, huỷ. |
| Phiên thu gom | /api/v1/admin/collection-sessions | Tạo phiên, bắt đầu, nhập phiếu, chuyển kiểm tra. |
| Phiên kiểm tra | /api/v1/admin/collection-inspections | Cân tổng, nhập từng loại, hoàn tất. |
| Hoá đơn và chi trả | /api/v1/admin/invoices, /api/v1/app/invoices | Danh sách, xác nhận, tạm dừng, chi trả. |
| Tài chính | /api/v1/admin/finance | Phiếu chi, doanh thu, kho. |
| Cấu hình | /api/v1/admin/{pricing,operations,depots,bag-shops,vehicle-types,vehicle-collectors,customers,accounts,roles} | Cài đặt hệ thống. |
| Thông báo | /api/v1/admin/notifications, /api/v1/booking-notifications | Trung tâm thông báo. |
| Tổng quan | /api/v1/admin/{dashboard,overview} | Số liệu màn Tổng quan. |
| Ảnh | POST /api/v1/photos, GET /api/v1/photos/:id | Tải và đọc ảnh. |
| Chỉ môi trường dev | /api/v1/dev/* | Chỉ đăng ký khi chạy development. |
Xác thực
Nhân viên
- Cookie
yc_m2_staff, đặthttpOnly,sameSite=lax,path=/, hạn 7 ngày khi chọn "ghi nhớ". - Cơ sở dữ liệu chỉ lưu hash của token, không lưu token gốc.
- Thiếu hoặc hết hạn phiên trả
401 UNAUTHENTICATEDvới thông báo Vui lòng đăng nhập.
Khách hàng
- Cặp cookie:
yc_m2_citizen(access token, hạn 900 giây) vàyc_citizen_refresh(refresh token, mặc định 90 ngày). - Refresh token được xoay mỗi lần làm mới. Nếu phát hiện token cũ bị dùng lại, hệ thống thu hồi toàn bộ nhóm token của thiết bị đó.
- Token không lưu trong
localStorage; trình duyệt tự gửi cookie.
Bảo vệ bổ sung
| Cơ chế | Thiết lập |
|---|---|
| CORS | Chỉ cho origin công khai và allowlist localhost khi không phải production. |
| Kiểm tra Origin | Chặn POST/PATCH/PUT/DELETE từ origin ngoài allowlist, trả 403 ORIGIN_FORBIDDEN. |
| Giới hạn tần suất | 120 request/phút ở production, 1200/phút ở môi trường khác. |
| Kích thước body | 128 KB cho JSON. |
| Tải ảnh | 1 file mỗi lần, tối đa 10 MB; quá cỡ trả 413 PHOTO_TOO_LARGE. |
| Cache | Mọi phản hồi /api/ mặc định Cache-Control: private, no-store. |
Định dạng lỗi
Lỗi trả về theo cặp mã và thông báo:
{ "code": "BOOKING_LOCKED", "message": "Lịch đã kết thúc hoặc đã xếp phiên nên không thể sửa, hủy hay duyệt." }- Lỗi kiểm tra dữ liệu vào trả
400 VALIDATION. - Lỗi quyền trả
403 PERMISSION_DENIED, hoặcDEPOT_SCOPEkhi thao tác ngoài điểm tập kết được phân. - Tranh chấp phiên bản trả
409với mã riêng cho từng nghiệp vụ.
Danh sách đầy đủ mã lỗi ở Tra cứu nhanh.
Yêu cầu bắt buộc ở production
Khi NODE_ENV=production, API từ chối khởi động nếu thiếu bất kỳ điều kiện nào:
- Nhà cung cấp SMS là Firebase và có API key tương ứng.
YECHAI_OTP_PEPPERdài tối thiểu 32 ký tự.YECHAI_PUBLIC_ORIGINbắt đầu bằnghttps://.- Không bật chế độ bootstrap QA.