| Method | Path | Mục đích | Trạng thái |
|---|
| GET | /v3/crm/centers | Danh sách trung tâm; thêm subscription_summary {plan_code, status, term_end, read_only} | extend |
| GET | /v3/crm/onboarding/centers | Trung tâm đã tạo trong onboarding | existing |
| POST | /v3/crm/onboarding/create-center | Tạo trung tâm; sau khi tạo, khởi tạo thuê bao trialing 30 ngày | extend |
| GET | /v3/crm/me/accessible-schools | Chi nhánh của người dùng; thêm cờ read_only và subscription_status | extend |
| GET | /v3/teacher/package/my-subscriptions | Gói cá nhân của giáo viên FLYER; không thay đổi, chỉ tham khảo cấu trúc | existing |
| GET | /v3/crm/subscription | → {subscription, plan, limits, usage: [{metric, value, limit, percent}], addons, credit_remaining, pending_downgrade} | new |
| GET | /v3/crm/subscription/plans | Danh mục gói công khai kèm giới hạn và mô-đun, theo X-Locale | new |
| GET | /v3/crm/subscription/usage | metric, from, to → lịch sử theo ngày; ?recompute=true tính lại ngay (1 lần/5 phút) | new |
| POST | /v3/crm/subscription/upgrade-quote | {plan_code, billing_cycle} → {new_price, remaining_value, months_unused, credit_applied, total_due, new_term_end, quote_hash} | new |
| POST | /v3/crm/subscription/upgrade | {plan_code, billing_cycle, quote_hash} → subscription_invoice; 409 STALE_QUOTE khi báo giá quá 24 giờ; Idempotency-Key | new |
| POST · DELETE | /v3/crm/subscription/downgrade | {plan_code} lên lịch hạ gói tại term_end; 422 USAGE_EXCEEDS_PLAN kèm danh sách chỉ số; DELETE huỷ yêu cầu | new |
| GET · POST · DELETE | /v3/crm/subscription/addons | {type, quantity} → báo giá theo tỷ lệ và hoá đơn; DELETE tắt tự gia hạn | new |
| GET | /v3/crm/subscription/invoices · /{id} · /{id}/pdf · /{id}/qr | Danh sách, chi tiết, PDF, mã QR chuyển khoản của hoá đơn thuê bao | new |
| POST | /v3/crm/subscription/invoices/{id}/vnpay · /einvoice | → {redirect_url}, callback cập nhật thanh toán (P2); {buyer} → phát hành hoá đơn điện tử, trả về số và mã tra cứu | new |
| GET · POST | /v3/crm/subscription/events · /notify-owner | Lịch sử thuê bao của tenant, phân trang; báo cho chủ trung tâm về giới hạn đã chạm (1 lần/giờ/người) | new |
| POST | /v3/internal/sepay/webhook | Webhook SePay hiện có (PRD 05) nhận thêm tài khoản của FLYER; khớp payment_code dạng TS-INV | extend |
| GET | /v3/admin/tenants · /{center_id} | status, plan_code, expiring_within_days, account_manager_id, q → danh sách kèm usage; chi tiết → subscription, usage, invoices, credits, events; chỉ tenant.admin | new |
| PATCH | /v3/admin/tenants/{center_id}/subscription | {plan_code, term_start, term_end, billing_cycle, contract_no, trust_payment, reason, version}; tuỳ chọn tạo hoá đơn offline đã thanh toán | new |
| POST | /v3/admin/tenants/{center_id}/trial-extend · /credits · /suspend · /reactivate · /terminate | {days ∈ 7|14|30, reason} (quá 90 ngày tổng cần tenant.admin.override); {amount_vnd, reason, expires_at?}; {reason}; terminate đặt purge_after = now + 90 ngày | new |
| GET · POST · PATCH | /v3/admin/plans · /{id} · /v3/admin/subscription-transactions/unmatched · /{id}/match | Danh mục gói và giới hạn (PATCH giới hạn của gói đang có thuê bao chỉ áp dụng cho kỳ mới); giao dịch SePay chưa khớp trên tài khoản FLYER (bảng unmatched_subscription_transaction, cùng mẫu PRD 05) và gán vào hoá đơn | new |
| middleware | mọi endpoint ghi dưới /v3/crm và /v3/school | 402 PLAN_LIMIT_REACHED {metric, limit, usage, suggested_plan}; 423 TENANT_READ_ONLY {term_end, grace_end}; header X-Plan-Warning: metric=active_students;percent=92 khi từ 90% | new |
