API文档

基础地址: https://api.yimatongsms.com

创建订单

GET /api/order/createOrder

请求参数

参数	类型	必填	备注
`secretKey`	str	是	API密钥
`smsCountryId`	int	是	国家服务 ID（smsCountryId，来自目录）
`buyNum`	int	是	购买数量（必填）。不得低于所选商品在目录中展示的最小购买数量（通常为 1；部分商品可能有更高下限）。

响应

参数	类型	备注
`code`	int	响应代号：0=成功（含 queryOrder 处理中）；400=业务失败；401=仅 createOrder 密钥无效；404=不存在；429=限流；500=系统错误
`message`	str	消息提示
`data.apiOrderId`	str	订单号

成功示例

{
  "code": 0,
  "message": "创建成功",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

失败示例

{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}

更多示例: createOrder — 处理中（仍 code=0）

{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

更多示例: createOrder — 401 密钥无效

{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}

更多示例: createOrder — 404 国家服务无效

{
  "code": 404,
  "message": "国家服务不存在或已停用",
  "data": null
}

更多示例: createOrder — 400 余额不足

{
  "code": 400,
  "message": "余额不足",
  "data": null
}

更多示例: createOrder — 500 创建失败

{
  "code": 500,
  "message": "创建失败",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

查询订单

GET /api/order/queryOrder

请求参数

参数	类型	必填	备注
`apiOrderId`	str	是	订单号

响应

参数	类型	备注
`code`	int	响应代号：0=成功（含 queryOrder 处理中）；400=业务失败；401=仅 createOrder 密钥无效；404=不存在；429=限流；500=系统错误
`message`	str	消息提示
`data.apiOrderId`	str	订单号
`data.contents`	json(list)	固定 contents 列表结构，每个元素是一行订单内容

data 列表项字段

参数	类型	备注
`data.contents[].contentId`	string	内容行 ID，用作 resolveNumber 的 contentId 参数
`data.contents[].type`	int	1=文本行，2=含 getdata 链接
`data.contents[].content`	string	行内容字符串
`data.contents[].expiresAt`	string	号码建议在此时间前完成取码（ISO-8601 本地时间，如 2026-05-28T15:04:00）。过期后可能无法继续获取验证码。

成功示例

{
  "code": 0,
  "message": "查询成功",
  "data": {
    "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721",
    "contents": [
      { "contentId": "806779395c1640c882e65aaf1aba21d9", "type": 2, "content": "13800138000----/api/order/getdata?contentId=806779395c1640c882e65aaf1aba21d9", "expiresAt": "2026-05-28T15:04:00" },
      { "contentId": "a1b2c3d4e5f6", "type": 2, "content": "13900139000----/api/order/getdata?contentId=a1b2c3d4e5f6", "expiresAt": "2026-05-28T15:08:00" }
    ]
  }
}

失败示例

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

更多示例: queryOrder — 处理中（code=0）

{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721", "contents": [] }
}

更多示例: queryOrder — 404 订单不存在

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

释放号码

GET /api/order/resolveNumber

主动释放订单内号码（无需 secretKey）。GET BASEURL + /api/order/resolveNumber?apiOrderId=...；可选 contentId（queryOrder 返回的 contents[].contentId）仅释放该行，省略则尝试释放该订单所有未释放且未收短信的号码。已收短信的号码无法释放；释放成功 message 含退款说明；失败 code=400 可重试；不支持的订单类型亦返回 400。

请求参数

参数	类型	必填	备注
`apiOrderId`	str	是	订单号
`contentId`	str	可选	可选。queryOrder 返回的 data.contents[].contentId；指定则仅释放该行号码

响应

参数	类型	备注
`code`	int	响应代号：0=成功（含 queryOrder 处理中）；400=业务失败；401=仅 createOrder 密钥无效；404=不存在；429=限流；500=系统错误
`message`	str	消息提示
`data.apiOrderId`	str	订单号

成功示例

{
  "code": 0,
  "message": "已释放，退 0.050 USD",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

失败示例

{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

更多示例: resolveNumber — 400 已收短信

{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

更多示例: resolveNumber — 404 订单不存在

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

获取数据

GET /api/order/getdata

用法：先调用 /queryOrder。当 data.contents 中某项 type=2 且 content 含 /api/order/getdata?contentId=... 时，访问 BASEURL + /api/order/getdata?contentId=... 返回：纯文本。

请求参数

参数	类型	必填	备注
`contentId`	str	是	从 /api/order/getdata?contentId=... 中提取 contentId

响应

HTTP 状态	响应体示例	含义
`200`	`123456`	成功，正文为纯文本内容（如短信验证码）
`400`	`invalid contentId`	contentId 无效
`404`	`not found`	内容不存在或无权限
`429`	`Too Many Requests`	请求过频
`502`	`fetch error`	内容获取失败

成功示例

失败示例

not found

更多示例: getdata — 429 限流

Too Many Requests

常见问题（FAQ）

Q1. queryOrder 的 data 结构是什么？

data 是对象，包含 apiOrderId 与 contents。每条 content 含 contentId、type、content；短信验证码类订单还会返回 expiresAt。contentId 可作为 resolveNumber 的可选参数。

Q2. 如何访问 getdata 内容？

当 type=2 时，从 content 提取 contentId，再请求 /api/order/getdata?contentId=...（纯文本响应）。

Q3. getdata 返回的是什么格式？

getdata 返回纯文本，不包裹 JSON 外壳。

Q4. createOrder 会返回 code=202 吗？

不会。createOrder 与 queryOrder 处理中均返回 code=0；请用 message（如「处理中，请稍后查询」）及 contents 是否为空判断，并轮询 queryOrder。

Q5. 余额与扣费单位是什么？

账户余额、单价与订单金额均为 USD（最多 3 位小数）。API message 中的退款金额也以 USD 表示，例如「已释放，退 0.050 USD」。