开发文档

域名注册开放 API

本文面向外部开发者 / 对接方：用你的账号在「用户中心 → 域名 API」自助开通后，拿到 appid 与密钥，即可调用本套接口查询、注册、管理域名。域名注册在平台方的星途（TNAME）账号下，随时可申请转出到自己的星途账号。

签名与鉴权算法与平台的「代理开放 API」完全一致；如果你已经对接过代理 API，只要换 appid/接口前缀即可。

一、签名算法

1. 收集本次请求的全部参数（含公共参数），去掉 sign；
2. 按参数名升序排列，拼成 k1=v1&k2=v2&…（值为空的不参与拼接）；
3. 末尾直接拼接你的密钥 secret（中间不加任何符号），取 md5 小写即为 sign。

// PHP 示例
$p = [
    'appid'     => 'DAxxxxxxxxxxxx',
    'domain'    => 'example.com',
    'timestamp' => time(),
    'nonce'     => bin2hex(random_bytes(6)),
];
ksort($p);
$str = '';
foreach ($p as $k => $v) {
    if ('sign' !== $k && '' !== (string) $v) { $str .= $k . '=' . $v . '&'; }
}
$p['sign'] = md5(rtrim($str, '&') . '你的secret');

示例（便于核对）：参数 appid=DAxxxx&domain=abc.com&nonce=abc&timestamp=1700000000 时，sign = md5("appid=DAxxxx&domain=abc.com&nonce=abc&timestamp=1700000000" + secret)。

常见 401 原因：签名串里参数名没有排序、把空值也拼进去了、secret 拼在了 md5 里而不是 md5 外、时间戳偏差超过 300 秒、nonce 重复使用。

二、响应与错误码

所有成功响应中 data.balance 为你的当前可用余额（方便对账）。

三、定价与计费

• 对外价 = max(基准价 × 你的折扣, 成本 + 最低毛利)：折扣来自你的代理等级（普通用户为原价），最低毛利由平台配置（默认 ¥2/单）—— 也就是说折扣再低也不会低于成本，不会出现卖一单亏一单。
• 成本每次下单实时向上游查询，售价随订单快照；查价接口不返回成本。
• 查价免费；register 按售价扣费；业务类失败自动退回余额并记流水，网络类异常会保留扣款转人工处理（可用 order/query 跟踪）。
• 易支付单 30 分钟未支付自动关闭，关闭后同域名可重新下单。

四、接口清单

五、注册流程

方式一：余额即时注册（推荐）

// 1) 查价
POST {base}/check        domains = "abc.com"
// data.list[0] = {"domain":"abc.com","available":true,"price":102.00}

// 2) 下单（带幂等键，网络抖动重发也不会重复扣款）
POST {base}/register
     domain     = "abc.com"
     pay_method = "balance"
     idem_key   = "你的业务单号-abc.com"

// data = {"order_no":"D20261014123456789","status":1,"status_text":"已付待注册","balance":198.00, ...}

// 3) 轮询状态（注册是异步入队的，通常 1-5 分钟）
POST {base}/order/query  order_no = "D20261014123456789"
// status: 1 已付待注册 → 2 注册中 → 3 已注册（失败为 4，余额已自动退回）

方式二：单笔易支付

POST {base}/register
     domain     = "abc.com"
     pay_method = "epay"
     pay_type   = "alipay"        // alipay / wxpay / qqpay（以平台开通的渠道为准）
     idem_key   = "你的业务单号-abc.com"
     return_url = "https://你的站点/pay/return"   // 可选，付款后跳回这里
// data = {"order_no":"D…","price":102.00,"pay_url":"https://…/submit.php?…","expire_at":"…"}

把 pay_url 给用户跳转支付；用户付完后平台自动提交注册，你继续用 order/query 轮询即可（本套餐不提供 webhook，以查询为准）。

六、订单状态与退款

data.refund_status：0 未退款 / 1 已退款 / 2 待人工退款（易支付渠道）/ 3 退款重试中。data.manual=true 表示该单需要人工跟进（网络类异常、转出中、续费单）。

七、解析管理

所有解析/NS 操作都会校验域名归属（只能操作你自己名下的域名），越权返回 403；域名在转出申请期间解析写操作会被锁定（403）。支持 A / CNAME / MX / TXT 四种记录。

八、转出（PUSH）与续费

• 转出：提交 transfer/apply（填你自己的星途账号 ID）后进入人工处理，通常 1-3 个工作日完成；完成后域名归属你的星途账号，平台不再提供解析与续费。申请期间可随时查询进度，未处理的申请可联系客服取消。
• 续费：上游注册商没有续费接口，本 API 不提供自助续费；请在到期前联系平台客服人工续费，或把域名转出后自行续费。到期时间可在 my/list 或 order/query 的 expire_time 查看。

九、频控与风控

• 全局：120 次/分钟（按 appid）；下单额外限制每分钟 6 单 / 每日 20 单（平台可调，可在 account 里看到你的额度）。
• 查价结果缓存 60 秒；单次最多查 5 个域名。
• 平台维护域名关键词 / 后缀黑名单（命中返回 422），并对异常账号停用；请勿提交违规、侵权、涉敏域名 —— 域名挂在平台账号下，滥用会导致整站被封。
• 建议在开通后到「用户中心 → 域名 API」配置 IP 白名单（支持 1.2.3.* 通配），把密钥泄露的风险降到最低。

十、常见问题

1. 提示「appid 不存在」：确认用的是用户中心「域名 API」页里的 appid（DA 开头），不是代理开放 API 的 AG 凭据。
2. 提示「该接口仅供代理账号调用」：卡密/授权的接口只能代理调；域名注册请用 /api/open/domain/*。
3. 下单返回 409「已有进行中的订单」：同一域名已有一张待付/注册中的单，用 order/query 查它，不要重复下单。
4. 下单返回 402：余额不足，充值后重试，或改用 pay_method=epay。
5. 注册失败了钱退了吗？：业务类失败（域名被抢、上游拒绝）立即原路退回余额并可在「财务明细」看到「域名注册失败退回」；网络类异常会保留扣款转人工，处理结果以 order/query 为准。
6. 能不能批量注册？：接口一次一单（上游串行较慢），批量请自行循环并遵守限额；建议带上 idem_key 保证不重复扣款。