添加套餐

基础套餐

适用场景

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

  必要条件

1. 仅支持对所用API key归属企业下的卡片进行操作。
2. OTA、非OTA（包括多IMSI)卡片均支持操作。
3. SIM卡服务合约在有效期内。

   注意事项

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

业务规则

1. 套餐绑定后不会对SIM卡状态产生影响。
2. 套餐绑定成功默认不启用，如要开启套餐需要调用API激活（异步）激活套餐。
3. 同一SIM可绑定多个基础套餐，同一个基础套餐可以延续多个周期。
4. 同一时点，同一SIM只能有一个生效的基础套餐。
5. 当SIM绑定了多个基础套餐时，默认将按照绑定时间，优先消耗绑定时间早的基础套餐。
6. 基础套餐有多个周期时，系统会在当前周期结束后切换至下个周期并重置流量。若周期结束前流量消耗完毕，可能会出现在下个周期开始前无法使用流量的情况。
7. SIM卡被 API 停机v2（异步）后 ，已绑定的基础套餐将不再提供服务，但其有效期仍然保留并继续消耗。
8. SIM卡被 API 复机（异步）后，有效期未消耗完的基础套餐将继续提供服务。

关于activate参数的说明

1. 仅支持非OTA卡添加基础套餐时由调用方自定义设置activate参数值
2. 再任意一个流量池中的SIM卡支持自定义设置activate参数值
3. activate默认值为flase，代表添加基础套餐但不立即激活套餐
4. activate设置为true，代表添加基础套餐并且立即激活套餐，立即激活套餐为异步处理，处理需要一定时效，且存在失败的概率。可通过响应header中的request_id查询异步操作结果。
5. 不同SIM卡状态添加基础套餐并且设置activate参数为true时的业务处理
   关于SIM卡状态SIM

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

5. 主要同步返回码

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

补充套餐 pending

适用场景：

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

  必要条件：

1. 仅支持对所用API key归属企业下的卡片进行操作。
2. OTA、非OTA（包括多IMSI)卡片均支持操作。
3. SIM卡不包含在任一流量池中。
4. SIM卡支持补充套餐绑定。支持的SIM卡详情咨询领科商务人员。
5. SIM卡使用中的基础套餐允许绑定该补充套餐。
6. SIM卡状态必须为Active-live/23（有使用中的副号套餐）。更多关于 SIM生命周期

   注意事项：

7. 补充套餐的绑定操作为异步处理，接口同步响应成功代表领科系统接收请求成功。
8. 获取操作异步处理结果的方式：
9. 使用接口响应中的request_id通过GET/sims/async_result/{request_id}进行处理结果查询。
10. 通过notification api回调获取结果 pending
11. 绑定补充套餐异步处理结束完成前，卡片处于锁定状态，此时禁止对同一SIM进行激活、停机、复机、重置等操作。同理，因其他操作被锁定时，卡片将无法绑定补充套餐，请稍后重试。
12. 异步处理过程通常可在几秒内结束，若运营商系统发生网络拥塞等异常，处理时长可达几十分甚至更长。
13. 异步处理结果可能会失败，当结果为失败时，用户可再次发起绑定补充套餐的操作。
14. 对部分特定的SIM卡在运营商的维护周期内，无法绑定补充套餐。详情咨询领科商务人员。

    业务规则：

15. 补充套餐绑定异步处理成功后立即生效。
16. 补充套餐作为基础套餐当前周期内的流量补充，不改变周期起止时间，周期结束后自动失效。
17. 在基础套餐的当前周期内，可以添加多次，相同或不相同的补充套餐。
18. SIM卡被 API 停机v2（异步） 后 ，已绑定的补充套餐将立即失效。
19. SIM卡被 复机（异步）后，无法恢复补充套餐。
20. 已经绑定了有效的补充套餐时，SIM卡不能被加入流量池。

SDK API 调用方式

支持的SDK版本1.0.9

1. 不使用activate参数示例如下：

   PartnerClient client = new PartnerClient(accessKey,privateKey)
   client.v1().service().addBundle(new AddBundle(1, "89314404000894487785", "DP20201117003762", 10, 3));
   client.v2().service().addBundle(new AddBundle(1, "89314404000894487785", "DP20201117003762", 10, 3));
   

2. 使用activate参数示例如下：

   client.v1().service().addBundle(new AddBundle(1, "89314404000894487785", "DP20201117003762", 10, 3, true));
   client.v2().service().addBundle(new AddBundle(1, "89314404000894487785", "DP20201117003762", 10, 3, true));
   

3. 使用Clinet-token的示例如下：
   ```java

final AddBundle addBundle = new AddBundle(1, "89852202306300013435", "LP20230712004099", 10, 3, true);
addBundle.setClientToken("123456");

{
  "bundle_id": "LP09823222320",
  "bundle_type": 10,
  "cycles": 3,
  "activate": true
}

{
  "data": null,
  "status": {
    "code": "CB-00-0000",
    "message": "Success",
    "detail": null
  }
}