SIMBEST 开发者文档
SIMBEST OPEN API / V1

连接您的卡务系统

卡片信息、流量用量与业务操作,
通过统一接口接入您的应用。

19 个接口签名鉴权企业数据隔离

快速接入 01

  1. 开通 API 权限

    企业管理员在代理商资料的 API 设置中启用 API,配置可调用接口、调用 IP 和查询/操作频率,向接入方提供 API ID 与 API SECRET。账号仅可访问已授权的卡片与流量池。

  2. 取得企业专属地址

    从企业系统顶部的“API 文档”进入,本页将显示对应企业地址。分享此文档链接即可保留企业代码。未登录的开发者无需平台账号即可阅读文档。

  3. 从服务端发起请求

    所有接口使用 POST,参数放在 application/x-www-form-urlencoded 请求体中,响应为 JSON。API SECRET 仅用于本地签名,不能作为参数发送。

企业 API 基础地址
https://www.simbest.cn/open-api/{企业代码}/api/v1

请从企业系统顶部进入文档,取得本企业的完整地址。

企业代码负责路由到企业独立服务,不是认证凭据。公网地址由平台统一维护,接入方无需填写内部 IP、数据库或容器地址。仅支持服务端调用,不开放跨域浏览器调用。

签名与鉴权 02

每个请求都包含以下公共参数,业务参数也必须参与签名。

参数类型说明
api_idstring企业分配的 API ID。
timestampstringUnix 秒级时间戳,与服务器时间差不超过 60 秒。
signstring64 位小写十六进制签名。
  1. 移除 sign;对已解码的参数值去除首尾空白,忽略空值。
  2. 按参数名 ASCII 升序排列,拼接为 key=value&key=value。
  3. 在末尾直接追加 API SECRET(不添加 & 或其他分隔符)。
  4. 对完整字符串做 UTF-8 编码和标准 Base64 编码。
  5. 对 Base64 文本计算 SHA-256,转为小写十六进制,得到 sign。
先对原始参数值签名,再进行表单 URL 编码。每个参数只允许出现一次。不要对 URL 编码后的字符串签名。服务器使用北京时间处理默认日期,时间戳使用 Unix 秒。

完整调用示例 03

示例查询卡号列表,不执行开停卡或套餐操作。将 API ID、SECRET 通过服务端环境变量提供;示例不会在此页面执行。

Python 3 · 标准库

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。以下错误码从服务端定义同步生成。

codemessage