跳转到主要内容
1签 (OneSign)

开通与续费签名服务

本页内容

签名服务决定应用可以使用的套餐、有效期和安装量权益。您可以使用账号余额购买,也可以核销已有开通密钥;开通或续费成功后,再单独提交签名任务。

选择开通方式

方式适用场景需要确认的内容
余额购买从应用可选套餐中选择服务期限,或按天购买套餐、时长、金额单位、退款规则和扣款金额
开通密钥已经取得适用于企业签名的开通码密钥对应的套餐和期限,以及不支持退款

开通密钥是兑换签名服务的凭证,与调用 API 使用的 AccessKey 不同。两种方式都需要明确授权,且不会自动创建签名任务。

前提条件

已创建企业签名应用并完成 SDK 初始化。查询权益需要 enterprise:ReadEntitlements;余额购买需要报价和付款权限、可用余额、预算及允许的来源 IP;密钥核销需要 enterprise:RedeemKeys 和该功能的接入许可。详细动作见各接口说明。

步骤一:查询当前权益

先读取套餐、签名有效期和安装设备上限。用 installation_limit.unlimited 判断是否不限设备数,不能把整个 installation_limit 对象当作一个数字。

Python SDK
def read_entitlement(client, app_id):
    data = client.get_signing_entitlement(app_id)["data"]
    limit = data["installation_limit"]
    # unlimited 表示是否不限安装设备数;maximum_devices 是当前上限。
    return {
        "state": data["state"],
        "plan_name": data["plan_name"],
        "expires_at": data["sign_expires_at"],
        "unlimited": limit["unlimited"],
        "maximum_devices": limit["maximum_devices"],
        "statistics_state": data["statistics_state"],
    }

statistics=null 表示没有返回统计对象,不能显示成零安装。请结合 statistics_state 判断授权或数据状态。签名权益期限与证书自身期限也是两回事,后续提交签名时仍会重新检查。

方式一:使用余额开通或续费

  1. 调用 列出套餐和按天价格取得当前可用套餐和退款规则。需要估算时,可调用 查询套餐参考价;参考价格本身不能用于付款。
  2. 使用所选 sku 创建购买报价,保存报价 ID、金额、价格修订号和金额单位修订号。
  3. 向使用者展示套餐、有效期、金额单位、金额及退款规则。取得确认后,以原报价数据提交付款。
  4. 保存付款回执中的订单 ID,重新查询当前权益,确认开通或续费结果。
Python SDK
def prepare_purchase(client, app_id, sku, quote_key, days=None):
    return client.create_purchase_quote(
        app_id, sku, quote_key, days=days
    )["data"]

def pay_confirmed_purchase(client, app_id, shown_quote, pay_key, confirmed):
    if confirmed is not True:
        raise ValueError("请先向使用者展示报价并取得付款确认")
    # 使用已展示并确认的原报价,不能在付款前悄悄替换金额或单位。
    return client.pay_purchase_quote(
        app_id, shown_quote["id"], shown_quote["amount"],
        shown_quote["pricing_revision"], shown_quote["currency"]["revision"],
        pay_key,
    )["data"]

示例中报价创建键与付款键分别对应两次写操作,需各自保存。金额是十进制字符串,请保留接口原值,不用浮点数重新计算。报价有效期以 expires_at 为准;创建报价不会冻结余额。

按天购买

仅当价格接口返回可用的按天套餐时,才让使用者填写天数。使用该套餐的 sku 和允许范围内的 days 创建报价;不要把示例天数当作固定限制。

先读取价格或权益中的 refund_policy.daily_supported。为 false 时,应在确认购买前提示“按天不支持退款,请谨慎选择”;为 true 时,仍需符合实际订单退款资格。最终资格由退款查询接口给出。

方式二:使用开通密钥

  1. 取得真实开通密钥,让使用者确认核销且不支持退款。密钥不要写入日志或网页源码。
  2. 保存本次核销的请求信息和幂等键,提交核销请求。
  3. 保存返回的核销回执 ID,再查询当前签名权益。
Python SDK
def redeem_confirmed_code(client, app_id, code, write_key, confirmed):
    if confirmed is not True:
        raise ValueError("请先确认使用开通密钥且不支持退款")
    return client.redeem_signing_key(
        app_id, code, confirm_non_refundable=True,
        idempotency_key=write_key,
    )["data"]

套餐和期限由密钥决定,不能通过请求改成其他套餐。已有有效服务按规则延长期限;服务已失效时从本次成功开通开始计算。此操作不扣站内余额,也不自动签名。

密钥核销的调用限制

使用已获授权的长期 AccessKey(AKP)。临时只读凭据和 OAuth 终端不能核销。每账号每分钟最多尝试五次,错误尝试也计入限额;接入程序应避免连续试码。

确认结果与恢复

遇到的情况处理方法
付款请求超时用原报价 ID 查询 查询购买报价及付款结果,检查付款回执。不要换报价重复扣款。
核销响应丢失,尚无回执 ID使用原应用、原密钥、原幂等键和相同正文重试;认证时间与 nonce 重新生成。
已经保存核销回执 ID调用 查询密钥核销回执。同一 API 应用下可轮换长期 AccessKey 后查询,其他 API 应用不能读取此回执。
密钥返回已使用先检查原操作是否已成功。使用新幂等键重复核销不能恢复旧响应。

回执记录的是当次授予结果,当前权益可能已因后续续费或退款变化。签名前再查询当前权益,接着阅读提交签名与获取结果。

相关接口