本域名(wapi.gzisp.net)是「域名、网站基础产品」开放接口的统一入口。接口已开发完成(只读 + 写入类),但当前已由管理员关闭,暂不可调用 —— 下面的说明请当作开放后的接入参考。
403 api_global_disabled(密钥正确也一样;你的密钥与配额都会被保留,开放后原样可用)。
本页仅作接入说明保留,请等平台开放后再联调。
我们按产品类型拆分了对外 API 域名,请按需使用:
wapi.gzisp.net:域名、网站基础类产品 API(本文档)。aiapi.gzisp.net:AI Token 开放接口(OpenAI 兼容对话补全)。若你要调用大模型对话能力,请前往 aiapi.gzisp.net。所有请求需在请求头携带会员专属 API Key(在会员中心「API 密钥」页生成,支持多把、可选用途、可独立吊销):
# 方式一:Authorization 头(推荐) Authorization: Bearer sk-你的密钥 # 方式二:X-Api-Key 头 X-Api-Key: sk-你的密钥 # 方式三:查询参数(仅调试用) ?api_key=sk-你的密钥
密钥明文仅在生成时显示一次,请妥善保存。泄露后可随时在会员中心吊销,对应调用立即失效。
所有端点以 https://wapi.gzisp.net/api/v1 为根,路径带版本号。分两类:只读接口调用不产生任何变更或费用;写入接口(交易)会改变线上状态(下单 / 扣款 / 改解析 / 提交转移),另需密钥勾选「交易 / 下单」权限。
| 方法 / 路径 | 说明 | 权限 | 状态 |
|---|---|---|---|
| GET /api/v1/ping | 密钥自检:确认密钥可用、作用域匹配、账户已开启开放 API | 只读 | 暂未开放 |
| GET /api/v1/domain/check | 域名可用性 + 注册 / 续费 / 转入价格试算 | 只读 | 暂未开放 |
| GET /api/v1/domain/whois | 域名注册信息(注册商、注册 / 到期日、DNS、状态) | 只读 | 暂未开放 |
| GET /api/v1/domain/suffixes | 后缀与价格表(每项带 registerable,判断能否下注册单只看它) | 只读 | 暂未开放 |
| GET /api/v1/dns/records | 某域名下的解析记录列表(只读,不改动任何解析) | 只读 | 暂未开放 |
| POST /api/v1/domain/register/precheck | 下单前预检(只读,不扣款):列全全部待办与报价 | 交易 | 暂未开放 |
| POST /api/v1/domain/register | 提交域名注册单(真实扣余额) | 交易 | 暂未开放 |
| GET /api/v1/domain/register/orders | 我的注册单列表与进度 | 交易 | 暂未开放 |
| POST /api/v1/domain/register/cancel | 撤回「待受理」注册单(原路退回余额) | 交易 | 暂未开放 |
| POST /api/v1/dns/records/save | 新增 / 修改一条解析记录(会推送到解析平台) | 交易 | 暂未开放 |
| POST /api/v1/dns/records/delete | 删除一条解析记录(会推送到解析平台) | 交易 | 暂未开放 |
| GET /api/v1/domain/renew/quote | 续费报价 + 资格预判(只读语义,不扣款;同族故要求交易权限) | 交易 | 暂未开放 |
| POST /api/v1/domain/renew | 提交域名续费(真实扣余额;受平台续费开关控制,见下) | 交易 | 暂未开放 |
| GET /api/v1/domain/transfer/quote | 转入 / 转出 / 过户 报价 + 资格预判(只读语义,不落单;同族故要求交易权限) | 交易 | 暂未开放 |
| POST /api/v1/domain/transfer | 提交转入 / 转出 / 站内过户(受理即落单,不预扣款;有价方向提交时先过余额闸门) | 交易 | 暂未开放 |
| GET /api/v1/domain/transfer/orders | 我的转移单列表与进度 | 交易 | 暂未开放 |
| POST /api/v1/domain/transfer/cancel | 撤回「待审核」转移单 | 交易 | 暂未开放 |
| 虚拟主机 / 建站 | 主机开通、站点管理、资源监控 | 交易 | 规划中 |
| 订单 / 财务 | 订单查询、余额与账单 | 交易 | 规划中 |
「只读」端点只需密钥作用域命中本域名(或不限)即可调用;「交易」端点在生成密钥时必须额外勾选「交易 / 下单(写入类端点)」—— 这是刻意的:
写入会动钱,绝不能让一把老的只读密钥在接口上线后自动获得下单能力。
可用 GET /api/v1/ping 返回的 key.can_trade 自检。
只读 / 交易的分界线是「会不会改变线上状态」:读平台与域名的事实(可用性、WHOIS、价格表、解析记录列表)算只读; 读自己的交易账目(订单列表)与任何写操作(下单、撤回、改解析、续费)都算交易。 这样一把只读密钥不会因为「要展示 DNS 面板」就被迫升级成能下单、能改解析的密钥。
同族同权限:注册 / 续费 / 转入转出 / 建站下单 这几族端点整族都要求交易权限,包含族内的只读端点
(续费报价 GET /api/v1/domain/renew/quote、转移报价 GET /api/v1/domain/transfer/quote、下单预检 POST /api/v1/domain/register/precheck、
订单 GET /api/v1/domain/register/orders、GET /api/v1/domain/transfer/orders)。原因:它们服务的是同一笔钱的决策链——
若「报价」只读而「扣款」要交易,就会出现「只读密钥能算出客户要花多少钱、却没有能力付费」的破碎语义。
🔴 扣费与余额口径(跨全部写入端点,请务必读完):
① 所有扣费都走「会员余额」,不存在绕过余额直接向注册商下单的路径;
② 余额不足时,平台一定会把原因如实返回给调用方
(insufficient_balance,message 里给出所需金额与当前余额),
并且 本平台侧不会做任何会让上游(注册商 / 解析平台 / AI 厂商)产生费用的操作 ——
即:先检余额,再向上游提交,余额不够时上游根本不会被调用,也不会留下任何半成品单据;
③ 扣款是原子条件写(`WHERE money >= 金额`),同一账户的并发消费不会透支、也不会重复扣;
④ 唯一的例外是「已经向上游提交成功、但本地结算失败」的极端情形:此时平台绝不伪装成功,
而是返回 unpaid(续费)或 402 settle_shortfall(AI),并明确标注
「上游已生效、差额已挂账、请勿重复提交」 —— 这类码不是可重试的失败。
GET https://wapi.gzisp.net/api/v1/ping
拿到密钥后建议先跑一次 —— 它会告诉你密钥是否有效、能否用于本域名、以及账户的开放 API 开关状态。
curl "https://wapi.gzisp.net/api/v1/ping" \ -H "Authorization: Bearer sk-你的密钥"
{
"ok": true,
"data": {
"server_time": "2026-09-25 12:00:00",
"user_id": 1100001,
"key": {
"id": 3,
"name": "生产环境",
"scope": "web,trade",
"scope_label": "网站 / 域名基础产品接口(wapi.gzisp.net) + 交易 / 下单(写入类端点)",
"can_trade": true
},
"api_status": 1,
"base": "https://wapi.gzisp.net/api/v1",
"endpoints": ["GET /api/v1/ping", "…"],
"write_endpoints": ["POST /api/v1/domain/register", "…"]
}
}
key.can_trade 为 false 时,只读端点仍可正常调用,但任何「交易」端点都会返回 403 key_trade_not_allowed —— 与其等到下单时才失败,建议先跑一次自检。
GET https://wapi.gzisp.net/api/v1/domain/check?domain=example.com
| 参数 | 必填 | 说明 |
|---|---|---|
domain | 是 | 待查询域名;会自动去掉协议 / 路径 / 结尾点并转小写 |
示例(curl)
curl "https://wapi.gzisp.net/api/v1/domain/check?domain=example.com" \ -H "Authorization: Bearer sk-你的密钥"
响应
{
"ok": true,
"data": {
"domain": "example.com",
"suffix": ".com",
"available": false,
"availability_source": "rdap",
"registered": {
"registrar": "Example Registrar, Inc.",
"reg_date": "1995-08-14",
"exp_date": "2026-08-13"
},
"platform_owned": false,
"price": {
"currency": "CNY",
"register": { "ok": true, "price": 78, "src": "Lv2 新注册价" },
"renew": { "ok": true, "price": 78, "src": "Lv2 续费价" },
"transfer": { "ok": false, "price": null, "msg": "后缀 .com 的转入价未配置" }
}
}
}
| 字段 | 说明 |
|---|---|
available | true 可注册 / false 已被注册 / null 无法判定(权威来源不可达,详见 availability_note) |
availability_source | rdap 注册局 RDAP / platform 本平台台账 / unverifiable 不可核验 |
price.*.ok | false 表示该动作尚未定价,此时 price 为 null。平台不会给出估算价 —— 未定价即以后台配置为准 |
GET https://wapi.gzisp.net/api/v1/domain/whois?domain=example.com
curl "https://wapi.gzisp.net/api/v1/domain/whois?domain=example.com" \ -H "Authorization: Bearer sk-你的密钥"
响应
{
"ok": true,
"data": {
"domain": "example.com",
"registered": true,
"registrar": "Example Registrar, Inc.",
"reg_date": "1995-08-14",
"exp_date": "2026-08-13",
"nameservers": ["a.iana-servers.net", "b.iana-servers.net"],
"status": ["clientDeleteProhibited"],
"source": "rdap",
"note": "",
"platform": { "managed_here": false, "owned_by_you": false }
}
}
数据优先来自 RDAP(走 443、结构化);RDAP 不可达时降级为 WHOIS,并在 source 中如实标注。两者都不可用时 registered 为 null —— 我们不会用「查不到」去推断「可注册」。
为保护隐私,只有该域名属于你本人时,才返回 platform 下的到期时间、状态等明细。
GET https://wapi.gzisp.net/api/v1/domain/suffixes
| 参数 | 必填 | 说明 |
|---|---|---|
action | 否 | 只看某个动作:register / renew / transfer;缺省返回三个动作 |
priced | 否 | 传 1 只返回已定价后缀,便于直接生成价目表 |
limit | 否 | 返回条数上限,默认 200,最大 500 |
价格与会员中心展示完全同源(后台定价中心是唯一价格源),仅返回已上架后缀。成本与毛利属商务信息,不会通过任何接口返回。
每个后缀项都带 registerable(布尔)—— 判断能不能下注册单,只看它。
它与 register.ok 不是一回事:register.ok 只表示「平台给这个后缀配了注册价」,
而 registerable 表示「当前至少有一家注册商能承接这个后缀的新注册」。
当 registerable=false 时,register 的价格是基准价参考值,
照它下单会被拒(下单预检会返回「本平台暂不支持 X 的新注册」)。
原因:本端点是「全列 + 打标」口径(priced 同理),不删条目,
以免按后缀全集对账的集成受影响。同一字段也出现在 GET /api/v1/domain/check 的顶层。
这一组端点会真实扣减会员余额。两道额外的闸门必须先过:
① 密钥须勾选「交易 / 下单」权限(否则 403 key_trade_not_allowed);
② 每个变更类请求必须携带 Idempotency-Key(否则 400 invalid_idempotency_key)。
关于 Idempotency-Key(为什么必须带)
网络超时(客户端收到 504、但服务端其实已经扣款成功)是常态,客户端一定会重试。幂等键保证同一个键 + 同一份请求体只会真正执行一次:
idempotent_replay: true),不会再次扣款;409 idempotency_key_reused(换一个新键再提交);409 idempotency_key_in_use。键的格式:8~64 位,仅字母、数字、-、_。用 UUID 或时间戳+随机串都可以。放在请求头 Idempotency-Key,也可放在请求体字段 idempotency_key。
① 下单前预检(只读,不扣款) POST /api/v1/domain/register/precheck
把「为什么不能下单」逐条列全(实名、注册商、定价、可用性…),一次就能看到全部待办,不用反复试。此端点不扣款、不建单,也不需要幂等键。
curl -X POST "https://wapi.gzisp.net/api/v1/domain/register/precheck" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{"domain":"example.cn","years":1,"registrar":"aliyun"}'
{
"ok": true,
"data": {
"can_submit": true,
"domain": "example.cn",
"suffix": ".cn",
"available": true,
"availability_source": "rdap",
"registrar": "aliyun",
"realname": { "ok": true, "kind": 0, "label": "个人已实名", "msg": "" },
"need_template": 1,
"status_queryable": true,
"template_gate": { "need": 1, "label": "域名注册需要实名模板(须审核通过)", "selected": 0, "ok": false,
"status_queryable": true,
"msg": "「阿里云」注册域名**必须**指定一份已通过审核的实名模板,请先在上方选择模板;…" },
"template_choices": [ { "id": 178, "name": "我的公司模板", "auth": "企业",
"status": 1, "label": "待审核", "usable": 0, "need": 1,
"missing": [], "note": "该注册商要求实名模板且须审核通过,当前状态:待审核" } ],
"quote": { "ok": true, "unit": 50, "total": 50, "years": 1, "src": "Lv2 新注册价" },
"candidates": [ { "code": "aliyun", "name": "阿里云", "priced": 1, "price": 50, "deliver_mode": "manual" } ],
"blockers": [],
"warnings": [],
"need_ack_unverified": false,
"deliver": { "mode": "manual", "label": "人工办理" }
}
}
| 字段 | 说明 |
|---|---|
can_submit | 即 blockers 为空。为 false 时把 blockers 逐条展示给用户即可(已写成可读中文) |
need_ack_unverified | true 表示可用性无法核验(RDAP 不可达)。此时提交必须带 ack_unverified: true 表示知悉「由人工核实,若已被注册则全额退款」 |
need_template | 「需不需要实名模板」是注册商属性(且只针对「域名注册」这个角色),不是模板属性:1 该注册商注册域名要实名;0 免实名,但仍必须给注册人联系信息(姓名 / 邮箱 / 电话齐备的模板);-1 本平台无法核验(该注册商未登记或渠道已停用)—— 此时不拦截,单据转人工核实 |
status_queryable | 该注册商的实名审核状态能否回查。为 true 时 need_template=1 才意味着「必须选一份status=2的模板」;为 false 时(如 dnspod)本平台查不到该家审核状态 ⇒ 闸门退化为「选一份姓名/邮箱/电话齐备的模板 + 整单转人工核实」,此时不要再向用户宣称「须审核通过」 |
template_choices | 该注册商下可用性已算好的模板清单(只含调用方自己的模板)。usable=1 才可选;missing 列出缺哪几项,note 是可直接展示给用户的中文原因。别自己按聚合状态判断能不能用 —— 同一份模板在阿里云与在新网的审核状态是分开的 |
template_gate | ok=false 时 msg 即为第 ⑩ 条闸门的拒绝原因(同时也会出现在 blockers 里)。提交前必须先让它为 ok=true,否则提交会被拒绝 |
deliver.mode | 恒为 manual:我们的注册商通道当前没有自动注册能力,一律由人工在注册商控制台办理 —— 如实告知,不做「下单即开通」的虚假承诺 |
② 提交注册单(扣余额) POST /api/v1/domain/register
提交前必须先调 ① 预检(can_submit=true),并带上 registrar + template_id:
实名模板要求按注册商不同 —— 阿里云/新网这类需实名审核的注册商,template_id 必须指向一份
在该注册商处审核通过(status=2)的模板;海外注册商(如 us2)不要求审核,但要求模板的
注册人姓名 / 邮箱 / 电话齐备。两者缺一都会被拒绝,且拒绝原因在预检的 blockers 里已经写明。
curl -X POST "https://wapi.gzisp.net/api/v1/domain/register" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Idempotency-Key: 7f3c1a92-你的唯一请求号" \
-H "Content-Type: application/json" \
-d '{"domain":"example.cn","years":1,"registrar":"us2","template_id":222,"remark":""}'
{
"ok": true,
"data": {
"id": 128,
"domain": "example.cn",
"msg": "注册申请已提交(单号 #128),已扣除 ¥50.00。",
"status": "pending",
"status_label": "待受理",
"deliver_mode": "manual"
}
}
流程:提交(扣款)→ 运营受理「办理中」→ 人工在注册商处完成 → 交付(写入域名台账)。 在「待受理」阶段可随时撤回并全额退回余额;已进入「办理中」则需联系客服。 若最终因域名被抢注 / 资质不符无法办理,将全额退款。
③ 查询我的注册单 GET /api/v1/domain/register/orders?limit=50
返回 items[],字段含 id / domain / years / price_fmt / status_label / can_cancel / create_time 等。
④ 撤回待受理注册单(退回余额) POST /api/v1/domain/register/cancel
curl -X POST "https://wapi.gzisp.net/api/v1/domain/register/cancel" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Idempotency-Key: 9ab0-撤回请求号" \
-H "Content-Type: application/json" \
-d '{"id":128}'
只有 can_cancel=1(待受理)的单据可撤回。撤回后款项原路退回会员余额,同时冲减累计消费额。该端点同样需要幂等键 —— 重复提交不会重复退款。
解析记录直接决定域名能不能被访问,所以三个端点分两种权限:列表只读,增删属交易(会推送到解析平台)。
① 列表 GET https://wapi.gzisp.net/api/v1/dns/records?domain_id=域名ID 只读
curl "https://wapi.gzisp.net/api/v1/dns/records?domain_id=215" \ -H "Authorization: Bearer sk-你的密钥"
{
"ok": true,
"data": {
"domain_id": 215,
"domain": "example.com",
"dns_provider": "cloudflare",
"dns_provider_label": "Cloudflare",
"types": ["A", "CNAME", "MX", "TXT", "NS", "AAAA", "SRV"],
"total": 1,
"warnings": [],
"items": [
{ "id": 1066, "rr": "www", "type": "A", "value": "1.2.3.4", "ttl": 600,
"mx": 0, "line": "默认", "status": 1,
"sync_status": 5, "sync_status_label": "待推送",
"create_time": "…", "update_time": "…" }
]
}
}
domain_id 取自你在本平台的域名台账(会员中心域名列表 / 后台域名管理里的 ID)。items[].id 就是后续增删要用的 rid。本平台不回传上游记录 ID(那是内部句柄),对外稳定标识只有 id。
② 新增 / 修改 POST https://wapi.gzisp.net/api/v1/dns/records/save 交易
curl -X POST "https://wapi.gzisp.net/api/v1/dns/records/save" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: dns-add-20260925-0001" \
-d '{"domain_id":215,"rr":"www","type":"A","value":"1.2.3.4","ttl":600,"line":"默认","status":1}'
| 字段 | 必填 | 说明 |
|---|---|---|
| domain_id | 是 | 域名台账 ID |
| rid | 否 | 传 = 修改该记录;不传 = 新增。rid 必须属于当前账户 |
| rr | 是 | 主机记录,如 www / @ / * |
| type | 是 | 只支持 A / CNAME / MX / TXT / NS / AAAA / SRV |
| value | 是 | 记录值(IP / 目标域名 / 文本) |
| ttl | 否 | 默认 600,最小 1 |
| mx | 否 | MX 优先级,默认 0 |
| line | 否 | 解析线路,默认「默认」 |
| status | 否 | 1=启用 0=暂停,默认 0(暂停)。要启用请显式传 1 |
{
"ok": true,
"data": {
"id": 1066, "domain_id": 215, "action": "create",
"msg": "解析记录已添加",
"record": { "id": 1066, "rr": "www", "type": "A", "value": "1.2.3.4", "ttl": 600,
"mx": 0, "line": "默认", "status": 1, "sync_status": 5,
"sync_status_label": "待推送", "create_time": "…", "update_time": "…" },
"dns_push": { "pushed": false, "pending": true, "status": 5,
"msg": "已构造注册商提交报文(liveSend 未开启,未实际发送…)" }
}
}
③ 删除 POST https://wapi.gzisp.net/api/v1/dns/records/delete 交易
curl -X POST "https://wapi.gzisp.net/api/v1/dns/records/delete" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: dns-del-20260925-0002" \
-d '{"rid":1066}'
🔴 必须看懂 dns_push:本平台解析记录以本地台账为权威,写入会同时尝试推送到该域名的解析平台。
pushed=false 表示记录已写入平台台账但未真实生效(常见原因 status=5:该解析平台后台未开启 liveSend,或 status=4:API 密钥未配置)。
这不是失败,但也不等于解析已生效 —— 请按 dns_push.msg 处理,或到后台开启对应解析平台的实时推送后再改一次。
修改时若改变了记录类型(如 A → CNAME),平台会按「删旧 + 加新」处理(部分解析平台只能改同类型记录的值),因此记录 ID 保持不变但上游是重建的。同一 Idempotency-Key 重复提交不会重复创建记录。
续费分两步:先报价 / 资格预判(不扣款),确认后再提交续费(扣余额)。两个端点都属「交易族」,因此都要求密钥勾选交易权限。
① 报价 + 资格 GET https://wapi.gzisp.net/api/v1/domain/renew/quote?domain_id=域名ID&years=年数 交易
curl "https://wapi.gzisp.net/api/v1/domain/renew/quote?domain_id=215&years=2" \ -H "Authorization: Bearer sk-你的密钥"
{
"ok": true,
"data": {
"domain_id": 215, "domain": "example.com", "years": 2,
"priced": true, "unit_price": 100.00, "total": 200.00, "currency": "CNY",
"price_src": "Lv2 续费价", "price_msg": "",
"eligible": true, "reason": "",
"phase": "normal", "phase_label": "正常",
"expired_days": 0, "grace_days": 30, "redemption_days": 30,
"grace_end": "", "redemption_end": "",
"transfer_status": 0, "transfer_label": "正常",
"end_time": "2027-09-03 13:10:53",
"max_years": 10,
"live": false, "can_submit": true,
"note": "可提交续费:POST /api/v1/domain/renew(需 Idempotency-Key)。⚠️ 平台当前为续费沙箱…"
}
}
| 字段 | 含义 |
|---|---|
| priced | 是否已定价。false 时 unit_price / total 为 null,且 can_submit=false —— 本平台不提供兜底价 |
| eligible / reason | 是否可续费及原因(未过期 / 宽限期可续;赎回期、删除期、已转出均不可续费) |
| phase | normal 正常 · grace 续费宽限期 · redemption 赎回期(需走赎回流程,普通续费不可用)· deletion 删除期 · transfer 已转出/已失效 |
| transfer_status | 0 正常 · 1 转出中 · 2 已转出 · 3 已失效。大于 0 一律不可续费 |
| max_years | 单次可续的最大年数(由注册商规则决定,通常 10) |
| live | 平台续费开关。false = 沙箱:提交后不会真实扣费 / 延长到期,见下 |
② 提交续费 POST https://wapi.gzisp.net/api/v1/domain/renew 交易
curl -X POST "https://wapi.gzisp.net/api/v1/domain/renew" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: renew-20260925-0001" \
-d '{"domain_id":215,"years":2}'
| 字段 | 必填 | 说明 |
|---|---|---|
| domain_id | 是 | 域名台账 ID,必须属于当前账户 |
| years | 否 | 续费年数,默认 1,取值 1~10 |
{
"ok": true,
"data": {
"domain_id": 215, "domain": "example.com", "years": 2,
"price": 200.00, "currency": "CNY",
"status": "sandbox",
"live": false,
"effective": false,
"end_time": "2027-09-03 13:10:53",
"msg": "沙箱模式:校验通过(2 年 ¥200.00,余额充足),未真实扣费/未推送注册商。",
"warn": "平台当前处于续费沙箱模式(renew_live=0):本次**未扣费、未延长到期、未推送注册商**…"
}
}
🔴 必须看懂 effective:平台续费通道受总开关控制,默认处于沙箱模式。
此时 status="sandbox" 且 effective=false,表示
本次没有扣费、没有延长到期、也没有向注册商发起任何请求 —— 它只代表「校验通过 + 报价」,不是已续费。
ok=true 只说明请求被平台接受,请务必以 effective 判断是否真正生效。
真实生效时返回 status="success" / effective=true,并回带新的 end_time。
常见拒绝:unpriced(该后缀未定价,不会兜底成交)·
renew_denied(资格不符:赎回期 / 删除期 / 已转出 / 已失效,原因见 message)·
insufficient_balance(余额不足:平台在向注册商发起续费之前就已拦截,
本次未向注册商提交任何操作、未产生任何费用,充值后重试即可)·
balance_check_failed(平台读余额失败,按 fail-closed 处理:同样未发起任何操作,稍后重试)·
renew_failed(502:平台已尝试真实续费但注册商侧失败或尚未接入,未产生任何变更,可用同一 Idempotency-Key 重试)。
同一 Idempotency-Key 重复提交不会重复扣费。
🔴 status="unpaid"(挂账,务必单独处理):
极端情形下,注册商侧已经续费生效,但平台侧结算(扣减余额)失败(例如同一账户的余额被另一笔并发消费抢走)。
此时返回 ok=true、effective=true、settled=false,
表示「事办成了、钱没扣到」,已挂账待人工补扣。
请勿重复提交 —— 注册商侧的续费已经发生,重复提交会在注册商侧再续一年。
用同一 Idempotency-Key 重发只会拿到这份同样的结果。
转移也是两步:先报价 / 资格预判,确认后再提交。三个方向共用同一组端点,靠 direction 区分:in 转入 · out 转出 · onsite 站内过户。整族都要求交易权限。
费用与扣款口径(与注册 / 续费不同,务必看清):
转出不计费(域名离开本平台,本平台不收费)· 转入按年计价 · 站内过户按「过户 / PUSH」价按次计。
🔴 转入与过户是「受理即落单」,提交时不预扣款 —— 由后台审核通过、并确认收款后按单据执行。
🔴 但有价方向在提交时会先过「余额闸门」:按报价做一次余额预检,不足即返回
insufficient_balance(不改库、不落单、不产生任何费用)。
这样余额为 0 的调用方不会把单据堆进后台、让运营先干活后收钱。
转出(合计 0)天然通过,不会被误拦。
① 报价 + 资格 GET https://wapi.gzisp.net/api/v1/domain/transfer/quote 交易
| direction | 必填参数 | 说明 |
|---|---|---|
| in | domain · target_registrar | 可选 years(默认 1)。此方向会查询 RDAP,用于判定是「同注册商内部转移」(免转移密码)还是「跨注册商转移」(需转移密码) |
| out | domain_id | 可选 target_registrar:留空 = 转出到本平台之外;填「与本域名当前注册商相同」= 同商内转给他人(需 target_account)。填一个别的本平台注册商会被拒绝 —— 那属于「转入到本平台另一家」,当成转出办会让域名真的离开本平台 |
| onsite | domain_id · target_user | 接收方填本平台会员的会员ID / 手机号 / 邮箱(需与本平台注册信息完全一致) |
curl "https://wapi.gzisp.net/api/v1/domain/transfer/quote?direction=in&domain=example.com&target_registrar=aliyun&years=1" \ -H "Authorization: Bearer sk-你的密钥"
{
"ok": true,
"data": {
"direction": "in", "direction_label": "转入",
"kind": "external", "kind_label": "跨注册商转移",
"need_auth_code": true, "need_target_account": false, "need_target_user": false,
"domain_id": 0, "domain": "example.com", "suffix_id": 2, "suffix_name": ".com",
"years": 1, "level": 2,
"target_registrar": "aliyun", "target_registrar_name": "阿里云",
"source_registrar": "xinnet", "source_registrar_name": "新网",
"rdap_status": 1, "rdap_registrar": "Xin Net Technology Corporation",
"eligible": true, "priced": true, "free": false,
"unit_price": 85.00, "total": 85.00, "currency": "CNY", "price_note": "Lv2 转入价",
"candidates": [
{
"code": "aliyun", "name": "阿里云", "priced": 1,
"price": 85.00, "msg": "Lv2 转入价", "note": "该注册商已接入自动转入接口。"
}
],
"msg": "源注册商为「新网」,目标为「阿里云」,两者不同 ⇒ 属**跨注册商转移**,需要转移密码。",
"note": "",
"can_submit": true, "blocked_reason": "", "warn": ""
}
}
| 字段 | 含义 |
|---|---|
| kind | internal 同注册商内部转移(免转移密码,需对方会员信息)· external 跨注册商转移(需转移密码)· onsite 本站内过户 |
| need_auth_code | 提交时是否必须带 auth_code(转移密码 / EPP Code) |
| eligible | 该域名是否具备转移资格。已转出 / 已失效 / 已锁定 / 状态不支持 均为 false |
| priced / free | 是否已定价 / 是否本就免费(转出 free=true)。priced=false 仍可提交(受理即落单),但后台补齐定价前不会交付 —— 见 warn |
| candidates | 仅 in:该后缀下已开通转入的注册商及各报价(未定价如实标 priced=0,绝不兜底) |
| can_submit | 判据是否通过。false 时请勿提交,原因见 blocked_reason |
② 提交 POST https://wapi.gzisp.net/api/v1/domain/transfer 交易
| 字段 | 必填 | 说明 |
|---|---|---|
| direction | 是 | in / out / onsite |
| domain | direction=in | 要转入的域名 |
| domain_id | out / onsite | 要转出 / 过户的域名台账 ID,必须属于当前账户 |
| target_registrar | in | 目标注册商代码(转出可留空 = 转出本平台之外) |
| auth_code | 跨商转入 | 转移密码。🔴 仅入库保存,任何接口都不回显;订单里只给脱敏值 auth_masked,且单据到终局即清空 |
| target_account | 同商内转给他人 | 对方在该注册商的会员信息 |
| target_user | onsite | 接收方(本平台会员ID / 手机号 / 邮箱) |
| years | 否 | 仅 in 有意义,默认 1 |
| remark | 否 | 备注(≤500 字) |
curl -X POST "https://wapi.gzisp.net/api/v1/domain/transfer" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-20260925-0001" \
-d '{"direction":"in","domain":"example.com","target_registrar":"aliyun","auth_code":"EPP-CODE-XXXX","years":1}'
{
"ok": true,
"data": {
"id": 47,
"direction": "in", "direction_label": "转入",
"domain": "example.com",
"kind": "external", "kind_label": "跨注册商转移",
"status": "pending", "status_label": "待审核",
"priced": true, "total": 85.00, "currency": "CNY",
"need_auth_code": true,
"msg": "转入申请已提交,等待审核。",
"warn": ""
}
}
③ 我的转移单 GET https://wapi.gzisp.net/api/v1/domain/transfer/orders?limit=50 交易
items[] 含:id / direction / kind / domain /
status(0 待审核 · 1 已通过待执行 · 2 已完成 · 3 已驳回 · 4 已撤回)/
priced / price / auth_masked / can_cancel / next。
🔴 不返回 auth_code(连脱敏值也仅在开放状态给)。
④ 撤回 POST https://wapi.gzisp.net/api/v1/domain/transfer/cancel 交易
curl -X POST "https://wapi.gzisp.net/api/v1/domain/transfer/cancel" \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-cancel-20260925-0001" \
-d '{"id":47}'
只有「待审核」的单据可撤回(已通过说明线上已在办理,撤回会让单据与实际不一致)。
可能被拒绝的情形:transfer_rejected(资格不符:域名已在本平台、后缀未收录或未开通转入、已有待处理单据、接收方无效等,原因见 message)·
invalid_direction(direction 不是 in / out / onsite)·
unpriced 只影响交付,不会阻止受理。
错误统一返回 error 结构(含 message / type / code 三个字段):
| HTTP | code | 含义 |
|---|---|---|
| 401 | invalid_api_key | 缺少 / 无效 / 已吊销 / 已过期的 API Key |
| 403 | key_scope_denied | 密钥作用域不含本域名(如密钥限定为「仅 AI Token 接口」) |
| 403 | key_trade_not_allowed | 该密钥未勾选「交易 / 下单」权限,不能调用写入类端点 |
| 403 | api_access_disabled | 账户未开启「开放 API 访问」总开关 |
| 400 | missing_domain | 缺少 domain 参数 |
| 400 | invalid_domain | 域名格式不合法 |
| 400 | invalid_action | action 只支持 register / renew / transfer |
| 400 | missing_domain_id | 缺少 domain_id 参数(解析记录 / 续费端点;转移族的缺参走 transfer_rejected) |
| 400 | missing_record_id | 缺少 rid 参数(解析记录删除) |
| 404 | domain_not_found | 域名不存在或不属于当前账户 |
| 404 | record_not_found | 解析记录不存在或不属于当前账户 |
| 400 | invalid_type | 解析记录类型不在白名单内 |
| 400 | empty_fields | 主机记录 rr 与记录值 value 均不能为空 |
| 400 | apex_ns_managed | 顶点 NS(rr 为 @ 或域名本身的 NS 记录)由「切换 DNS 服务商」统一管理,解析记录端点不提供新增 / 修改 —— 它的权威位置在注册局侧的委派 NS |
| 400 | invalid_idempotency_key | 缺少或格式非法的 Idempotency-Key(8~64 位字母数字与 - _) |
| 400 | missing_id | 缺少 id(单据编号) |
| 400 | order_rejected | 下单未通过校验(原因在 message 里,多为未实名 / 未定价 / 已注册等) |
| 400 | cancel_rejected | 撤回未通过(单据不存在 / 已进入办理中) |
| 400 | unpriced | 该后缀未定价,无法成交(平台不提供兜底价,请先联系管理员配置) |
| 400 | renew_denied | 续费资格不符(赎回期 / 删除期 / 已转出 / 已失效),原因见 message |
| 400 | insufficient_balance | 余额不足:message 里给出所需金额与当前余额。注册 / 续费 / 转入方向都会返回它,且平台不会向上游(注册商)提交任何操作、不产生任何费用 |
| 400 | balance_check_failed | 平台读余额失败(系统问题,不是你没钱)。按 fail-closed 处理:不向上游提交任何操作,稍后重试 |
| 400 | renew_rejected | 续费被拒绝(其它业务原因,见 message) |
| 400 | invalid_direction | 转移 direction 不是 in / out / onsite |
| 400 | transfer_rejected | 转移未通过资格判定(域名已在本平台 / 后缀未收录或未开通转入 / 已有待处理单据 / 需转移密码 / 接收方无效等,原因见 message) |
| 502 | renew_failed | 平台已尝试真实续费但注册商侧失败 / 尚未接入。未产生任何变更,可用同一幂等键重试 |
| 409 | idempotency_key_in_use | 相同幂等键的请求正在处理中,请勿并发提交 |
| 409 | idempotency_key_reused | 该幂等键已用于内容不同的请求,请换一个新键 |
| 500 | internal_error | 服务端异常。未产生任何变更,可用同一幂等键重试 |
鉴权恒先于参数诊断:缺少或无效的密钥一律先返回 401 / 403,
即使请求同时还缺参数也不会先报 400 —— 所以排查时请先确认密钥,再看 400 系列。
另外,因缺参而失败的请求不会占用你带的 Idempotency-Key,改正后可沿用同一个键重发。
登录会员中心 → 左侧「账户」组 → API 密钥(/member/apikeys)。两个产品域名(aiapi / wapi)共用同一套密钥体系,靠「用途」区分;密钥共用,但调用地址按产品域不同:
生成多把密钥,分别用于不同系统 每把可设有效期(或长期有效) 每把可选用途:全部只读 / 仅 AI Token 接口 / 仅网站基础产品接口 需要下单时另勾「交易 / 下单」权限 随时独立吊销
「产品域」与「交易权限」是两件事:产品域决定这把密钥能访问哪个域名(不选 = 两个都只读可用); 而「交易 / 下单」是一个必须单独勾选的权限位 —— 不勾选时这把密钥即使泄露也只能读,下不了单、扣不了款、改不了解析。 要调用写入类端点,请勾选「交易 / 下单」,并确认产品域包含网站 / 域名基础产品接口。
还需在会员中心 → 安全中心 打开「开放 API 访问」总开关,密钥才会生效;关闭该开关会立即拒绝该账户下的全部调用。