开发者规范(版本 V2)

API 统一访问路径

https://api.simsky.cn/api/v2/

请求规则

• 请求方式必须是 POST
• 请求的 Content-type 请设置成 application/x-www-form-urlencoded;charset=utf-8
• 请求的参数都放在 Body 里面
• 字符编码只支持 UTF-8
• 请求参数必须包含 app_id, timestamp 和 sign 三个参数

返回数据

返回数据格式是 JSON 类型。返回的数据结构里面都有 code 这个字段。code 为 0 的时候，表示正常返回。 非 0 的时候，表示异常返回，message 会返回详细的错误信息。

异常的时候返回的结构都一样：

参数	类型	说明
code	整型	返回 code
message	字符串	异常消息详细

CODE参考

CODE	说明
0	请求成功
010101	APP_ID 没有传，或者传的是错误的 APP_ID
010102	时间戳参数没有传
010103	时间戳参数格式不对
010104	时间戳与服务器时间差别过大
010105	缺少签名参数
010106	签名参数值不正确
010107	API 发生异常
010108	没有权限调用 API （只有分销商和直接企业客户可以调用 API）
010109	API 功能未开通
010110	API 调用的 IP 不对
010111	API路径不正确

例子:

{
  code: 010101,
  message: '非法请求，缺少 APP ID 或 APP ID 不正确'
}

参数说明

参数	说明
app_id	每个分销商/代理商均会被分配一个 app_id。登录系统在设置 -> 开发设置里面可以看到。
timestamp	当前调用 API 的时间，是1970 年 1 月 1 日以来到现在的时间，单位是秒。例如: 1509704538
sign	加密签名。生成算法下面的安全认证规则会详细说明。

安全认证规则

本系统 API 访问采用的是 app_id 和 app_secret 加密认证的方式。认证的必须保证下面三个值正确:

1. app_id 必须是系统存在的，用来识别身份。
2. app_secret 是用来检查身份是否匹配的。登录系统在设置 -> 开发设置里面可以看到，请自己保管好不要泄露给他人。
3. timestamp 必须保证和服务器相差的时间不超过1分钟，否则无法调用成功。
4. sign 是通过下面的算法加密生成的字符串，只有 sign 匹配才能成功调用 API。

sign 生成算法

将发送请求所有的参数，包含 app_id 和 timestamp，按参数名字母升序排列，连接成 key1=value1&key2=value2&...&keyx=valuex 的字符串，拼接好后，最后末尾加上你的 app_secret 的值，然后做 base64 编码，再做下 sha256 加密算法，从而得到了 sign 的值。例子：

app_id = '62120422875257'
app_secret = '2e933aa426f2708982512af311f63435'
timestamp = 1509704538
# 其他应用参数
iccid = '89860316422022752211'
status = 'activated'

# 拼接参数字符串和 app_secret
raw_sign = "app_id=62120422875257&iccid=89860316422022752211&status=activated&timestamp=15097045382e933aa426f2708982512af311f63435"

sign = Digest::SHA256.hexdigest(Base64.strict_encode64(raw_sign))

# 得到的 sign 值: 4de5fddbfbf261a0fa3ae543cde64dddec9108acc87903ef16738d3d14c1a17b

Java 代码示例

JAVA 调用接口代码完整例子，下面的例子调用的是[单卡可订购套餐列表]接口。使用了 apache 的 httpcomponents-client-4.5.5 版本的 http 相关的库。

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Hashtable;
import java.util.List;

import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;

// JAVA 调用接口代码例子
public class ApiExample {

  // 开发设置中可看到 APP_ID 和 APP_SECRET
  private final String APP_ID = "XXXXXXXXXXXX";
  private final String APP_SECRET = "XXXXXXXXXXXXXXXXXXXXXXXXXXX";

  public static void main(String[] args) throws Exception {
    ApiExample http = new ApiExample();
    http.sendPost();
  }

  // HTTP POST请求例子
  private void sendPost() throws Exception {

    String url = "https://api.simsky.cn/api/v2/sim_cards/terminal_products";
    HttpClient client = HttpClientBuilder.create().build();
    HttpPost post = new HttpPost(url);

    // 参数初始化
    List<NameValuePair> urlParameters = new ArrayList<NameValuePair>();
    String currentTime = String.valueOf(System.currentTimeMillis() / 1000);
    Hashtable<String, String> params = new Hashtable<String, String>();
    params.put("app_id", APP_ID);
    params.put("timestamp", currentTime);
    params.put("iccid", "8986031749204104383");

    // 参数按 key 排序
    List<String> keys = new ArrayList<String>(params.keySet());
    Collections.sort(keys);
    String sign = "";
    for (String key : keys) {
      String value = (String) params.get(key);
      urlParameters.add(new BasicNameValuePair(key, value));
      if (!sign.equals("")) {
        sign += "&";
      }
      sign += (key + "=" + value);
    }
    // 生成 sign
    sign += APP_SECRET;
    // 添加加密的 sign
    urlParameters.add(new BasicNameValuePair("sign", SHA256(encode(sign.getBytes()))));

    post.setHeader("Content-type", "application/x-www-form-urlencoded;charset=utf-8");
    post.setEntity(new UrlEncodedFormEntity(urlParameters, Consts.UTF_8));
    // 发送 POST 请求
    HttpResponse response = client.execute(post);

    // 返回结果打印
    System.out.println("\nSending 'POST' request to URL : " + url);
    System.out.println("Post parameters : " + post.getEntity());
    System.out.println("Response Code : " + response.getStatusLine().getStatusCode());

    BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));

    StringBuffer result = new StringBuffer();
    String line = "";
    while ((line = rd.readLine()) != null) {
      result.append(line);
    }

    System.out.println(result.toString());

  }

  // Base 64 加密
  public static String encode(final byte[] bytes) {
    return new String(Base64.encodeBase64(bytes));
  }

  // SHA 256 加密
  public String SHA256(final String strText) {
    return SHA(strText, "SHA-256");
  }

  private String SHA(final String strText, final String strType) {
    // 返回值
    String strResult = null;

    // 是否是有效字符串
    if (strText != null && strText.length() > 0) {
      try {
        // SHA 加密开始
        MessageDigest messageDigest = MessageDigest.getInstance(strType);
        // 传入要加密的字符串
        messageDigest.update(strText.getBytes());
        // 得到 byte 结果
        byte byteBuffer[] = messageDigest.digest();

        // 將 byte 转换 string
        StringBuffer strHexString = new StringBuffer();
        // 遍历 byte buffer
        for (int i = 0; i < byteBuffer.length; i++) {
          String hex = Integer.toHexString(0xff & byteBuffer[i]);
          if (hex.length() == 1) {
            strHexString.append('0');
          }
          strHexString.append(hex);
        }
        // 得到返回結果
        strResult = strHexString.toString();
      } catch (NoSuchAlgorithmException e) {
        e.printStackTrace();
      }
    }
    return strResult;
  }
}

SIM 卡相关

单卡详情

返回单张 SIM 卡详细信息。

HTTP 请求 URL

POST /api/v2/sim_cards/get_sim_card_detail

请求参数

参数	类型	必须	说明
iccid	字符串	Y	SIM 卡的 iccid

返回

参数	一级参数	二级参数	类型	说明
code			字符串	返回 code
monthly_products
	iccid		字符串	卡的 iccid
	imei		字符串	卡的 IMEI
	access_number		字符串	接入号(只有电信有)
	is_real_authentication		布尔型	是否做过实名认证 true 或 false。
	after_test_status		字符串	测试流量用尽后状态
	traffic_test		整型	测试流量。单位(KB)
	traffic_test_used		整型	已用测试流量。单位(KB)
	traffic_test_left		整型	剩余测试流量。单位(KB)
	test_begin_date		日期时间	测试开始时间。(YYYY-MM-DD hh:mm:ss)
	test_end_date		日期时间	测试结束时间。(YYYY-MM-DD hh:mm:ss)
	traffic_total		整型	当月总共流量。单位(KB)
	traffic_use		整型	当月已使用流量。单位(KB)
	traffic_left		整型	当月剩余流量。单位(KB)
	internal_status		字符串	卡内部状态。(in_stock: 在库, test_unactivated: 测试待激活, test_activated: 测试激活, test_stopped: 测试关停, tested: 测试结束, wait_activated: 待激活, activated: 已激活, stopped: 停卡, disconnected: 断网, canceled: 销卡)
	bind_status		字符串	机卡分离状态。0: 是, 1: 否, 空：未查询到机卡分离状态
	activation_time		字符串	卡激活时间。格式: YYYY-MM-DD HH:MM:SS。例: 2018-04-11 18:47:22
	current_month		对象数组	当月套餐。下面是数组单个对象的数据结构。
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值: traffic_package(流量包), traffic_package_plus(加餐包),traffic_pool(流量池)
		service_cycle	字符串	服务周期。有四种值： 1(一个月), 3(一个季度), 6(半年), 12(全年)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		service_capacity	浮点型	服务容量。如果是 capacity_unit 是 gb，那 service_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格。单位：元
	next_month		对象数组	次月套餐。下面是数组单个对象的数据结构。
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值: traffic_package(流量包), traffic_package_plus(加餐包),traffic_pool(流量池)
		service_cycle	字符串	服务周期。有四种值： 1(一个月), 3(一个季度), 6(半年), 12(全年)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		service_capacity	浮点型	服务容量。如果是 capacity_unit 是 gb，那 service_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格。单位：元
	subscribe_histories		对象数组	订购套餐历史。下面是数组单个对象的数据结构。
		terminal_product_name	字符串	订购套餐包名
		subscribe_cycle	字符串	服务周期。有四种值： 1(一个月), 3(一个季度), 6(半年), 12(全年)
		subscribe_no	字符串	订购编号
		effective_date	日期时间	套餐生效时间。(YYYY-MM-DD hh:mm:ss)
		expiration_date	日期时间	套餐失效时间。(YYYY-MM-DD hh:mm:ss)
		source	字符串	来源。（API：通过 API 订购的）
		created_at	日期时间	订购时间。(YYYY-MM-DD hh:mm:ss)
customize_products
	iccid		字符串	卡的 iccid
	imei		字符串	卡的 IMEI
	access_number		字符串	接入号
	is_real_authentication		布尔型	是否做过实名认证 true 或 false。
	traffic_total		整型	本周期总流量。单位(KB)
	traffic_use		整型	本周期已使用流量。单位(KB)
	internal_status		字符串	卡内部状态。(in_stock: 在库, test_unactivated: 测试待激活, test_activated: 测试激活, test_stopped: 测试关停, tested: 测试结束, wait_activated: 待激活, activated: 已激活, stopped: 停卡, canceled: 销卡)
	bind_status		字符串	机卡分离状态。0: 是, 1: 否, 空：未查询到机卡分离状态
	activation_time		字符串	卡激活时间。格式: YYYY-MM-DD HH:MM:SS。例: 2018-04-11 18:47:22
	power_status		字符串	开关机状态。0: 关机, 1: 开机
	online_status		字符串	在线状态。00：离线, 01: 在线
	current_products		对象数组	当前套餐。下面是数组单个对象的数据结构。
		order_id	字符串	订单编号
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值:natural_month_product(自然月套餐)， traffic_package_plus(加油包), customize_product(自定义套餐)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		product_capacity	字符串	套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		cycle	字符串	周期数。例如：2(2个周期); -1(无限周期)
		cycle_list	字符串	周期序列。例如：2/3， 一共3个周期，目前处于第二个周期; 2/-1， 无限周期，目前处于第二个周期
		effective_date	字符串	当前周期的生效时间。(YYYY-MM-DD hh:mm:ss)
		expiration_date	字符串	当前周期的失效时间。(YYYY-MM-DD hh:mm:ss)
	next_products		对象数组	后续套餐。下面是数组单个对象的数据结构。
		order_id	字符串	订单编号
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值:natural_month_product(自然月套餐)， traffic_package_plus(加油包), customize_product(自定义套餐)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		product_capacity	字符串	套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		cycle	字符串	周期数。例如：2
		effective_date	字符串	当前周期的生效时间。(YYYY-MM-DD hh:mm:ss)
		expiration_date	字符串	当前周期的失效时间。(YYYY-MM-DD hh:mm:ss)
		product_price	浮点型	该套餐的价格
	subscribe_histories		对象数组	订购套餐历史。下面是数组单个对象的数据结构。
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值: natural_month_products(自然月套餐), traffic_package_plus(加油包), customize_products(自定义套餐)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		product_capacity	日期时间	套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		cycle	日期时间	周期数
		effective_date	字符串	套餐生效时间。(YYYY-MM-DD hh:mm:ss)
		expiration_date	日期时间	套餐失效时间。(YYYY-MM-DD hh:mm:ss)
		product_price	日期时间	该套餐的价格
		created_at	日期时间	订购时间。(YYYY-MM-DD hh:mm:ss)
		subscribe _price	日期时间	订购金额
single_sim_direct或者single_grade_traffic_pool或者multi_grade_traffic_pool				企业单卡或者单档位独享流量池或者多档位共享流量池单卡详情及套餐使用详情
	iccid		字符串	卡的iccid
	imei		字符串	卡的 IMEI
	access_number		字符串	接入号
	is_real_ authentication		布尔型	是否实名认证：true或者false
	internal_status		字符串	卡内部状态。（in_stock:库存，test_unactivated:测试待激活，test_activated:测试激活，test_stopped:测试关停，tested:测试结束，wait_activated:待激活，activated:已激活，disconnected：断网，stopped:停卡，cancled:销卡）
	bind_status		字符串	机卡分离状态。0: 是, 1: 否, 空：未查询到机卡分离状态
	activation_time		字符串	卡激活时间。（YYYY-MM-DD hh:mm:ss)
	effective_date		字符串	服务周期起始日。(YYYY-MM-DD hh:mm:ss)
	expiration_date		字符串	服务周期结束日。(YYYY-MM-DD hh:mm:ss)
	traffic_limit		字符串	卡号限额
	can_send_message		布尔型	是否开通短信功能：true或者false
	product_number		字符串	套餐编号
	name		字符串	套餐名称
	capacity_unit		字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
	product_capacity		浮点型	套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包
	traffic_use		整型	已用流量。单位（KB）
	traffic_left		整型	剩余流量。单位（KB）
	traffic_exceed		整型	超额流量。单位（KB）
	count_usage		整型	使用的连接次数。单位（次）
	count_left		整型	剩余的连接次数。单位（次）
	count_exceed		整型	超额的连接次数。单位（次）
	charge_message_number		浮点型	收费短信数量
	power_status		字符串	开关机状态。0: 开机, 1: 关机
	online_status		字符串	在线状态。00：离线, 01: 在线

CODE参考

CODE	说明
0	请求成功
020101	该iccid不存在或已销卡

单卡可订购套餐列表

返回单张 SIM 卡当月和次月的可订购套餐列表。

HTTP 请求 URL

POST /api/v2/sim_cards/terminal_products

请求参数

参数	类型	必须	说明
iccid	字符串	Y	SIM 卡的 iccid

返回

参数	一级参数	二级参数	类型	说明
code			字符串	返回 code
monthly_procucts
	current_month		对象数组	当月的套餐列表
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值: traffic_package(流量包), traffic_package_plus(加餐包),traffic_pool(流量池)
		service_cycle	字符串	服务周期。有四种值： 1(一个月), 3(一个季度), 6(半年), 12(全年)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		service_capacity	浮点型	服务容量。如果是 capacity_unit 是 gb，那 service_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格。单位：元
	next_month		对象数组	次月的套餐列表
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		service_type	字符串	服务类型。套餐类型是流量的话，有三种值: traffic_package(流量包), traffic_package_plus(加餐包),traffic_pool(流量池)
		service_cycle	字符串	服务周期。有四种值： 1(一个月), 3(一个季度), 6(半年), 12(全年)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		service_capacity	浮点型	服务容量。如果是 capacity_unit 是 gb，那 service_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格。单位：元
customize_products
	natural_month_products		对象数组	自然月套餐列表
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		service_type	字符串	服务类型。套餐类型是流量的话，有二种值: natural_month_product(自然月套餐), traffic_package_plus(加油包)
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		product_capacity	浮点型	套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格。单位：元
	customize_products		对象数组	自定义套餐列表
		product_number	字符串	套餐编号
		name	字符串	套餐名字
		product_category	字符串	套餐类型。可以是 data_traffic(流量), text_message(短信), voice(语音)
		product_unit	字符串	套餐单位。有两种值：月，日
		product_cycle	字符串	套餐周期。如果 product_unit 是日，product_cycle是3，代表套餐周期是3天的自定义套餐
		capacity_unit	字符串	流量单位。有两种值：mb(兆字节), gb(千兆字节)
		product_capacity	浮点型	套餐容量。如果是 capacity_unit 是 gb，那product_capacity 是 3 的话，代表就是套餐为 3G 的流量包。
		product_price	浮点型	该套餐的价格 单位：元

CODE参考

CODE	说明
0	请求成功
020201	该iccid不存在或已销卡

订购套餐(月流量叠加包)

给单张 SIM 卡订购流量套餐，注意目前仅支持电信卡。此卡必须系统已存在，如果需要实名认证的卡，必须实名认证通过后才能订购套餐。

HTTP 请求 URL

POST /api/v2/sim_cards/subscribe_product/monthly_product

请求参数

参数	类型	必须	说明
iccid	字符串	Y	SIM 卡的 iccid
product_number	字符串	Y	订购套餐编号
is_current_month	字符串	Y	是否订购当月的。值为 true 或者 false
subscribe_cycle	整型	N	订购周期，单位是月。只有订购次月的时候才需要，也可以不传，默认是1。如果订购两个月就是 2
order_no	字符串	N	订单编号(可选)，会返回。

CODE参考

CODE	说明
0	请求成功
020301	该终端产品不存在
020302	该卡和订购产品不属于同一个分销商
020303	该卡未进行实名认证
020304	卡未划拨
020305	卡的业务模式不对
020306	分销商余额不足，无法订购套餐
020307	无法在当月最后一天23点以后订购当月套餐
020308	该产品还未定价，不允许订购
020309	订购的卡跟产品不属于同一个运营商下
020310	订购的卡业务类型不存在
020311	订购卡的业务模式和终端产品业务模式不一致
020312	支付渠道是到平台的无法通过 API 订购
020314	该iccid不存在或已销卡
020316	卡已销卡，无法订购套餐
020317	运营商卡状态不对，不允许订购套餐
020390	套餐订购失败

下面是一个成功返回的例子：

{code: '0', message: '套餐已经预定成功，请等待运营商处理！', order_no: 'XXXXXXX'}

订购套餐(自定义套餐)

给单张 SIM 卡订购自定义流量套餐。此卡必须系统已存在，如果需要实名认证的卡，必须实名认证通过后才能订购套餐。

HTTP 请求 URL

POST /api/v2/sim_cards/subscribe_product/customize_product

请求参数

参数	类型	必须	说明
iccid	字符串	Y	SIM 卡的 iccid
product_number	字符串	Y	订购套餐编号
service_type	字符串	N	仅用以区分自然月套餐和加油包，默认是1，代表自然月套餐，如果写入2，代表加油包
subscribe_cycle	整型	Y	订购周期，单位是个。默认是1。如果订购两个周期就是 2
order_no	字符串	N	订单编号(可选)，会返回。

返回

参数	类型	说明
code	String	返回 code
message	字符串	处理结果消息
order_no	字符串	参数传了的话，会返回
order_id	字符串	系统订单编号

CODE参考

CODE	说明
0	请求成功
020301	该终端产品不存在
020302	该卡和订购产品不属于同一个分销商
020303	该卡未进行实名认证
020304	卡未划拨
020305	卡的业务模式不对
020306	分销商余额不足，无法订购套餐
020308	该产品还未定价，不允许订购
020309	订购的卡跟产品不属于同一个运营商下
020310	订购的卡业务类型不存在
020311	订购卡的业务模式和终端产品业务模式不一致
020312	支付渠道是到平台的无法通过 API 订购
020313	当前套餐未生效或不是月套餐，无法订购加油包
020314	该iccid不存在或已销卡
020315	订购类型不存在
020316	卡已销卡，无法订购套餐
020390	套餐订购失败

下面是一个成功返回的例子：

{code: '0', message: '套餐已经订购成功!', order_no: 'XXXXXXX'}

更新物联卡信息

支持SIM卡批量更新从运营商处获取的最新的物联卡信息（最多100张，若超过100张，只取前100张处理）

HTTP 请求 URL

POST /api/v2/sim_cards/update_sim_cards

请求参数

参数	类型	必须	说明
iccids	字符串	Y	SIM卡的iccid,多个ICCID之间用逗号分隔

返回

参数	一级参数	类型	说明
code		字符串	返回 code
message		字符串	处理消息
result		对象数组	单张SIM卡调用接口的处理结果
	iccid	字符串	SIM卡的iccid
	code	字符串	返回code
	message	字符串	处理结果消息

CODE 参考

CODE	说明
0	请求成功
020401	iccids 不能为空
020402	部分更新成功
020403	全部更新失败

一级参数 CODE 参考

0204001 | 该ICCID不存在或已销卡

更新物联卡信息调用结果返回如下：

{code: '020402', result:
   [{"iccid":"89860316422022752211",code: '0', message: "调用接口成功，处理结果请至系统页面查看"},
    {"iccid":"89860316422022752232",code: '020401', message: "该iccid不存在或已销卡"}],
 message: 部分更新成功'
}

卡号更新状态

支持SIM 卡批量更新卡状态（最多100张，若超过100张，只取前100张处理），支持三大运营商(移动，联通，电信)。目前支持：停机、复机、断网、恢复上网。 停机、复机、断网、恢复上网的执行结果通过平台通知给到，具体参考平台通知相关部分。

HTTP 请求 URL

POST /api/v2/sim_cards/update_status

请求参数

参数	类型	必须	说明
iccids	字符串	Y	SIM卡的iccid,多个ICCID之间用逗号分隔
operation	字符串	Y	请求操作。有以下五种值：suspend(停机),resume（复机）,net_down（断网）,net_up（恢复上网)

返回

参数	一级参数	类型	说明
code		字符串	返回 code
message		字符串	处理结果消息
result		对象数组	单张SIM卡调用接口的结果
	iccid	字符串	SIM卡的iccid
	code	字符串	返回 code
	message	字符串	处理结果消息

CODE参考

CODE	说明
0	请求成功
020601	iccids 不能为空
020602	部分更新成功
020603	全部更新失败

一级CODE参考

CODE	说明
0206001	停机任务处理中，无需重复操作
0206002	复机任务处理中，无需重复操作
0206003	断网任务处理中，无需重复操作
0206004	恢复上网任务处理中，无需重复操作
0206006	非法请求，操作方法不正确
0206007	该iccid不存在或已销卡
0206008	停机方式是手动停机，且在服务期内才能复机
0206009	断网方式是手动断网，且在服务期内才能恢复上网
0206012	卡已停机，无需重复操作
0206013	卡未停机，不能执行复机操作
0206014	卡已断网，无需重复操作
0206015	卡未断网，不能执行恢复上网操作
0206016	卡已激活，无需重复操作
0206017	没有该卡的操作权限
0206019	待激活的卡，不能进行停机
0206020	此卡已经销卡，无须提请销卡
0206021	此卡已经提请销卡申请，不能重复申请
0206022	停机保号时间不在服务周期内，提请销卡申请失败
0206023	移动卡测试期沉默期无法停机
0206024	移动卡测试期沉默期无法复机
0206025	移动卡测试期沉默期无法断网
0206026	移动卡测试期沉默期无法恢复上网
0206027	非停机状态的卡，不能进行复机
0206028	未激活的卡，不能进行断网
0206029	未激活的卡，不能进行恢复上网
0206030	移动流量池卡月底23点后不允许停机
0206031	此卡已经销卡，不能进行断网
0206032	平台强制停机无法复机
0206033	已停机的卡，不能进行断网
0206034	未实名认证的卡，不能进行复机
0206035	未实名认证的卡，不能进行停机
0206036	未实名认证的卡，不能进行断网
0206037	未实名认证的卡，不能进行恢复上网
0206038	平台强制停机，不能进行恢复上网
0206040	已销卡的卡，不能进行停机
0206041	未激活的卡，不能进行提请销卡
0206042	沉默期内只有测试激活状态可以进行停机
0206043	沉默期内只有关停状态可以进行复机
0206044	测试激活期间不能进行强制停机
0206045	测试流量使用期间不能断网
0206046	测试流量使用期间不能恢复上网
0206090	卡状态更新失败

停机调用成功返回如下：

{ code: '020603', result:
          [{ "iccid": "89860401101701240250",  "code": "020612", "message": "卡已停机，无需重复操作"},
        {"iccid": "898604011017012","code": "020607", "message": "该iccid不存在或已销卡“}],
  message: '全部更新失败'
}

单卡ICCID、电话号码、IMSI互查

单卡 ICCID、电话号码、IMSI互查。传入单卡ICCID、电话号码、IMSI三个参数中的任一已知参数值，返回三个参数值, 支持三大运营商(移动，联通，电信)。

HTTP 请求 URL

POST /api/v2/sim_cards/query_card_no

请求参数

参数	类型	必须	说明
iccid	字符串	N	SIM 卡的 iccid
phone_number	字符串	N	SIM卡的电话号码
imsi	字符串	N	SIM卡的imsi

返回

参数	类型	说明
code	字符串	返回 code
iccid	字符串	该卡的 iccid
phone_number	字符串	该卡的电话号码
imsi	字符串	该卡的imsi

CODE参考

CODE	说明
0	请求成功
020701	该卡不存在或已销卡

月流量查询

历史月或当月流量使用详情

HTTP 请求 URL

POST /api/v2/sim_cards/query_traffic_use_by_month

请求参数

参数	类型	必须	说明
iccid	字符串	Y	SIM卡的iccid
month	字符串	Y	格式：YYYYMM。可查询范围:201712至当月。

返回

参数	类型	说明
code	字符串	返回code
traffic_use	整型	已使用流量。单位（KB)
month	字符串	查询月份

CODE参考

CODE	说明
0	请求成功
020801	查询月份参数不对
020802	该卡不存在或已销卡

查询成功结果返回列子如下：

{code: '0', traffic_use: 29991, month: "201806"}

月份参数未输入或格式不对的话返回错误信息如下：

{code: 020701, message: "查询月份参数不对，请检查"}

卡号限额

划拨对象对企业单卡或者流量池的卡设置或取消卡号限额，支持批量操作。（最多100张，若超过100张，只取前100张处理）

HTTP请求的URL

POST /api/v2/sim_cards/set_traffic_limit

请求参数

参数	类型	必须	说明
iccids	字符串	Y	SIM卡的iccid,多个iccid之间用逗号分隔
limit_type	字符串	Y	设置限额。三种值：limit_percent (卡号档位 单位：%)、limit_absolute_value(容量绝对值)、limit_cancle (取消限额)
capacity_unit	字符串	N	容量单位。若limit_type的值是limit_absolute_value，此字段必填。容量单位。有三种值：mb(兆字节), gb(千兆字节), count(次)
limit_value	浮点型	N	限额值（限额值必须大于0且不能超过小数点后两位）。若limit_type的值是limit_cancle，此字段不填。若limit_type的值是limit_percent，limit_value是80的时候，代表限额值是套餐容量的80%；若limit_type的值是limit_absolute_value，capacity_unit 是gb,limit_value是80的时候，代表限额值是80gb

返回

参数	一级参数	类型	说明
code		字符串	返回 code
message		字符串	处理消息
result		对象数组	单张SIM卡卡号限额结果
	iccid	字符串	SIM卡的iccid
	code	字符串	返回code
	message	字符串	处理结果消息

CODE参考

CODE	说明
0	请求成功
020901	iccids不能为空
020902	限额类型错误
020903	限额值必须大于0且不能超过小数点后两位
020904	容量单位错误, 有三种值：mb(兆字节), gb(千兆字节), count(次)
020905	部分设置成功
020906	全部设置失败
020907	容量单位是次，限制值必须为正整数

一级参数CODE参考

CODE	说明
0209001	该ICCID不存在或已销卡
0209002	卡号的业务模式不支持卡号限额
0209003	没有该卡的操作权限
0209004	该卡已经销卡, 无需设置卡号限额
0209005	限额值单位不适用于此卡

流量池相关

所有流量池信息（当月信息）

客户账户中所有流量池当月信息，包括单档位独享流量池和多档位共享流量池

HTTP请求的URL

POST /api/v2/sim_cards/pool_list

请求参数：无需额外请求参数

返回

参数	一级参数	类型	说明
code		字符串	返回code
traffic_pools		对象数组	流量池。下面是数组单个对象的数据结构
	id	字符串	流量池编号
	update_time	字符串	数据更新时间。格式：YYYY-MM-DD hh:mm:ss
	name	字符串	流量池名称
	carrier	字符串	运营商。有三种值：cmcc(移动)，unicom(联通)，chinanet(电信)
	billing_method	字符串	流量池计费方式。有两种值：forward(前向)，backward（后向）
	excess_price	浮点型	超额流量资费。单位(元/gb)
	capacity_unit	字符串	流量单位。值：mb(兆字节)
	traffic_total	浮点型	流量池总流量
	traffic_use	浮点型	已用流量
	traffic_left	浮点型	剩余流量
	traffic_exceed	浮点型	超额流量
	traffic_use_rate	浮点型	流量使用百分比。单位：%
	charge_message_number	整型	收费短信条数
	cards_total_count	整型	卡号总数
	current_ wait_activated_count	整型	当前待激活卡数
	current _activated_count	整型	当前激活卡数
	current _disconnected_count	整型	当前断网卡数
	current_stopped_count	整型	当前停卡卡数
	current_cancled_count	整型	当前销卡卡数
	current_activated_count_rate	整型	当前激活卡数百分比。单位：%

CODE参考

CODE	说明
0	请求成功

单个流量池详情

传入流量池编号及查询月份，返回单个流量池详情

HTTP请求URL

POST /api/v2/sim_cards/pool_detail

请求参数

参数	类型	必须	说明
id	字符串	Y	流量池编号
start_month	字符串	Y	查询起始月份，可查询范围:201712至当月。格式：YYYYMM。例如：201805（查询起始时间是2018年5月）
end_month	字符串	N	查询结束月份。如果只需查询一个月份，则起始月份与结束月份输入同样的值；如果不输入此参数，则返回起始月份至当前月份的所有月份的数据。

返回

参数	一级参数	类型	说明
code		字符串	返回code
id		字符串	流量池编号
name		字符串	流量池名称
carrier		字符串	运营商。有三种值：cmcc(移动)，unicom(联通)，chinanet(电信)
billing_method		字符串	流量池计费方式。有两种值：forward(前向)，backward（后向）
excess_price		浮点型	超额流量资费。单位：元/GB
month_detail		对象数组	流量池月份使用详情。下面是数组单个对象的数据结构
	month	字符串	查询月份。格式：YYYYMM
	update_time	字符串	数据更新时间。格式：YYYY-MM-DD hh:mm:ss。只有查询月份为当前月份才返回此参数
	cards_total_count	整型	卡号总数
	actived_cards_count	整型	活跃卡号总数
	inactive_cards_count	整型	非活跃卡号总数
	capacity_unit	字符串	流量单位。值：mb(兆字节)
	traffic_total	浮点型	流量池总流量
	traffic_use	浮点型	使用流量
	traffic_exceed	浮点型	超额流量
	charge_message_number	浮点型	收费短信条数
	total_cost	浮点型	总费用。单位：元
	product_cost	浮点型	套餐流量费用。单位：元
	exceed_cost	浮点型	超额流量费用。单位：元
	message_cost	浮点型	短信费用。单位：元

CODE参考

CODE	说明
0	请求成功
030201	查询的流量池编号错误
030202	查询月份参数不对

实名认证相关

批量提交实名认证资料

批量 SIM 卡提交实名认证资料

HTTP 请求 URL

POST /api/v2/authentication_records/upload_authentication_information

请求参数

参数	类型	必须	说明
iccids	字符串	Y	SIM 卡的 iccid, 多个ICCID之间用逗号分隔。最多5张。
user_name	字符串	N	认证人的名字
identity_card	字符串	N	认证人的身份证号码
phone_number	字符串	Y	认证人的联系手机号码

返回

参数	一级参数	类型	说明
code		字符串	批量调用结果
message		字符串	批量调用处理消息
result		对象数组	提交实名认证资料结果数组
	code	字符串	返回 code
	iccid	字符串	iccid
	message	字符串	处理结果消息

参数CODE参考

CODE	说明
0	全部处理成功
040101	iccids，手机号码不能为空
040103	手机号码格式不对
040104	部分处理失败
040105	全部处理失败

一级参数CODE参考

CODE	说明
0	请求成功
0401001	该卡不存在或已销卡
0401002	该卡已审核认证通过
0401003	该卡无需实名认证
0401004	手机号码已被8张卡使用了，无法被其他卡号使用了

认证数据接收成功返回如下：

{code: '0', result: [{code: '0', iccid: '89860316422022752211', message: '认证数据接收成功'}], message: '全部处理成功'}

批量查询实名认证状态

批量 SIM 卡查询实名认证状态

HTTP 请求 URL

POST /api/v2/authentication_records/find_authentication_status

请求参数

参数	类型	必须	说明
iccids	字符串	Y	SIM 卡的 iccid, 多个ICCID之间用逗号分隔。最多100张。

返回

参数	一级参数	类型	说明
code		字符串	批量查询结果
message		字符串	批量查询处理消息
result		对象数组	实名认证查询结果数组
	code	字符串	返回 code
	iccid	字符串	SIM 卡的 iccid
	status	字符串	该卡的状态。有 passed(审核通过), no_passed(审核未通过) 两种值
	reason	字符串	审核通过和未通过的理由
	message	字符串	错误消息

参数CODE参考

CODE	说明
0	全部查询成功
040201	iccids不能为空

一级参数CODE参考

CODE	说明
0	请求成功
0402001	该卡不存在或已销卡
0402002	该卡无需实名认证
0402003	该卡无实名认证申请记录

查询结果返回例子如下：

{code: '0', result: [code: '0', iccid: '89860316422022752211', status: 'passed', reason: '审核已通过'], message: '全部查询成功'}

短信接口

发送短信

针对开通短信功能的SIM卡，可调用API批量发送短信。

HTTP 请求 URL

POST /api/v2/sms/send_sms

请求参数

参数	类型	必须	说明
phone_numbers	字符串	Y	SIM 卡的 电话号码，多个电话号码之间用逗号分隔
message	字符串	Y	发送的短信内容

返回

参数	类型	说明
code	整型	返回code
message	字符串	处理结果消息

CODE参考

CODE	说明
0	短信发送预定成功，请等待平台处理！
050101	短信内容不能为空
050102	手机号码不能为空
050103	输入的手机号码有误，或卡不存在或已销卡
050104	卡未开通短信功能

平台通知相关

分销商可以设置通知的服务器 URL 地址，平台一些操作(例: SIM 卡更新状态)后，会主动通知该地址返回操作结果。

SIM 卡更新状态执行结果通知

当调用 SIM 卡更新状态接口,会以主动通知形式发送给分销商设置的 URL。

HTTP POST请求，返回数据格式是 JSON 类型

接受参数

参数	类型	说明
code	整型	返回 code
result	字符串	返回订购结果（'success'或'fail'）
notify_type	字符串	固定值: update_status
iccid	字符串	单卡的 ICCID
status	字符串	更新的卡状态