Màn gói cước và hoá đơn (bản SaaS) #
Chỉ có ở bản SaaS (server chạy cùng nền tảng). Bản on-premise / standalone trả
501 billing_unavailable cho các route /api/v1/plan/subscription và
/api/v1/plan/invoices* — ẩn các màn này khi gặp mã đó. Cần quyền
core.view_billing. Các route dưới /api/v1/plan vẫn gọi được khi cửa hàng đã
hết hạn (subscription_expired) — để khách tự xem và trả hoá đơn mà mở lại.
Mô hình #
- Một thuê bao cho cả khách: một gói, một hạn cho MỌI cửa hàng của khách; tiền mỗi kỳ = giá gói × số cửa hàng, cộng các add-on (theo cửa hàng hoặc một lần cho khách).
- Giá của một kỳ = giá có hiệu lực tại đầu kỳ. Đổi giá có hẹn ngày: kỳ đang chạy giữ giá cũ. Khách có thể có giá riêng (hợp đồng).
- Gói quyết định module dùng được: module ngoài gói trả 404
module_not_enabled(menu đã lọc sẵn).
Màn "Gói của tôi" #
GET /api/v1/plan/subscription (getStoreSubscription) — null = khách không
có thuê bao (không giới hạn). Hiện:
planName,price(giá đang áp cho khách, null = miễn phí) ×quantity(số cửa hàng),expiresAt/graceUntil;addons[](name,price,quantity);nextPeriod: dự tính hoá đơn kỳ sau (lines[],total) — theo giá có hiệu lực tại đầu kỳ đó;upcomingPrices[]: giá sắp đổi có ảnh hưởng tới khách (name,pricemới,effectiveFrom) — hiện như một thông báo.
Tính năng / hạn mức / trạng thái hạn của CỬA HÀNG đang đứng: GET /api/v1/plan
(getStorePlan, CMS §5).
Màn hoá đơn #
GET /api/v1/plan/invoices (listStoreInvoices) — hoá đơn của KHÁCH (mọi cửa
hàng), mới nhất trước, phân trang theo con trỏ. Mỗi hoá đơn có lines[] (gói ×
số cửa hàng, add-on, chênh lệch đổi gói, thêm cửa hàng), amount (đã trừ
creditApplied), status, và khi còn mở: transfer (tài khoản, nội dung
chuyển khoản, ảnh VietQR). Chuyển đúng nội dung → hoá đơn tự ghi nhận.
Trả bằng ví MoMo: POST /api/v1/plan/invoices/{id}/momo
(payStoreInvoiceWithMomo) → payUrl / deeplink / qrCodeUrl; mỗi lần gọi
một phiên mới. Sau khi trả, đọc lại hoá đơn (trạng thái đổi khi cổng xác nhận).
Hàm SDK của các route này có trong SDK của bản SaaS (không có trong trang tra cứu API của bản lõi).