连接您的卡务系统
卡片信息、流量用量与业务操作,
通过统一接口接入您的应用。
快速接入 01
- 开通 API 权限
企业管理员在代理商资料的 API 设置中启用 API,配置可调用接口、调用 IP 和查询/操作频率,向接入方提供 API ID 与 API SECRET。账号仅可访问已授权的卡片与流量池。
- 取得企业专属地址
从企业系统顶部的“API 文档”进入,本页将显示对应企业地址。分享此文档链接即可保留企业代码。未登录的开发者无需平台账号即可阅读文档。
- 从服务端发起请求
所有接口使用 POST,参数放在
application/x-www-form-urlencoded请求体中,响应为 JSON。API SECRET 仅用于本地签名,不能作为参数发送。
https://www.simbest.cn/open-api/{企业代码}/api/v1请从企业系统顶部进入文档,取得本企业的完整地址。
企业代码负责路由到企业独立服务,不是认证凭据。公网地址由平台统一维护,接入方无需填写内部 IP、数据库或容器地址。仅支持服务端调用,不开放跨域浏览器调用。
签名与鉴权 02
每个请求都包含以下公共参数,业务参数也必须参与签名。
| 参数 | 类型 | 说明 |
|---|---|---|
api_id | string | 企业分配的 API ID。 |
timestamp | string | Unix 秒级时间戳,与服务器时间差不超过 60 秒。 |
sign | string | 64 位小写十六进制签名。 |
- 移除
sign;对已解码的参数值去除首尾空白,忽略空值。 - 按参数名 ASCII 升序排列,拼接为
key=value&key=value。 - 在末尾直接追加 API SECRET(不添加 & 或其他分隔符)。
- 对完整字符串做 UTF-8 编码和标准 Base64 编码。
- 对 Base64 文本计算 SHA-256,转为小写十六进制,得到 sign。
完整调用示例 03
示例查询卡号列表,不执行开停卡或套餐操作。将 API ID、SECRET 通过服务端环境变量提供;示例不会在此页面执行。
cURL 请求结构
先按上述规则计算签名,将结果设置为 SIGN。不要把 SECRET 放进 URL。
响应与异步任务 04
{
"code": "0",
"message": "查询成功",
"result": { "iccids": ["示例ICCID"] }
}code是字符串,"0"表示成功;HTTP 200 仍可能包含业务失败。- 批量接口的
result通常为数组;部分成功时外层 code 非 0,仍需逐卡检查iccid / code / message。 - 断网、恢复联网、停复机、续期、限速、解绑、开关语音等返回逐卡
task_id。受理成功不代表运营商执行成功。 - 使用
/sim_cards/get_task查询任务:0 待处理、1 进行中、2 成功、3 失败。建议间隔 3–5 秒轮询,并遵守账号频率限制。 - 操作接口不提供客户端幂等键。网络超时后先核查任务/后台操作记录,再决定是否重试,避免重复续费等操作。
- 错误 010008 表示超出调用限制,建议退避重试。查询、操作的分钟配额由企业分别配置。
卡片状态枚举
life_cycle:0 库存、1 沉默期、2 可用、3 待续期订购、4 待销卡、5 已销卡、6 测试期。
net_status:0 正常、1 强制断网、2 客户断网、3 单卡超套停、4 服务结束、5 提请销卡、6 销卡、7 共享超套停、8 主动停机、9 停机保号。
接口参考 05
下列路径追加到企业 API 基础地址之后;所有接口均为 POST。
没有找到匹配的接口,请调整搜索内容。
错误码参考 06
业务错误以实际返回的 message 为准。网关错误使用 HTTP 4xx/503,业务错误通常返回 HTTP 200。以下错误码从服务端定义同步生成。
| code | message |
|---|