开发者规范(版本 V3)
API 统一访问路径
https://api.simsky.cn/api/v3/
请求规则
- 请求方式必须是 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 |
| 010109 |
API 功能未开通 |
| 010110 |
API 调用的 IP 不对 |
例子:
{
code: 010101,
message: '非法请求，缺少 APP ID 或 APP ID 不正确'
}
参数说明
| 参数 |
说明 |
| app_id |
每个分销商/代理商均会被分配一个 app_id。登录系统在设置 -> 开发设置里面可以看到。 |
| timestamp |
当前调用 API 的时间，是1970 年 1 月 1 日以来到现在的时间，单位是秒。例如: 1509704538 |
| sign |
加密签名。生成算法下面的安全认证规则会详细说明。 |
安全认证规则
本系统 API 访问采用的是 app_id 和 app_secret 加密认证的方式。认证的必须保证下面三个值正确:
- app_id 必须是系统存在的，用来识别身份。
- app_secret 是用来检查身份是否匹配的。登录系统在设置 -> 开发设置里面可以看到，请自己保管好不要泄露给他人。
- timestamp 必须保证和服务器相差的时间不超过1分钟，否则无法调用成功。
- 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×tamp=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/v3/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/v3/sim_cards/get_sim_card_detail
| 参数 |
类型 |
必须 |
说明 |
| iccid |
字符串 |
Y |
ICCID |
返回
| 参数 |
一级参数 |
二级参数 |
类型 |
说明 |
| code |
|
|
字符串 |
返回 code |
| data |
|
|
Object |
返回的卡详情数据 自定义套餐和企业市场返回的结构不一样 |
| 自定义套餐 |
|
|
|
|
|
iccid |
|
字符串 |
卡 ICCID |
|
imei |
|
字符串 |
卡 IMEI |
|
card_type |
|
字符串 |
固定值: customize_product (代表自定义套餐) |
|
carrier_type |
|
字符串 |
运营商类型。(china_telecom - 中国电信, china_mobile - 中国移动, china_unicom - 中国联通) |
|
access_number |
|
字符串 |
接入号 |
|
is_need_verified |
|
字符串 |
是否需要实名认证 true 或 false |
|
is_real_authentication |
|
字符串 |
是否做过实名认证 true 或 false |
|
after_test_status |
|
字符串 |
测试流量用尽后状态 |
|
is_force_stop |
|
字符串 |
是否是强制停机 |
|
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） |
|
status |
|
字符串 |
卡状态。(in_stock: 在库, test_unactivated: 测试待激活, test_activated: 测试激活, test_stopped: 测试关停, tested: 测试结束, wait_activated: 待激活, activated: 已激活, stopped: 停卡, disconnected: 断网, canceled: 销卡) |
|
bind_status |
|
字符串 |
机卡分离状态。0: 是, 1: 否, 空：未查询到机卡分离状态 |
|
power_status |
|
字符串 |
开关机状态。0: 开机, 1: 关机 |
|
online_status |
|
字符串 |
在线状态。00：离线, 01: 在线 |
|
activation_time |
|
字符串 |
卡激活时间。格式: YYYY-MM-DD HH:MM:SS。例: 2018-04-11 18:47:22 |
|
current_products |
|
数组 |
当前套餐。如果没有当前套餐，返回空数组。 |
|
|
order_id |
字符串 |
订单编号 |
|
|
product_number |
字符串 |
套餐编号 |
|
|
name |
字符串 |
套餐名字 |
|
|
service_type |
字符串 |
服务类型。套餐类型是流量的话，有三种值: monthly_plan (自然月套餐)，data_plus (加油包), custom_month(天数月套餐)，custon_day(天数日套餐) |
|
|
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 |
字符串 |
服务类型。套餐类型是流量的话，有三种值: monthly_plan (自然月套餐)，data_plus (加油包), custom_month(天数月套餐)，custon_day(天数日套餐) |
|
|
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) |
|
subscribe_histories |
|
数组 |
订购套餐历史。如果没有订购套餐历史，返回空数组。 |
|
|
product_number |
字符串 |
套餐编号 |
|
|
name |
字符串 |
套餐名字 |
|
|
service_type |
字符串 |
服务类型。套餐类型是流量的话，有三种值: monthly_plan (自然月套餐)，data_plus (加油包), custom_month(天数月套餐)，custon_day(天数日套餐) |
|
|
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_at |
字符串 |
订购时间。(YYYY-MM-DD hh:mm:ss)。 |
|
|
subscribe_price |
浮点型 |
订购金额 |
|
|
is_subscribe |
字符串 |
是否退订 |
| 企业单卡，流量池，NB卡 |
|
|
|
|
|
iccid |
|
字符串 |
卡 ICCID |
|
imei |
|
字符串 |
卡 IMEI |
|
access_number |
|
字符串 |
接入号 |
|
card_type |
|
字符串 |
企业单卡: single_sim_direct 单档位流量池: single_grade_traffic_pool 多档位流量池: multi_grade_traffic_pool |
|
is_need_verified |
|
字符串 |
是否需要实名认证 true 或 false |
|
is_real_authentication |
|
字符串 |
是否做过实名认证 true 或 false |
|
is_force_stop |
|
字符串 |
是否是强制停机 |
|
status |
|
字符串 |
卡状态。(in_stock: 在库, test_unactivated:测试待激活, test_activated:测试激活, test_stopped:测试关停, tested:测试结束, wait_activated: 待激活, activated: 已激活, stopped: 停卡, canceled: 销卡) |
|
bind_status |
|
字符串 |
机卡分离状态。0: 是, 1: 否, 空：未查询到机卡分离状态 |
|
power_status |
|
字符串 |
开关机状态。0: 开机, 1: 关机 |
|
online_status |
|
字符串 |
在线状态。00：离线, 01: 在线 |
|
activation_time |
|
字符串 |
卡激活时间。格式: YYYY-MM-DD HH:MM:SS。例: 2018-04-11 18:47:22 |
|
effective_date |
|
字符串 |
服务周期起始日。(YYYY-MM-DD hh:mm:ss) |
|
expiration_date |
|
字符串 |
服务周期结束日。(YYYY-MM-DD hh:mm:ss) |
|
traffic_limit |
|
字符串 |
卡号限额 |
|
can_send_message |
|
布尔型 |
是否可以发送短信 |
|
product_number |
|
字符串 |
套餐编号 |
|
name |
|
字符串 |
套餐名称 |
|
capacity_unit |
|
字符串 |
容量单位。有三种值：mb(兆字节), gb(千兆字节), count(次) |
|
product_capacity |
|
浮点型 |
套餐容量。如果是 capacity_unit 是 gb，那 product_capacity 是 3 的话，代表就是套餐为 3G 的流量包 |
|
traffic_use |
|
整型 |
已用流量。单位（KB） |
|
traffic_left |
|
整型 |
剩余流量。单位（KB） |
|
traffic_exceed |
|
整型 |
超额流量。单位（KB） |
|
count_usage |
|
整型 |
使用的连接次数。单位（次） |
|
count_left |
|
整型 |
剩余的连接次数。单位（次） |
|
count_exceed |
|
整型 |
超额的连接次数。单位（次） |
|
sms_count |
|
整型 |
收费短信数量 |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 020101 |
该卡不存在或已销卡 |
单卡可订购套餐列表
返回单张 SIM 卡当月和次月的可订购套餐列表。
HTTP 请求 URL
POST /api/v3/sim_cards/terminal_products
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccid |
字符串 |
Y |
ICCID |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| data |
|
数组 |
套餐列表 |
|
product_number |
字符串 |
套餐编号 |
|
name |
字符串 |
套餐名字 |
|
product_category |
字符串 |
套餐类型。自然月/加油包: month/month_plus，天数月：custom_month,天数日：custom_day |
|
product_unit |
字符串 |
套餐单位。有两种值：month(月)，day(日)。天数月或天数日的时候才有值。 |
|
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 |
该卡不存在或已销卡 |
单卡订购套餐
订购自定义套餐
HTTP 请求 URL
POST /api/v3/sim_cards/subscribe_product/customize_product
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccid |
字符串 |
Y |
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 |
该终端产品不存在 |
| 020303 |
该卡未进行实名认证 |
| 020305 |
卡的业务模式不对 |
| 020306 |
分销商余额不足，无法订购套餐 |
| 020308 |
该产品分销商还未定价，不允许订购 |
| 020310 |
订购的卡业务类型不存在 |
| 020311 |
订购卡的业务模式和终端产品业务模式不一致 |
| 020312 |
支付渠道是到平台的无法通过 API 订购 |
| 020313 |
当前套餐未生效或不是月套餐，无法订购加油包 |
| 020314 |
该iccid不存在或已销卡 |
| 020315 |
订购类型不存在 |
| 020316 |
卡已销卡，无法订购套餐 |
| 020318 |
订购卡的运营商类型和终端产品运营商类型不一致 |
| 020319 |
无法在当月最后一天22点以后订购当月加油包 |
| 020321 |
卡已手动断网或手动停机，无法订购套餐 |
| 020322 |
卡的vpn设置与订购加油包的vpn设置不一致，无法订购套餐 |
| 020323 |
支付渠道是分销的无法通过超级管理员 APPID 订购 |
| 020324 |
强制停机的卡，不允许订购套餐 |
| 020390 |
套餐订购失败 |
| 020392 |
订购周期必须是大于0的整数 |
| 020393 |
该卡不可续订套餐 |
| 020395 |
非管理员无法订购测试产品 |
| 020396 |
测试产品只能订购1个周期 |
| 020397 |
当前卡已经使用或正在使用或存在未使用的非测试产品，无法进行订购测试产品 |
| 020398 |
该 iccid 不属于该客户或已销卡 |
| 020399 |
本次订购周期数超过剩余可订购周期数，剩余可订购周期数为XX个 |
单卡 ICCID，电话号码，IMSI 互查
单卡 ICCID、电话号码、IMSI互查。传入单卡ICCID、电话号码、IMSI三个参数中的任一已知参数值，返回三个参数值, 支持三大运营商(移动，联通，电信)。
HTTP 请求 URL
POST /api/v3/sim_cards/query_card_no
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccid |
String |
N |
ICCID |
| phone_number |
String |
N |
电话号码 |
| imsi |
String |
N |
IMSI |
返回
| 参数 |
类型 |
说明 |
| code |
字符串 |
返回 code |
| iccid |
字符串 |
该卡的 ICCID |
| phone_number |
字符串 |
该卡的电话号码 |
| imsi |
字符串 |
该卡的 IMSI |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 020701 |
该卡不存在或已销卡 |
批量更新物联卡信息
支持SIM卡批量更新从运营商处获取的最新的物联卡信息（最多100张，若超过100张，只取前100张处理）
HTTP 请求 URL
POST /api/v3/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 参考
| 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/v3/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: '全部更新失败'
}
批量当前周期流量查询
批量查询当前周期流量
HTTP 请求 URL
POST /api/v3/sim_cards/current_cycle_traffic_use
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
String |
Y |
多个 ICCID，按逗号分割，最多支持 100 个 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| data |
|
数组 |
返回的周期流量数组 |
|
code |
字符串 |
返回 code |
|
iccid |
字符串 |
查询的iccid |
|
traffic_total |
浮点型 |
总共流量 |
|
traffic_use |
浮点型 |
已使用流量。单位(KB) |
|
count_total |
整型 |
总次数 |
|
count_usage |
整型 |
已使用次数。单位(次) |
|
service_begin_time |
字符串 |
当前周期生效时间(YYYY-MM-DD HH::MM:SS) |
|
service_end_time |
字符串 |
当前周期失效时间(YYYY-MM-DD HH::MM:SS) |
|
message |
字符串 |
错误信息 |
| message |
|
字符串 |
错误信息 |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 021001 |
iccids 不能为空 |
一级参数CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 0210001 |
该卡不存在或已销卡 |
| 0210003 |
当前无生效周期 |
批量历史周期流量查询
批量查询历史周期流量
HTTP 请求 URL
POST /api/v3/sim_cards/history_cycle_traffic_use
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
String |
Y |
多个 ICCID，按逗号分割，最多支持 100 个 |
返回
| 参数 |
一级参数 |
二级参数 |
类型 |
说明 |
| code |
|
|
字符串 |
返回 code |
| data |
|
|
数组 |
返回的历史周期信息 |
|
code |
|
字符串 |
返回 code |
|
iccid |
|
字符串 |
查询的iccid |
|
history_cycle |
|
整型 |
卡的历史周期数量，无则显示0 |
|
cycle_data |
|
数组 |
返回卡的历史周期信息 |
|
|
product_id |
整型 |
套餐ID |
|
|
product_name |
字符串 |
套餐名称 |
|
|
traffic_total |
浮点型 |
周期容量，对于后向池卡，此值显示为空，因为其单卡周期内无固定容量（适用于流量卡）。单位(KB) |
|
|
traffic_use |
浮点型 |
已使用流量（适用于流量卡）。单位(KB) |
|
|
count_total |
整型 |
总次数（适用于NB卡）。单位(次) |
|
|
count_usage |
整型 |
已使用次数（适用于NB卡）。单位(次) |
|
|
cycle_begin_time |
字符串 |
历史周期生效时间(YYYY-MM-DD HH::MM:SS) |
|
|
cycle_end_time |
字符串 |
历史周期失效时间(YYYY-MM-DD HH::MM:SS) |
|
message |
|
字符串 |
错误信息 |
| message |
|
|
字符串 |
错误信息 |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 021401 |
iccids 不能为空 |
一级参数CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 0214001 |
该卡不存在或已销卡 |
| 0214002 |
卡无历史周期 |
批量月流量查询
当月或历史月流量查询
HTTP 请求 URL
POST /api/v3/sim_cards/query_traffic_use_by_month
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
字符串 |
Y |
多个 ICCID，按逗号分割，最多支持 100 个 |
| month |
字符串 |
Y |
格式：YYYYMM。可查询范围:201712至当月。 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| month |
|
字符串 |
查询的月份 |
| data |
|
数组 |
返回月流量数组 |
|
code |
字符串 |
返回 code |
|
iccid |
字符串 |
查询的 ICCID |
|
traffic_use |
整型 |
查询月份的已使用流量。单位(KB) |
|
count_usage |
整型 |
查询月份的已使用次数。单位(次) |
|
message |
字符串 |
错误信息 |
| message |
|
字符串 |
错误信息 |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 020801 |
查询月份参数不对 |
| 020802 |
iccids 不能为空 |
一级参数CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 0208001 |
该卡不存在或已销卡 |
| 0208002 |
该月流量不存在 |
批量卡状态查询
批量查询卡状态
HTTP请求的URL
POST /api/v3/sim_cards/query_status
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
字符串 |
Y |
多个 ICCID，按逗号分割，最多支持 100 个 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| data |
|
数组 |
返回卡状态查询结果 |
|
code |
字符串 |
返回 code |
|
iccid |
字符串 |
查询的 ICCID |
|
status |
字符串 |
卡状态。(in_stock: 在库, test_unactivated: 测试待激活, test_activated: 测试激活, test_stopped: 测试关停, tested: 测试结束, wait_activated: 待激活, activated: 已激活, stopped: 停卡, canceled: 销卡) |
|
message |
字符串 |
错误信息 |
| message |
|
字符串 |
错误信息 |
CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 021001 |
iccids 不能为空 |
一级参数CODE参考
| CODE |
消息内容 |
| 0 |
请求成功 |
| 0210001 |
该卡不存在或已销卡 |
批量卡号限额设置
划拨对象对企业单卡或者流量池的卡设置或取消卡号限额，支持批量操作。（最多100张，若超过100张，只取前100张处理）
HTTP请求的URL
POST /api/v3/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 |
限额值单位不适用于此卡 |
取消测试
取消测试流量，支持批量操作。（最多100张，若超过100张，只取前100张处理）
HTTP请求的URL
POST /api/v3/sim_cards/cancel_test
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
字符串 |
Y |
SIM卡的iccid,多个iccid之间用逗号分隔 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| message |
|
字符串 |
处理消息 |
| result |
|
对象数组 |
单张SIM卡调用接口的结果 |
|
iccid |
字符串 |
SIM卡的iccid |
|
code |
字符串 |
返回code |
|
message |
字符串 |
处理结果消息 |
CODE参考
| CODE |
说明 |
| 0 |
请求成功 |
| 021101 |
iccids 不能为空 |
| 021102 |
部分取消测试成功 |
| 021103 |
全部取消测试失败 |
| 021104 |
没有操作权限 |
一级参数CODE参考
| CODE |
说明 |
| 0211001 |
该ICCID不存在或已销卡 |
| 0211002 |
该卡无测试流量 |
| 0211003 |
卡不处于测试待激活、测试激活、测试关停或测试结束状态 |
续期
批量续期（仅支持企业市场，最多100张，若超过100张，只取前100张处理）
HTTP请求的URL
POST /api/v3/sim_cards/renew
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
字符串 |
Y |
SIM 卡的 iccid, 多个ICCID之间用逗号分隔。最多100张。 |
| renew_cycle |
整型 |
Y |
续期周期数，单位是个。 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
批量调用结果 |
| message |
|
字符串 |
批量调用处理消息 |
| result |
|
对象数组 |
提交续期结果数组 |
|
code |
字符串 |
返回 code |
|
iccid |
字符串 |
iccid |
|
message |
字符串 |
处理结果消息 |
参数CODE参考
| CODE |
说明 |
| 0 |
全部续期成功 |
| 021301 |
部分续期成功 |
| 021302 |
全部续期失败 |
| 021303 |
iccid 不能为空 |
| 021304 |
服务周期数量格式错误，请输入1-1000000之间的整数 |
| 021305 |
当前存在划拨任务，暂时不能进行续期，请任务完成后再进行操作 |
| 021306 |
可用额度不足 |
一级参数CODE参考
| CODE |
说明 |
| 0213001 |
该卡不存在或已销卡 |
| 0213002 |
测试流量使用期间不能续期 |
| 0213003 |
此卡尚未使用，不允许续期 |
| 0213004 |
无限周期的卡不允许续期 |
| 0213005 |
此卡不允许续期 |
| 0213006 |
联通：预计销卡月份的26号不能续期 |
| 0213007 |
移动、电信：预计销卡时间的最后三个工作日不能续期 |
| 0213008 |
此卡手动停机，不允许续期 |
| 0213009 |
服务周期到期当天18点后不能续期 |
| 0213010 |
套餐已失效，不允许续期 |
| 0213011 |
套餐未设置终端用户价格，不允许续期 |
| 0213012 |
强制停机的卡，不允许续期 |
| 0213013 |
已经提请销卡的NB卡，不允许续期 |
流量池相关
所有流量池信息(当月信息)
客户账户中所有流量池当月信息，包括单档位独享流量池和多档位共享流量池
HTTP请求的URL
POST /api/v3/sim_cards/pool_list
请求参数：无需额外请求参数
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| traffic_pools |
|
数组 |
流量池数组 |
|
traffic_pool_id |
字符串 |
流量池编号 |
|
update_time |
字符串 |
数据更新时间 |
|
name |
字符串 |
流量池名称 |
|
carrier |
字符串 |
运营商。有三种值： china_mobile(移动)，china_unicom(联通)，china_telecom(电信) |
|
billing_method |
字符串 |
流量池计费方式。有两种值：forward(前向)，backward（后向） |
|
grade_type |
字符串 |
流量池类型。单档位: single，多档位: multi |
|
traffic_total |
浮点型 |
流量池流量总量(KB) |
|
traffic_use |
浮点型 |
已用流量(KB) |
|
traffic_left |
浮点型 |
剩余流量(KB) |
|
traffic_exceed |
浮点型 |
超额流量(KB) |
|
traffic_use_rate |
浮点型 |
流量使用百分比。 |
|
sms_count |
整型 |
收费短信条数 |
|
cards_total_count |
整型 |
卡号总数 |
|
cards_total_count_in_pool |
整型 |
入池卡号总数 (移动前向流量池才有) |
|
current_active_total_count |
整型 |
当前活跃卡总数 |
|
current_activated_count |
整型 |
当前激活卡总数 |
|
current_wait_activated_count |
整型 |
待激活卡总数 |
|
current_disconnected_count |
整型 |
当前断网卡总数 |
|
current_stopped_count |
整型 |
当前停卡总数 |
|
current_cancled_count |
整型 |
当前销卡卡数 |
单个流量池详情
传入流量池编号及查询月份，返回单个流量池详情
HTTP请求URL
POST /api/v3/sim_cards/pool_detail
请求参数
| 参数 |
类型 |
必须 |
说明 |
| traffic_pool_id |
字符串 |
Y |
流量池编号 |
| start_month |
字符串 |
Y |
查询起始月份，可查询范围:201712至当月。格式：YYYYMM。例如：201805（查询起始时间是2018年5月） |
| end_month |
字符串 |
N |
查询结束月份。如果只需查询一个月份，则起始月份与结束月份输入同样的值；如果不输入此参数，则返回起始月份至当前月份的所有月份的数据。 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| traffic_pool_id |
|
字符串 |
流量池编号 |
| name |
|
字符串 |
流量池名称 |
| carrier |
|
字符串 |
运营商。有三种值： china_mobile(移动)，china_unicom(联通)，china_telecom(电信) |
| billing_method |
|
字符串 |
流量池计费方式。有两种值：forward(前向)，backward（后向） |
| grade_type |
|
字符串 |
流量池类型。单档位: single，多档位: multi |
| month_details |
|
数组 |
流量池每个月份的使用详情 |
|
month |
字符串 |
查询月份。格式：YYYYMM |
|
update_time |
字符串 |
数据更新时间。格式：YYYY-MM-DD hh:mm:ss。只有查询月份为当前月份才返回此参数 |
|
cards_total_count |
整型 |
卡号总数 |
|
cards_total_count_in_pool |
整型 |
入池卡号总数 (移动前向流量池才有) |
|
actived_cards_count |
整型 |
活跃卡数 |
|
traffic_total |
浮点型 |
流量池总量(KB) |
|
traffic_use |
浮点型 |
使用流量(KB) |
|
traffic_exceed |
浮点型 |
超额流量(KB) |
|
sms_count |
整型 |
收费短信条数 |
|
total_cost |
浮点型 |
总共费用 |
|
product_cost |
浮点型 |
套餐费用 |
|
sms_cost |
浮点型 |
短信费用 |
CODE参考
| CODE |
说明 |
| 0 |
查询成功 |
| 030201 |
查询的流量池编号不对 |
| 030202 |
查询月份参数不对 |
实名认证相关
批量提交实名认证资料
批量 SIM 卡提交实名认证资料
HTTP 请求 URL
POST /api/v3/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/v3/authentication_records/find_authentication_status
请求参数
| 参数 |
类型 |
必须 |
说明 |
| iccids |
字符串 |
Y |
SIM 卡的 iccid, 多个ICCID之间用逗号分隔。最多100张。 |
返回
| 参数 |
一级参数 |
类型 |
说明 |
| code |
|
字符串 |
返回 code |
| result |
|
数组 |
实名认证查询结果数组 |
|
code |
字符串 |
返回 code |
|
iccid |
字符串 |
SIM卡的 iccid |
|
status |
字符串 |
该卡的实名认证状态。有 passed(审核通过), no_passed(审核未通过) 两种值。 |
|
reason |
字符串 |
审核通过和未通过的理由 |
|
message |
字符串 |
错误消息 |
参数CODE参考
| CODE |
说明 |
| 0 |
请求成功 |
| 040201 |
iccids 不能为空 |
一级参数CODE参考
| CODE |
说明 |
| 0 |
查询成功 |
| 0402001 |
该卡不存在或已销卡 |
| 0402002 |
该卡无需实名认证 |
| 0402003 |
该卡无实名认证申请记录 |
短信相关
发送短信
针对开通短信功能的SIM卡，可调用API批量发送短信。
HTTP 请求 URL
POST /api/v3/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 |
字符串 |
更新的卡状态 |
