API 文档与开发者接入

基础信息

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

统一响应与错误

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

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

标准项目 API

项目代码由上游搜索返回；项目必须已在 Nuomi 核验、启用并对当前账户配置有效 CNY 售价才能取号。每个账户最多同时保留 100 笔未结束的标准或通用短信订单，单笔结果待处理不会阻止其他独立订单；每个业务类型仍执行每秒新请求限制和上游共享队列约束。生产数据库核验到项目 57118，名称为「新电途科技/新电途」，适用范围记录为中国大陆（代码 CN，依据为已观察分配记录，不代表上游承诺所有号码均来自该地区）。当前通用平台售价配置为 ¥1.00 CNY；用户价格覆盖或后台调整会改变实际响应，以下均以 API 实时返回为准。

搜索标准项目

GET /standard/projects?keyword={关键词} · 每账户每分钟最多 30 次。搜索是真实上游关键词查询并补充 Nuomi 已发布目录，不支持完整目录下载，也没有上游分页参数。已录入 Nuomi 的项目代码可精确本地匹配；上游接口不保证能按未同步项目代码搜索。

curl --get 'https://ckkk.lol/api/v1/standard/projects' \
  --data-urlencode 'keyword=新电途' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY'

import requests

response = requests.get(
    "https://ckkk.lol/api/v1/standard/projects",
    params={"keyword": "新电途"},
    headers={"Authorization": "Bearer YOUR_NUOMI_API_KEY"},
    timeout=15,
)
print(response.json())

const response = await fetch(
  "https://ckkk.lol/api/v1/standard/projects?keyword=" + encodeURIComponent("新电途"),
  { headers: { Authorization: "Bearer YOUR_NUOMI_API_KEY" } }
);
const result = await response.json();

成功结构与当前服务一致。project_id 是上游项目代码；local_project_id 仅对已发布项目提供。只有 order_enabled: true 才可通过本 API 申请号码。

{
  "ok": true,
  "data": {
    "currency_code": "CNY",
    "currency_name": "RMB（人民币）",
    "minor_unit": "fen",
    "keyword": "新电途",
    "projects": [{
      "project_id": "57118",
      "name": "新电途科技/新电途",
      "country_code": "CN",
      "upstream_confirmed": true,
      "published": true,
      "order_enabled": true,
      "status": "order_open",
      "price_minor": 100,
      "price_currency_code": "CNY"
    }],
    "upstream_result_count": 1,
    "upstream_status": "ok",
    "upstream_pagination_supported": false,
    "complete_directory_supported": false
  }
}

这是响应字段摘录；实际搜索响应还会返回 match_source、available、status 和已发布项目的 local_project_id。项目数量及本地项目主键会随查询和数据库变化；上面显示的价格是当前平台默认配置的示例值，不应缓存为固定售价。取号时服务端会重新检查项目状态和当前账户价格。

获取号码

POST /standard/orders · 新请求每账户每秒最多 1 次。正文中的 project_id 必须是搜索返回的上游项目代码（例如 "57118"），不是本地数据库主键。request_key 是调用方生成的 20–100 位字母、数字、下划线或连字符标识；网络超时后必须用同一个值核对/重试原单，新的业务请求才生成新值。

curl -X POST 'https://ckkk.lol/api/v1/standard/orders' \
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"57118","request_key":"client-unique-request-000001","filters":{}}'

import requests

payload = {
    "project_id": "57118",
    "request_key": "client-unique-request-000001",
    "filters": {},
}
response = requests.post(
    "https://ckkk.lol/api/v1/standard/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/standard/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NUOMI_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    project_id: "57118",
    request_key: "client-unique-request-000001",
    filters: {}
  })
});
const result = await response.json();

新单成功通常为 HTTP 201，幂等重放为 HTTP 200。标准项目取号成功后先预留 Nuomi 售价；等待短信不扣款，收到有效验证码后结算一次。明确失败释放预留；上游超时/结果未知时订单保留待核，切勿用新 request_key 再下一单。

查询订单、短信与释放

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

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

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

固定单项目协议接入

现有 API 文档：固定项目协议

现有固定单项目协议对应接口根地址 https://ckkk.lol/api/v1。使用此协议时，将客户端地址设为该根地址，并使用 Nuomi 账号生成的 API Key。项目固定为新电途，协议项目码为 newdian，Nuomi 内部映射至已核验项目 57118；该协议不提供项目搜索。

新订单返回 HTTP 201，同一幂等键重放返回 HTTP 200；供应商明确拒绝返回 422/429 SUPPLIER_REJECTED，订单失败、预留释放且不扣费；结果不确定返回 503 ORDER_STATE_UNKNOWN 并保留原请求待核；上游已有待核订单时返回 409 ORDER_RECONCILIATION_REQUIRED，当前请求不会再次购买。收到 409 后应查询已有订单，不要自动重试或更换请求标识。该兼容入口复用 Nuomi 自己的余额预留、订单、价格和账务逻辑。请使用 Nuomi 为当前账号签发的 API Key；不同平台的 API Key 不能混用。

全项目 API 文档：动态项目协议

全项目协议的 Nuomi 接口根地址为 https://ckkk.lol/api/docc/v1，需要客户端支持动态项目搜索及显式传入项目 ID。它与固定单项目协议使用不同的请求字段、项目 ID 和订单命名空间。

创建或订单对象提供 verification_code、reserved、billing_status 等字段；短信查询的核心字段直接位于 data。price_cents 是 Nuomi 为当前用户配置的 CNY 零售价分值，不是其他平台的价格。待核结果必须查询原订单，不能使用新键重发。

curl -X POST 'https://ckkk.lol/api/docc/v1/number' \\
  -H 'Authorization: Bearer YOUR_NUOMI_API_KEY' \\
  -H 'Idempotency-Key: client-unique-request-000001' \\
  -H 'Content-Type: application/json' \\
  -d '{"project_id":"57118","isp":"1"}'

通用短信 API

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

关键词获取号码

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

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 的价格快照扣费一次；明确失败不扣费。超时和结果未知时保留原订单待核，不自动创建新单。查询短信不重复扣费；释放号码不重复扣费且不自动退款。

查询订单、短信与释放

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。