NUOMI DEVELOPER API

通用短信 API

通过 Nuomi 后端使用已开放服务。标准项目和通用短信分别使用独立接口，并共享现有账户、订单、余额与账务规则。

基础信息

API 基础地址	`https://ckkk.lol/api/v1`
传输与内容	仅使用 HTTPS。JSON 请求发送 `Content-Type: application/json`；项目搜索使用 UTF-8 查询参数。
认证	请求头 `Authorization: Bearer YOUR_NUOMI_API_KEY`。不得把密钥放在 URL、网页前端或日志中。
密钥管理	登录后打开「API Key 管理」创建、轮换或撤销自己的密钥。完整密钥只在创建/轮换响应中显示一次；服务端只保存摘要。每个账户最多 5 个有效 Key。
账户隔离	每个 Key 绑定创建者账户。订单列表、短信查询与释放只作用于该账户自己的订单；使用其他账户订单号不会获得其订单数据。
货币	金额以整数分返回，货币代码为 CNY。所有售价由 Nuomi 服务端读取；请求体传价格会被拒绝。
时间	网站页面统一显示北京时间（UTC+8）；API 时间字段使用 ISO 8601，并带有 `+08:00` 时区偏移。

当前项目搜索只返回指定关键词对应的上游结果及已发布本地匹配项目；上游不支持完整目录下载或分页时，不代表全部项目。通用短信没有只读服务目录接口，直接使用关键词取号，不提供伪造的项目列表。

统一响应与错误

成功响应使用 {"ok": true, "data": ...}；失败响应使用 {"ok": false, "error": {"code": "...", "message": "..."}}。实际错误码由接口返回。

HTTP	常见错误码	含义与处理
400	`INVALID_PARAMETER`、`INVALID_FILTER`、`INVALID_KEYWORD`、`CLIENT_PRICE_REJECTED`	修正 JSON 类型、参数范围或筛选值后再提交。
401	`AUTHENTICATION_FAILED`	密钥无效、已撤销或账户不可用；重新核对密钥并检查账户状态。
402	`INSUFFICIENT_BALANCE`	可用余额不足。可用余额已扣除仍处于预留中的金额。
409	`PROJECT_NOT_AVAILABLE`、`ORDER_IN_PROGRESS`、`ORDER_RECONCILIATION_REQUIRED`、`ORDER_UNAVAILABLE`	项目未达到取号条件，或同一请求仍在处理。相同幂等键只对应原订单；另一笔独立任务可使用新的请求标识继续创建。
422	`SUPPLIER_REJECTED`	号码请求被明确拒绝，订单失败且未扣费；不要把它当成待核订单。
429	`RATE_LIMITED`、`MAX_ACTIVE_ORDERS`、`SUPPLIER_REJECTED`	`RATE_LIMITED` 表示请求频率受限；`MAX_ACTIVE_ORDERS` 表示账户已有 100 笔未结束订单；`SUPPLIER_REJECTED` 表示号码请求被明确拒绝且未扣费。
502	`UPSTREAM_UNAVAILABLE`、`NUMBER_UNAVAILABLE`、`RELEASE_FAILED`	上游不可用、明确无号或释放失败。按响应中的订单信息核对；不要因网络重试而创建新订单。
503	`API_DISABLED`、`CATALOG_DISABLED`、`ORDER_STATE_UNKNOWN`、`SETTLEMENT_PENDING`、`RELEASE_PENDING`	功能未开放，或单笔订单结果暂未确认。Nuomi 后台会继续处理原订单；请保留原请求标识用于该订单幂等重放，其他独立任务可使用新的请求标识。

如果返回 HTTP 403，且响应头带有 Cloudflare Ray ID，这表示请求可能被安全边缘或接口服务拒绝。请记录北京时间（UTC+8）、状态码和 Ray ID，提供给 Nuomi 支持排查；这不等同于“无库存”。不要把 Key 或完整响应正文发给支持人员。

GENERAL SMS

通用短信 API

通用短信使用关键词直接获取号码，不传标准项目 ID。它使用 Nuomi 自己设置的 CNY 售价，并由现有通用短信订单服务处理。上游没有可安全读取的只读服务目录接口，因此本 API 不提供虚构的通用项目搜索列表。

关键词获取号码

POST /general-sms/orders · 新请求每账户每秒最多 1 次。request_key 格式与标准项目相同，同一请求重试不得更换。不得传价格字段。

字段	类型	说明
`keyword`	字符串，必填	1–80 个字符的短信服务关键词，不是项目 ID。
`request_key`	字符串，必填	20–100 位幂等标识。
`phone`	字符串，可选	指定号码，6–20 位数字。
`card_type`	字符串，可选	`实卡`、`虚卡` 或 `全部`；默认 `全部`。
`filter_duplicates`	布尔，可选	是否过滤重复号码；默认 `false`。

curl -X POST 'https://ckkk.lol/api/v1/general-sms/orders' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"Telegram","request_key":"client-unique-request-000002","card_type":"全部","filter_duplicates":false}'

import requests

payload = {
    "keyword": "Telegram",
    "request_key": "client-unique-request-000002",
    "card_type": "全部",
    "filter_duplicates": False,
}
response = requests.post(
    "https://ckkk.lol/api/v1/general-sms/orders",
    json=payload,
    headers={"Authorization": "Bearer YOUR_NUOMI_API_KEY"},
    timeout=30,
)
print(response.status_code, response.json())

const response = await fetch("https://ckkk.lol/api/v1/general-sms/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NUOMI_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    keyword: "Telegram",
    request_key: "client-unique-request-000002",
    card_type: "全部",
    filter_duplicates: false
  })
});
const result = await response.json();

通用短信在上游明确成功分配号码后，按订单创建时 Nuomi 的价格快照扣费一次；明确失败不扣费。超时和结果未知时保留原订单待核，不自动创建新单。查询短信不重复扣费；释放号码不重复扣费且不自动退款。

查询订单、短信与释放

方法与路径	响应/副作用
`GET /general-sms/orders`	每账户每分钟最多 60 次；返回当前 Key 所属账户最近 100 笔通用短信订单。
`POST /general-sms/orders/{order_id}/sms`	每账户每分钟最多 30 次；查询该账户订单的短信状态与内容，不创建新会话、不重复扣费。
`POST /general-sms/orders/{order_id}/release`	每账户每分钟最多 10 次；请求释放该账户订单，不自动退款。

curl 'https://ckkk.lol/api/v1/general-sms/orders' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY'

curl -X POST 'https://ckkk.lol/api/v1/general-sms/orders/ORDER_ID/sms' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY'

curl -X POST 'https://ckkk.lol/api/v1/general-sms/orders/ORDER_ID/release' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY'

账户余额与状态

GET /account/balance 每账户每分钟最多 60 次，返回当前 Key 所属账户余额、预留金额和可用余额，均为 CNY 分。余额查询只读业务数据。

{
  "ok": true,
  "data": {
    "currency_code": "CNY",
    "currency_name": "RMB（人民币）",
    "minor_unit": "fen",
    "balance_minor": 10000,
    "reserved_minor": 100,
    "available_minor": 9900
  }
}

订单状态：requesting 请求中；unknown 结果待核；active 等待短信；received 已收到短信；releasing 释放中；release_unknown 释放结果待核；released 已释放；failed 取号失败。

查询和释放是 POST 请求，但只针对指定的已有订单。它们不会调用新的取号流程。订单列表只返回当前 API Key 所属账户的数据。

调用日志与排障

登录后在「API Key 管理」查看最近 50 条调用元数据：接口、时间、HTTP 状态、业务错误码和耗时。系统不会记录密钥、请求正文、验证码或完整响应。
HTTP 429：根据返回的等待时间再提交；不要在客户端循环重试。
HTTP 502/503：先用相同订单号查询原订单。若取号结果待核，重复取号必须使用相同 request_key，不得创建新标识掩盖未知结果。
HTTP 403：记录北京时间（UTC+8）和 Cloudflare Ray ID，并通过 Nuomi 支持渠道排查；切勿发送 API Key。
API Key 泄漏或不再使用时，立即在账户页面撤销或轮换。撤销后服务端会在下一次请求鉴权时拒绝该 Key。