把云码接入你自己的网站

服务代码与国家代码

目录接口为公开只读接口，不需要 API Key。返回的代码可直接传给价格与下单接口；数据与本站选择器共用当前目录。

GET /api/partner-catalog?type=services 获取服务；GET /api/partner-catalog?type=countries 获取国家/地区。

curl 'https://www.yunmaya.cn/api/partner-catalog?type=services'
curl 'https://www.yunmaya.cn/api/partner-catalog?type=countries'

响应：{"success":true,"type":"services","count":2,"items":[{"name":"WhatsApp","code":"wa"}]}

国家项包含 name、code，以及可用时的 iso 国旗代码。列表约每分钟更新缓存。

创建订单

POST /api/orders-create

一次创建一个号码订单。服务代码和国家代码请从本站的价格 API 文档页面查看；请求参数只接受本站列出的代码。

请求参数

请求示例

curl -X POST https://www.yunmaya.cn/api/orders-create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"wa","country":"73"}'

成功响应（HTTP 201）

{
  "success": true,
  "order": {
    "activation_id": "订单编号",
    "phone": "+号码",
    "service": "wa",
    "country": "73",
    "status": "waiting",
    "price": 0.45,
    "currency": "USD",
    "expires_at": "2026-09-25T12:00:00.000Z",
    "cancel_available_at": "2026-09-25T11:43:00.000Z"
  },
  "balance": 9.55,
  "currency": "USD"
}

返回的 price 是云码当前售价；下单金额以成功响应为准。余额不足或没有可用号码时不会创建成功订单。

查询订单状态与验证码

GET /api/orders-status?activation_id=订单编号

使用创建订单响应中的 activation_id 查询短信状态。请在等待期间每隔几秒轮询一次。

curl -G 'https://www.yunmaya.cn/api/orders-status' \
  --data-urlencode 'activation_id=订单编号' \
  -H 'Authorization: Bearer YOUR_API_KEY'

等待中返回 {"success":true,"status":"waiting"}；收到短信后返回 {"success":true,"status":"completed","code":"123456"}。超过订单的 expires_at 且仍未收到验证码时，状态查询会尝试取消上游号码；确认取消后服务器自动把订单金额退回云码余额。

超时退款由订单状态查询触发，并非独立后台定时任务。请在 expires_at 后继续轮询，直到返回 {"success":true,"status":"expired","refunded":true}；若返回 HTTP 409 / expiring，表示上游取消尚未确认，请稍后重试。

查询余额与取消订单

GET /api/partner-account 查询云码账户余额；使用创建订单响应中的余额也可以更新你自己的站点余额显示。

curl 'https://www.yunmaya.cn/api/partner-account' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应：{"success":true,"balance":9.55,"currency":"USD"}

POST /api/partner-account?action=cancel 取消一个仍在等待中的订单。订单归属会按 API Key 校验；订单未到允许取消时间或上游未确认取消时，不会退款。

curl -X POST 'https://www.yunmaya.cn/api/partner-account?action=cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"activation_id":"订单编号"}'

成功响应：{"success":true,"status":"cancelled","refunded":true,"balance":10,"currency":"USD"}

取消只适用于未完成订单。服务器先请求上游取消，收到确认后才给云码账户退款；取消接口返回 HTTP 409 且状态为 cancelling 时，请稍后重试查询订单状态。

常见错误

此接口会创建真实订单并扣除余额。请勿在程序中自动重复提交同一请求；每次成功调用都会创建新的订单。