添加套餐

基础套餐

适用场景

SIM卡当前没有可以使用的套餐，需要为SIM卡绑定套餐

必要条件

仅支持对所用API key归属企业下的卡片进行操作。

OTA、非OTA（包括多IMSI)卡片均支持操作。

SIM卡服务合约在有效期内。

注意事项

基础套餐的绑定为同步处理，接口同步响应成功代表套餐绑定成功。

当前订购套餐时不允许变更付费类型，如对于预付费的SIM不能订购后付费类型产品。

类型为后付费时，默认无限周期，参数cycles数值不生效

业务规则

套餐绑定后不会对SIM卡状态产生影响。

套餐绑定成功默认不启用，如要开启套餐需要调用API激活（异步）激活套餐。

同一SIM可绑定多个基础套餐，同一个基础套餐可以延续多个周期。

同一时点，同一SIM只能有一个生效的基础套餐。

当SIM绑定了多个基础套餐时，默认将按照绑定时间，优先消耗绑定时间早的基础套餐。

基础套餐有多个周期时，系统会在当前周期结束后切换至下个周期并重置流量。若周期结束前流量消耗完毕，可能会出现在下个周期开始前无法使用流量的情况。

SIM卡被 API 停机v2（异步）后，已绑定的基础套餐将不再提供服务，但其有效期仍然保留并继续消耗。

SIM卡被 API 复机（异步）后，有效期未消耗完的基础套餐将继续提供服务。

关于activate参数的说明

仅支持非OTA卡添加基础套餐时由调用方自定义设置activate参数值

再任意一个流量池中的SIM卡支持自定义设置activate参数值

activate默认值为flase，代表添加基础套餐但不立即激活套餐

activate设置为true，代表添加基础套餐并且立即激活套餐，立即激活套餐为异步处理，处理需要一定时效，且存在失败的概率。可通过响应header中的request_id查询异步处理结果。

不同SIM卡状态添加基础套餐并且设置activate参数为true时的业务处理
关于SIM卡状态SIM

操作前SIM卡状态	是否支持设置为true	业务处理	备注
静默期	是	添加套餐B并激活套餐B
使用期	是	添加套餐B，原使用中套餐A变更为暂停或结束，激活套餐B	此时若不希望暂停或结束套餐A，可将activate设置为flase
暂停期	是	添加套餐B，激活套餐B
停机保	是	添加套餐B，激活套餐B
废弃期（含合约已结束）	否	禁止操作

返回码

主要描述本接口中data.code中的返回码及对应的错误原因

code	message	建议操作
CB-01-0125	已经加入流量池的SIM卡不能进行该操作	联系领科支持人员移除流量池
CB-01-0111	该SIM卡有请求处理中，不允许同时操作	套餐添加成功。但有其他异步处理操作进行中activate激活异常，需要等待后再次调用激活（异步）
CB-00-0000	成功	添加套餐成功
CB-02-0003	该套餐不存在	套餐ID错误或不存在，请更换正确的套餐ID

补充套餐 `pending`

适用场景：

当SIM卡使用中套餐当前周期内流量不够用时，在基础套餐当前周期内进行流量补充。

必要条件：

仅支持对所用API key归属企业下的卡片进行操作。

OTA、非OTA（包括多IMSI)卡片均支持操作。

SIM卡不包含在任一流量池中。

SIM卡支持补充套餐绑定。支持的SIM卡详情咨询领科商务人员。

SIM卡使用中的基础套餐允许绑定该补充套餐。

SIM卡状态必须为Active-live/23（有使用中的副号套餐）。更多关于 SIM生命周期

注意事项：

补充套餐的绑定操作为异步处理，接口同步响应成功代表领科系统接收请求成功。

获取操作异步处理结果的方式：

使用接口响应中的request_id通过GET/sims/async_result/{request_id}进行处理结果查询。

通过notification api回调获取结果 pending

绑定补充套餐异步处理结束完成前，卡片处于锁定状态，此时禁止对同一SIM进行激活、停机、复机、重置等操作。同理，因其他操作被锁定时，卡片将无法绑定补充套餐，请稍后重试。

异步处理过程通常可在几秒内结束，若运营商系统发生网络拥塞等异常，处理时长可达几十分甚至更长。

异步处理结果可能会失败，当结果为失败时，用户可再次发起绑定补充套餐的操作。

对部分特定的SIM卡在运营商的维护周期内，无法绑定补充套餐。详情咨询领科商务人员。

业务规则：

补充套餐绑定异步处理成功后立即生效。

补充套餐作为基础套餐当前周期内的流量补充，不改变周期起止时间，周期结束后自动失效。

在基础套餐的当前周期内，可以添加多次，相同或不相同的补充套餐。

SIM卡被 API 停机v2（异步）后，已绑定的补充套餐将立即失效。

SIM卡被复机（异步）后，无法恢复补充套餐。

已经绑定了有效的补充套餐时，SIM卡不能被加入流量池。

SDK API 调用方式

支持的SDK版本1.0.9

不使用activate参数示例如下：

使用activate参数示例如下：

使用Clinet-token的示例如下：

application/json

Body

data

必需

Any of

object

order_id

string

可选

添加套餐时的业务标识，可作为后续发起指定取消的输入参数

status

object (status)

必需

code

string

必需

message

string | null

必需

detail

必需

示例

{
  "data": {
    "order_id": "SO-123456578845"
  },
  "status": {
    "code": "CB-00-0000",
    "message": "Success",
    "detail": "https://apidoc-cn.iotcube.link/"
  }
}

基础套餐

适用场景

必要条件

注意事项

业务规则

关于activate参数的说明

返回码

补充套餐 `pending`

适用场景：

必要条件：

注意事项：

业务规则：

SDK API 调用方式

请求参数

示例代码

返回响应

添加套餐

基础套餐#

适用场景#

必要条件#

注意事项#

业务规则#

关于activate参数的说明#

返回码#

补充套餐 pending#

适用场景：#

必要条件：#

注意事项：#

业务规则：#

SDK API 调用方式#

请求参数

示例代码

返回响应

基础套餐

适用场景

必要条件

注意事项

业务规则

关于activate参数的说明

返回码

补充套餐 `pending`

适用场景：

必要条件：

注意事项：

业务规则：

SDK API 调用方式