nextebook-sdk 1.1.0

NextEbook OEM API Python SDK

NextEbook OEM SDK

NextEbook OEM API 的官方 Python SDK，用于管理会员卡激活码的生成、查询和作废。

功能特性

• ✅ 检查 OEM 单位额度
• ✅ 生成会员卡激活码
• ✅ 作废激活码（仅限未激活的激活码）
• ✅ 激活会员卡
• ✅ 完整的类型提示
• ✅ 自定义异常类
• ✅ 详细的 API 文档

安装

pip install nextebook-sdk

或从源码安装：

git clone https://github.com/nextebook/nextebook-sdk.git
cd nextebook-sdk
pip install .

快速开始

1. 初始化客户端

from nextebook_sdk import OemClient

# 初始化客户端
client = OemClient(
    base_url="http://127.0.0.1:9999",
    api_key="3d0a7dc8-796f-4206-9bc2-b313e6c92a29"
)

2. 检查额度

# 查询 OEM 单位的额度信息
quota = client.check_quota()

print(f"OEM单位: {quota.oem_name}")
print(f"总额度: {quota.activation_code_quota}")
print(f"已使用: {quota.used_quota}")
print(f"剩余: {quota.remaining_quota}")

3. 生成激活码

# 生成 10 个 1 年期激活码
result = client.generate_codes(count=10, validity_years=1)

print(f"成功生成 {len(result.codes)} 个激活码")
for code in result.codes:
    print(code)

print(f"已使用额度: {result.used_quota}")
print(f"剩余额度: {result.remaining_quota}")

4. 作废激活码

# 作废未使用的激活码
result = client.revoke_code("550e8400-e29b-41d4-a716-446655440000")

if result.quota_restored:
    print(f"成功作废，已恢复 {result.validity_years} 年额度")
else:
    print("成功作废")

5. 激活会员卡

# 为用户激活会员卡
result = client.activate_code(
    code="550e8400-e29b-41d4-a716-446655440000",
    user_id=123
)

print(f"成功激活 {result.validity_years} 年期会员")
print(f"OEM单位: {result.oem_name}")

API 参考

OemClient

OEM API 客户端类。

初始化参数

• base_url (str): API 基础 URL
• api_key (str): OEM API 密钥（UUID 格式）
• timeout (int, optional): 请求超时时间（秒），默认 30

方法

check_quota()

检查 OEM 单位的激活码额度。

返回: OemQuotaInfo

抛出异常:

• InvalidApiKeyError: API 密钥无效
• NetworkError: 网络请求失败

---

generate_codes(count, validity_years)

生成激活码。

参数:

• count (int): 生成数量（1-100）
• validity_years (int): 有效期年限（1/2/3）

返回: GenerateCodesResult

抛出异常:

• InvalidApiKeyError: API 密钥无效
• InsufficientQuotaError: 额度不足
• ValueError: 参数无效

---

revoke_code(code)

作废激活码。

业务规则:

• 只有未激活的激活码可以被作废
• 已激活的激活码不可作废（已被用户使用）
• 作废后额度会恢复
• 被作废的激活码不可再激活

参数:

• code (str): 要作废的激活码（UUID 字符串）

返回: RevokeCodeResult

抛出异常:

• InvalidCodeError: 激活码无效
• CannotRevokeActivatedError: 激活码已激活
• AlreadyRevokedError: 激活码已作废
• PermissionDeniedError: 无权操作该激活码

---

activate_code(code, user_id)

激活会员卡激活码。

参数:

• code (str): 激活码（UUID 字符串）
• user_id (int): 用户 ID

返回: ActivateCodeResult

抛出异常:

• InvalidCodeError: 激活码无效
• AlreadyActivatedError: 激活码已被激活
• PermissionDeniedError: 无权操作该激活码

数据模型

OemQuotaInfo

OEM 单位额度信息。

属性:

• oem_name (str): OEM 单位名称
• activation_code_quota (int): 激活码总额度
• used_quota (int): 已使用额度
• remaining_quota (int): 剩余额度

GenerateCodesResult

生成激活码结果。

属性:

• codes (List[str]): 生成的激活码列表
• used_quota (int): 已使用额度
• remaining_quota (int): 剩余额度
• validity_years (int): 有效期年限

RevokeCodeResult

作废激活码结果。

属性:

• code (str): 被作废的激活码
• validity_years (int): 有效期年限
• revoked_at (datetime): 作废时间
• quota_restored (bool): 额度是否已恢复

ActivateCodeResult

激活激活码结果。

属性:

• validity_years (int): 有效期年限
• activated_at (datetime): 激活时间
• oem_name (str): OEM 单位名称

异常处理

SDK 提供了详细的异常类：

• OemApiError: 基础异常类
• InvalidApiKeyError: 无效的 API 密钥
• InsufficientQuotaError: 额度不足
• InvalidCodeError: 无效的激活码
• AlreadyActivatedError: 激活码已被激活
• CannotRevokeActivatedError: 无法作废已激活的激活码
• PermissionDeniedError: 权限不足
• AlreadyRevokedError: 激活码已作废
• NetworkError: 网络错误
• InvalidResponseError: 无效的响应

异常处理示例

from nextebook_sdk import OemClient, InsufficientQuotaError, InvalidCodeError

client = OemClient(base_url="http://127.0.0.1:9999", api_key="...")

try:
    result = client.revoke_code("550e8400-e29b-41d4-a716-446655440000")
    print(f"成功作废: {result}")
except InvalidCodeError:
    print("激活码不存在")
except CannotRevokeActivatedError:
    print("该激活码已被激活，不可作废")
except AlreadyRevokedError:
    print("该激活码已被作废")
except Exception as e:
    print(f"错误: {e}")

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest tests/

代码格式化

black nextebook_sdk/
isort nextebook_sdk/

类型检查

mypy nextebook_sdk/

许可证

MIT License - 详见 LICENSE 文件

支持

• GitHub Issues: https://github.com/nextebook/nextebook-sdk/issues
• 邮箱: [e-mail]

更新日志

1.0.0 (2025-01-26)

初始版本发布：

• ✅ 检查 OEM 单位额度
• ✅ 生成会员卡激活码
• ✅ 作废激活码
• ✅ 激活会员卡
• ✅ 完整的类型提示和文档