开发文档

产品使用文档与部署教程，持续更新中

首页>文档>API 文档

域名注册接口（星途域名 TNAME）

域名注册接口（星途域名 TNAME）

阅读提示：本文是上游注册商（星途域名）的接口说明——写给想了解「本平台是怎么对接上游注册商」的开发者，接口密钥在上游商户手里，不是本平台对外开放的接口。如果你要接入本平台注册域名，请改用《域名注册开放 API》：在「用户中心 → 域名 API」自助开通后拿 appid / 密钥即可调用（余额扣费或单笔易支付，支持查询、注册、解析、转出申请）。

云枢官网系统的域名注册模块对接的注册商是星途域名（tname.net）。本文整理自官方接口文档 https://tname.net/doc（xtum.cn 与 tname.net 是同一套后端，两个域名都可用），并补充官方文档没写清、但真机实测确认过的细节。

程序侧已把本套接口封装在域名注册插件的 app/service/TnameApi.php（class TnameApi）里：签名、POST 表单、错误文案、价格解析、状态码翻译都已处理，二次开发直接调用即可，不需要自己拼 sign。

项目值
接口根地址https://tname.net/api/
认证方式uid（商户 ID）+ sign = md5(uid + key)，key 在星途后台生成
请求方式POST / GET 均可（推荐 POST 表单），字符编码 UTF-8
返回约定{"code":1,"msg":"成功","data":{…}}，code=1 为成功，其余为失败（失败原因看 msg）
程序内封装app/service/TnameApi.php（check() / register() / domainInfo() / dnsAdd() 等）

一、公共参数与返回

请求公共参数

变量名必填类型示例值描述
uid是int1001系统分配的商户 ID
sign是String32 位 MD5md5(uid + key)——只拼这两项，不带其它参数

返回公共参数

参数名类型说明
codeint1 = 成功，其余为失败
msgString相关描述（失败原因）
dataobject / array / String具体信息（各接口不同，见下）

注意：官方文档「返回公共参数说明」里写的是「code：1 未成功，其他为失败」，这句是笔误——文档里每个接口的示例、以及真机实测都是 code=1 且 msg=成功。程序里统一按 code=1 成功 判断。

二、接口一览

接口地址用途
查询域名POST /api/check查询域名是否可注册，返回注册价
注册域名POST /api/register提交注册（默认一年），进注册任务队列
获取域名列表POST /api/getdomainlist分页列出账号下所有域名
获取域名信息POST /api/getdomaininfo单个域名详情（含注册状态、DNS 类型、到期时间）
获取解析列表POST /api/getdnslist列出某域名的全部解析记录
添加解析POST /api/adddns新增一条解析记录，返回 record_id
修改解析POST /api/updns按 record_id 修改解析
删除解析POST /api/deldns按 record_id 删除解析
修改 DNS 服务器POST /api/upnameserver切换 DNS（留空 = 切回高级 DNS）

三、查询域名

接口地址：https://tname.net/api/check

变量名必填类型示例值描述
domain是Stringtname.net需要查询的域名（如 domain.com）

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": {
        "price": "85.00"   // 注册价格（注意：是字符串，不是数字）
    }
}

真机实测（域名已被注册时）：{"code":-1,"msg":"域名已被注册！","data":"example.com"}——失败时 data 仍是域名字符串，不要直接当对象用。

四、注册域名

接口地址：https://tname.net/api/register

变量名必填类型示例值描述
domain是Stringtname.net需要注册的域名（默认一年）

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": {
        "price": 85   // 订单价格
    }
}

重要：code=1 只代表域名已进入星途的注册任务队列，不代表注册成功。要确认是否注册成功，用「获取域名信息」接口查 status（0 注册中 / 1 正常）。程序里 register() 之后就是轮询 domainInfo() 判状态的。

五、获取域名列表

接口地址：https://tname.net/api/getdomainlist

参数名必填类型示例值描述
page是int1第几页
list_rows是int10每页显示多少条数据

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": {
        "list": [
            {"domain":"aa.top","dns_type":3,"create_time":"2022-06-11 20:53:47","of_time":1812718427},
            {"domain":"bb.top","dns_type":3,"create_time":"2024-04-30 20:01:38","of_time":1809086498}
        ],
        "total": 3,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1
    }
}

字段说明：dns_type 1=我司 DNS、2=其他 DNS、3=高级 DNS；create_time 注册时间；of_time 到期时间（时间戳）。

六、获取域名信息

接口地址：https://tname.net/api/getdomaininfo

参数名必填类型示例值描述
domain是Stringtname.net要查询的顶级域名

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": {
        "domain": "tname.net",
        "dns_type": 3,
        "create_time": "2023-09-19 23:04:54",
        "of_time": "2027-09-19 23:04:54",
        "status": 1
    }
}
字段取值
dns_type1=我司 DNS / 2=其他 DNS / 3=高级 DNS
status0=注册中 / 1=正常 / 2=PUSH 中 / 3=出售中 / 4=Hold / 5=续费中

七、获取域名解析列表

接口地址：https://tname.net/api/getdnslist

参数名必填类型示例值描述
domain是Stringtname.net域名

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": [
        {"id":197344,"name":"@","type":"CNAME","value":"xx.cn","mx":0,"ttl":1},
        {"id":197345,"name":"www","type":"CNAME","value":"bb.cn","mx":0,"ttl":1},
        {"id":231662,"name":"a","type":"A","value":"8.218.167.39","mx":null,"ttl":1}
    ]
}

八、添加解析

接口地址：https://tname.net/api/adddns

参数名必填类型示例值描述
domain是Stringtname.net域名
host是Stringwww主机记录（域名前缀），如 www 或 @
type是StringA解析类型：A / CNAME / MX
value是String127.0.0.1解析值（类型为 A 时应为服务器 IP）
cdn否int1是否启用 CDN，1 启用 / 0 不启用
mx否int5类型为 MX 时必填，值 1~10

返回参数：

{
    "code": 1,
    "msg": "成功",
    "data": {
        "record_id": 16868   // 该解析记录的唯一 ID，修改/删除解析都要用它
    }
}

九、修改解析

接口地址：https://tname.net/api/updns

参数名必填类型示例值描述
domain是Stringtname.net域名
record_id是int10000添加解析成功返回的唯一 ID
host是Stringwww主机记录，如 www 或 @
type是StringA解析类型：A / CNAME / MX
value是String127.0.0.1解析值（类型为 A 时应为服务器 IP）
cdn否int1是否启用 CDN
mx否int10类型为 MX 时必填，值 1~10

返回参数：{"code":1,"msg":"成功","data":{}}

十、删除解析

接口地址：https://tname.net/api/deldns

参数名必填类型示例值描述
domain是Stringtname.net域名
record_id是int16868添加解析时返回的 record_id

返回参数：{"code":1,"msg":"成功","data":{}}

十一、修改 DNS 服务器

接口地址：https://tname.net/api/upnameserver

参数名必填类型示例值描述
domain是Stringtname.net域名
ns1否Stringns1.tname.net留空则切换为高级 DNS（用星途自己的解析）
ns2否Stringns2.tname.net留空则切换为高级 DNS

返回参数：{"code":1,"msg":"成功","data":{}}

十二、真机实测要点（2026-09-29，uid=12162）

  1. 成功判定看 code=1：官方文档「code：1 未成功」是笔误，实测各接口成功均返回 {"code":1,"msg":"成功"}。
  2. 价格是字符串：check 成功时 data.price 形如 "85.00"，做数值运算前先 (float)；register 的 data.price 是数字。
  3. 失败时 data 类型会变：check 查询已注册域名返回 data 为域名字符串（不是对象），按数组取值前判类型。
  4. 密钥未生成的报错：未在星途后台生成密钥的账号、以及不存在的 uid，都返回 {"code":-1,"msg":"当前用户未生成秘钥！"}；只有已配密钥的账号输错 sign 才会看到「签名错误」——排障时先确认后台生成过密钥。
  5. 域名信息/列表 拿不到解析记录的情况：域名必须已切到「高级 DNS」（dns_type=3）才能用 getdnslist/adddns/updns/deldns；如果域名还在用星途默认 DNS，解析要用 upnameserver 切过来。
  6. 注册是异步的：register 返回成功只表示任务入队，注册结果用 getdomaininfo 的 status 轮询（0 注册中 → 1 正常）。

十三、PHP 调用示例

官方文档给每个接口都配了一段几乎相同的 cURL 示例；下面把它们合并成一个通用函数（程序里用 TnameApi 即可，这段是给独立脚本/排查用的）：

$uid = 1001;                 // 商户 ID（星途后台）
$key = '你的key';            // 后台生成的密钥

function tname_api(string $path, array $params, string $uid, string $key): array
{
    $params['uid']  = $uid;
    $params['sign'] = md5($uid . $key);          // 只拼 uid + key
    $ch = curl_init('https://tname.net/api/' . $path);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 20);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    $out = curl_exec($ch);
    curl_close($ch);
    return json_decode((string) $out, true) ?: [];
}

// 查是否可注册
$r = tname_api('check', ['domain' => 'domain.com'], $uid, $key);
if (($r['code'] ?? 0) === 1) {
    echo '可注册，价格：' . (float) $r['data']['price'];
} else {
    echo '不可注册：' . $r['msg'];
}

// 注册域名（返回成功只是入队，之后用 getdomaininfo 轮询 status）
$r = tname_api('register', ['domain' => 'domain.com'], $uid, $key);

// 添加解析（type 支持 A / CNAME / MX）
$r = tname_api('adddns', ['domain' => 'domain.com', 'host' => 'www', 'type' => 'A', 'value' => '1.2.3.4', 'cdn' => 0], $uid, $key);
$recordId = (int) ($r['data']['record_id'] ?? 0);

接口地址汇总：https://tname.net/api/{check|register|getdomainlist|getdomaininfo|getdnslist|adddns|updns|deldns|upnameserver}，官方文档原文：https://tname.net/doc。

← 返回文档列表