Đại lý và tín dụng

Cách hoạt động

• Bạn mời đại lý bằng email và chọn các gói họ được bán, mỗi gói một giá tính bằng tín dụng cho mỗi key.
• Bạn nạp tín dụng cho đại lý. Tín dụng là đơn vị nội bộ giữa hai bên: ClavisAUH không thu tiền hộ, bạn nhận thanh toán theo cách của mình rồi ghi sổ.
• Đại lý phát hành key ở Kinh doanh › Cổng đại lý hoặc qua Reseller API. Mỗi đơn trừ giá × số key khỏi số dư.
• Số dư luôn là tổng các bút toán trong sổ, không phải một con số lưu riêng có thể bị lệch.

Key do đại lý bán là license bình thường của ứng dụng: chúng nằm trong Phát hành & bản quyền › License, tuân theo luật của gói và phát webhook license.created như mọi key khác.

Điều kiện

• Workspace dùng gói Premium. Trên Basic, nút Mời đại lý bị khoá kèm dòng "Tính năng đại lý có trên gói Premium", còn API trả lỗi plan_limit (HTTP 402). Xem bảng giá.
• Bạn có vai trò Chủ sở hữu hoặc Quản trị. Thành viên không xem và không quản lý được đại lý.
• Ứng dụng có ít nhất một gói license ở Phát hành & bản quyền › Đăng nhập & gói license. Nếu chưa có, khung mời hiện "Chưa có gói nào để bán".

Mời đại lý

1. Mở Kinh doanh › Đại lý và bấm Mời đại lý.
2. Điền khung Mời đại lý theo bảng dưới.
3. Bấm Gửi lời mời. Đại lý nhận email có link nhận lời, còn thẻ của họ hiện trạng thái Đang chờ nhận lời.

Nếu đại lý không thấy email, bấm vào thẻ của họ rồi bấm Gửi lại lời mời. Mỗi lần gửi lại tạo một link mới và link cũ hết hiệu lực. Sau khi mời, khung quản lý cho đổi gói, giá và trạng thái; tên, giới hạn ngày và quyền xem chỉ đặt được lúc mời.

Gói và giá

Mỗi đại lý được cấp tối đa 50 gói, giá tối đa 1.000.000 tín dụng mỗi key.

• Key đại lý phát hành lấy thời hạn và số máy từ gói. Đại lý không đổi được thời hạn, số máy hay tiền tố; thời hạn vẫn tính từ lần kích hoạt đầu tiên.
• Để sửa, bấm vào thẻ đại lý, chỉnh mục Gói và giá rồi bấm Lưu gói và giá. Danh sách mới thay toàn bộ danh sách cũ. Bỏ một gói chỉ chặn các đơn mới; key đã bán không bị ảnh hưởng.
• Giá 0 nghĩa là đại lý phát hành gói đó miễn phí, chỉ còn giới hạn key mỗi ngày chặn lại.
• Muốn đại lý tự đặt lại thiết bị cho khách qua Reseller API, tích Đại lý ở mục Chuyển máy khi sửa gói. Xem Gói license và quyền tính năng.

Nạp và điều chỉnh tín dụng

1. Bấm vào thẻ đại lý. Phần đầu khung hiện Số dư.
2. Ở mục Nạp hoặc điều chỉnh, nhập số tín dụng và Ghi chú, rồi bấm Ghi sổ.

• Số dương là nạp, vào sổ với loại Nạp.
• Số âm là điều chỉnh, vào sổ với loại Điều chỉnh và bắt buộc có ghi chú từ 3 ký tự.
• Mỗi bút toán là số nguyên khác 0, tối đa 10.000.000 theo mỗi chiều; ghi chú tối đa 300 ký tự.
• Số dư không bao giờ âm. Khoản trừ lớn hơn số dư bị từ chối với mã negative_balance.

Nếu bạn bán tín dụng qua cửa hàng riêng, hãy tự động hoá bước nạp bằng một Seller API key có scope resellers:write, tạo ở Kinh doanh › Khoá Seller API. GET /seller/v1/resellers (scope resellers:read) trả danh sách đại lý kèm ID và số dư.

curl -X POST https://api.example.com/seller/v1/resellers/$RESELLER_ID/credit \
  -H "Authorization: Bearer $CLAVIS_API_KEY" \
  -H "Idempotency-Key: payment-1042" \
  -H "content-type: application/json" \
  -d '{"amount": 500, "note": "Payment 1042"}'

Kết quả trả về { "data": { "balance": … } }. Với Idempotency-Key, cùng một khoản thanh toán gửi lại trong 24 giờ chỉ được ghi sổ một lần.

Sổ tín dụng

Mục Sổ tín dụng trong khung đại lý hiện 50 bút toán gần nhất, mới nhất trước, mỗi dòng có loại, ghi chú, số tín dụng và thời điểm:

• Nạp: khoản bạn nạp.
• Bán key: một đơn của đại lý, ghi chú dạng 5 × Tên gói kèm số key.
• Điều chỉnh: khoản trừ kèm lý do.

Bấm CSV để tải sổ (tối đa 10.000 bút toán, cũ nhất trước) với các cột date, kind, amount, keys, note. Với Seller API, mỗi license có trường resellerId, và GET /seller/v1/apps/app_…/licenses?resellerId=… lọc key của một đại lý.

Mỗi đơn khoá bản ghi đại lý, kiểm tra giới hạn ngày và số dư, tạo key rồi ghi bút toán trừ trong cùng một transaction. Nếu một bước thất bại, không key nào được tạo và không tín dụng nào bị trừ; hai đơn chạy song song không thể tiêu quá số dư.

Tạm dừng và thu hồi

Công tắc Đang bán hiện trong khung khi đại lý đã nhận lời:

• Tắt: đại lý chuyển sang Tạm dừng. Mọi Reseller API key của họ bị thu hồi ngay; họ không phát hành, tạm khoá hay mở lại key được nữa (mã reseller_inactive). Key đã bán vẫn chạy bình thường.
• Bật lại: đại lý bán tiếp ngay, nhưng phải tạo Reseller API key mới.
• Đại lý chưa nhận lời thì không bật được; khung hiện Gửi lại lời mời thay cho công tắc.

Hiện chưa có thao tác xoá đại lý; tắt Đang bán là cách dừng hẳn.

Để thu hồi mọi key một đại lý đã bán, vào mục Thu hồi toàn bộ, bấm Thu hồi mọi key (nút bị khoá khi đại lý chưa bán key nào), nhập Lý do thu hồi từ 3 đến 300 ký tự và xác nhận. Mọi key của đại lý chưa bị thu hồi chuyển sang Thu hồi, mọi phiên trên các key đó kết thúc ngay. Lý do và số key được lưu vào nhật ký kiểm toán.

Phía đại lý

Nhận lời mời

1. Mở link Accept invitation trong email. Link dẫn tới Kinh doanh › Cổng đại lý; nếu chưa đăng nhập, bạn qua trang đăng nhập rồi được đưa về đúng trang này.
2. Đăng nhập bằng đúng email được mời, hoặc tạo tài khoản bằng email đó nếu chưa có.
3. Bấm Nhận lời trong khung Lời mời làm đại lý.

Đăng nhập bằng tài khoản khác sẽ nhận lỗi wrong_account. Link đã dùng, đã bị thay bằng lần gửi lại hoặc không hợp lệ trả invite_expired; khi đó hãy nhờ người bán bấm Gửi lại lời mời.

Mục Cổng đại lý chỉ hiện trong thanh bên khi bạn đã làm đại lý cho ít nhất một workspace. Nếu bán cho nhiều workspace, bạn chuyển qua lại bằng các nút mang tên workspace ở đầu trang.

Cổng đại lý

• Số dư (tín dụng), trạng thái và giới hạn ngày nếu có ("tối đa N key mỗi ngày").
• Phát hành key: các gói bạn được bán, kèm ứng dụng và giá.
• Key bạn đã phát hành: bản xem trước, trạng thái, ngày hết hạn, thời điểm tạo, cùng nút Tạm khoá hoặc Mở lại cho từng key.
• Sổ tín dụng: 12 bút toán gần nhất.
• Reseller API: tạo khoá cho bot hoặc cửa hàng của bạn.

Khi bị tạm dừng, bạn vẫn xem được trang nhưng không phát hành hay thao tác key được.

Phát hành key bằng tín dụng

1. Chọn một gói trong Phát hành key.
2. Nhập Số key (1 đến 500). Email người mua và Ghi chú đơn hàng (tối đa 500 ký tự) không bắt buộc.
3. Kiểm tra dòng Tổng N tín dụng (chuyển màu đỏ khi vượt số dư), rồi bấm Phát hành.
4. Bấm Chép tất cả và gửi key cho khách ngay.

Email người mua được gắn vào license và mở cổng khách hàng cho khách. Mỗi đơn còn tính vào hạn mức key mỗi lô và key mỗi ngày của workspace người bán, xem Gói Basic, Premium và hạn mức.

Reseller API của đại lý

Trong thẻ Reseller API, bấm Tạo khoá và cất khoá ngay vì nó chỉ hiện một lần.

• Khoá chỉ có scope licenses:read và licenses:write: chỉ thấy, chỉ bán key của chính bạn và trừ vào cùng số dư.
• Được gọi GET /seller/v1/me (kèm số dư), GET /seller/v1/apps, đọc và tra cứu key của mình, tạo key, và các thao tác suspend, reinstate, note, cùng reset_devices nếu gói cho đại lý chuyển máy. Không xoá, thu hồi hay gia hạn key được (forbidden_scope).
• Tối đa 5 khoá đang hoạt động cho mỗi đại lý. Cổng hiện chỉ có nút tạo khoá, chưa có danh sách để thu hồi; nếu khoá bị lộ, hãy báo người bán tạm dừng tài khoản đại lý, việc này thu hồi mọi khoá ngay.

curl -X POST https://api.example.com/seller/v1/apps/app_…/licenses \
  -H "Authorization: Bearer $CLAVIS_RESELLER_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "content-type: application/json" \
  -d '{"policyId": "pol_…", "count": 1, "email": "buyer@example.com", "note": "Order 1042"}'

policyId là bắt buộc với khoá đại lý; hãy hỏi người bán ID các gói bạn được bán. API dùng count, email và note; thời hạn, số máy và tiền tố luôn theo gói. Kết quả có dạng { "data": { "keys": [...], "ids": [...], "balance": … } }, với balance là số dư sau đơn.

Khi không đủ tín dụng và các lỗi khác

Lỗi có dạng { "error": { "code": "…", "message": "…", "requestId": "…" } }. Với các lỗi phát hành dưới đây, đơn bị huỷ trọn vẹn: không key nào được tạo và không tín dụng nào bị trừ.

Liên quan

• Bán hàng qua Seller API
• Gói license và quyền tính năng
• Webhook
• Gói Basic, Premium và hạn mức