网站 / 域名基础产品 API(Open API)

本域名(wapi.gzisp.net)是「域名、网站基础产品」开放接口的统一入口。接口已开发完成(只读 + 写入类),但当前已由管理员关闭,暂不可调用 —— 下面的说明请当作开放后的接入参考。

⚠️ 本平台 API 服务当前未开放。 管理员已在后台关闭对外 API:下面文档中的全部端点此刻都会返回 403 api_global_disabled(密钥正确也一样;你的密钥与配额都会被保留,开放后原样可用)。 本页仅作接入说明保留,请等平台开放后再联调。

i域名用途说明

我们按产品类型拆分了对外 API 域名,请按需使用:

1鉴权方式

所有请求需在请求头携带会员专属 API Key(在会员中心「API 密钥」页生成,支持多把、可选用途、可独立吊销):

# 方式一:Authorization 头(推荐)
Authorization: Bearer sk-你的密钥

# 方式二:X-Api-Key 头
X-Api-Key: sk-你的密钥

# 方式三:查询参数(仅调试用)
?api_key=sk-你的密钥

密钥明文仅在生成时显示一次,请妥善保存。泄露后可随时在会员中心吊销,对应调用立即失效。

2接口总览

所有端点以 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),并明确标注 「上游已生效、差额已挂账、请勿重复提交」 —— 这类码不是可重试的失败。

3密钥自检

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 —— 与其等到下单时才失败,建议先跑一次自检。

4域名可用性与价格试算

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 的转入价未配置" }
    }
  }
}
字段说明
availabletrue 可注册 / false 已被注册 / null 无法判定(权威来源不可达,详见 availability_note)
availability_sourcerdap 注册局 RDAP / platform 本平台台账 / unverifiable 不可核验
price.*.okfalse 表示该动作尚未定价,此时 price 为 null。平台不会给出估算价 —— 未定价即以后台配置为准

5域名注册信息(RDAP / WHOIS)

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 下的到期时间、状态等明细。

6后缀与价格表

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 的顶层。

7域名注册下单(写入类 · 交易)

这一组端点会真实扣减会员余额。两道额外的闸门必须先过: ① 密钥须勾选「交易 / 下单」权限(否则 403 key_trade_not_allowed); ② 每个变更类请求必须携带 Idempotency-Key(否则 400 invalid_idempotency_key)。

关于 Idempotency-Key(为什么必须带)

网络超时(客户端收到 504、但服务端其实已经扣款成功)是常态,客户端一定会重试。幂等键保证同一个键 + 同一份请求体只会真正执行一次:

键的格式: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_unverifiedtrue 表示可用性无法核验(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_gateok=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(待受理)的单据可撤回。撤回后款项原路退回会员余额,同时冲减累计消费额。该端点同样需要幂等键 —— 重复提交不会重复退款。

8解析记录(DNS)

解析记录直接决定域名能不能被访问,所以三个端点分两种权限:列表只读,增删属交易(会推送到解析平台)。

① 列表 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 重复提交不会重复创建记录。

9域名续费(写入类 · 交易)

续费分两步:先报价 / 资格预判(不扣款),确认后再提交续费(扣余额)。两个端点都属「交易族」,因此都要求密钥勾选交易权限。

① 报价 + 资格 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是否可续费及原因(未过期 / 宽限期可续;赎回期、删除期、已转出均不可续费)
phasenormal 正常 · grace 续费宽限期 · redemption 赎回期(需走赎回流程,普通续费不可用)· deletion 删除期 · transfer 已转出/已失效
transfer_status0 正常 · 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 重发只会拿到这份同样的结果。

10域名转入 / 转出 / 站内过户(写入类 · 交易)

转移也是两步:先报价 / 资格预判,确认后再提交。三个方向共用同一组端点,靠 direction 区分:in 转入 · out 转出 · onsite 站内过户。整族都要求交易权限。

费用与扣款口径(与注册 / 续费不同,务必看清): 转出不计费(域名离开本平台,本平台不收费)· 转入按年计价 · 站内过户按「过户 / PUSH」价按次计。 🔴 转入与过户是「受理即落单」,提交时不预扣款 —— 由后台审核通过、并确认收款后按单据执行。 🔴 但有价方向在提交时会先过「余额闸门」:按报价做一次余额预检,不足即返回 insufficient_balance(不改库、不落单、不产生任何费用)。 这样余额为 0 的调用方不会把单据堆进后台、让运营先干活后收钱。 转出(合计 0)天然通过,不会被误拦。

① 报价 + 资格 GET https://wapi.gzisp.net/api/v1/domain/transfer/quote 交易

direction必填参数说明
indomain · target_registrar可选 years(默认 1)。此方向会查询 RDAP,用于判定是「同注册商内部转移」(免转移密码)还是「跨注册商转移」(需转移密码)
outdomain_id可选 target_registrar:留空 = 转出到本平台之外;填「与本域名当前注册商相同」= 同商内转给他人(需 target_account)。填一个别的本平台注册商会被拒绝 —— 那属于「转入到本平台另一家」,当成转出办会让域名真的离开本平台
onsitedomain_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": ""
  }
}
字段含义
kindinternal 同注册商内部转移(免转移密码,需对方会员信息)· 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
domaindirection=in要转入的域名
domain_idout / onsite要转出 / 过户的域名台账 ID,必须属于当前账户
target_registrarin目标注册商代码(转出可留空 = 转出本平台之外)
auth_code跨商转入转移密码。🔴 仅入库保存,任何接口都不回显;订单里只给脱敏值 auth_masked,且单据到终局即清空
target_account同商内转给他人对方在该注册商的会员信息
target_useronsite接收方(本平台会员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 只影响交付,不会阻止受理。

11错误码

错误统一返回 error 结构(含 message / type / code 三个字段):

HTTPcode含义
401invalid_api_key缺少 / 无效 / 已吊销 / 已过期的 API Key
403key_scope_denied密钥作用域不含本域名(如密钥限定为「仅 AI Token 接口」)
403key_trade_not_allowed该密钥未勾选「交易 / 下单」权限,不能调用写入类端点
403api_access_disabled账户未开启「开放 API 访问」总开关
400missing_domain缺少 domain 参数
400invalid_domain域名格式不合法
400invalid_actionaction 只支持 register / renew / transfer
400missing_domain_id缺少 domain_id 参数(解析记录 / 续费端点;转移族的缺参走 transfer_rejected)
400missing_record_id缺少 rid 参数(解析记录删除)
404domain_not_found域名不存在或不属于当前账户
404record_not_found解析记录不存在或不属于当前账户
400invalid_type解析记录类型不在白名单内
400empty_fields主机记录 rr 与记录值 value 均不能为空
400apex_ns_managed顶点 NS(rr 为 @ 或域名本身的 NS 记录)由「切换 DNS 服务商」统一管理,解析记录端点不提供新增 / 修改 —— 它的权威位置在注册局侧的委派 NS
400invalid_idempotency_key缺少或格式非法的 Idempotency-Key(8~64 位字母数字与 - _)
400missing_id缺少 id(单据编号)
400order_rejected下单未通过校验(原因在 message 里,多为未实名 / 未定价 / 已注册等)
400cancel_rejected撤回未通过(单据不存在 / 已进入办理中)
400unpriced该后缀未定价,无法成交(平台不提供兜底价,请先联系管理员配置)
400renew_denied续费资格不符(赎回期 / 删除期 / 已转出 / 已失效),原因见 message
400insufficient_balance余额不足:message 里给出所需金额与当前余额。注册 / 续费 / 转入方向都会返回它,且平台不会向上游(注册商)提交任何操作、不产生任何费用
400balance_check_failed平台读余额失败(系统问题,不是你没钱)。按 fail-closed 处理:不向上游提交任何操作,稍后重试
400renew_rejected续费被拒绝(其它业务原因,见 message)
400invalid_direction转移 direction 不是 in / out / onsite
400transfer_rejected转移未通过资格判定(域名已在本平台 / 后缀未收录或未开通转入 / 已有待处理单据 / 需转移密码 / 接收方无效等,原因见 message)
502renew_failed平台已尝试真实续费但注册商侧失败 / 尚未接入。未产生任何变更,可用同一幂等键重试
409idempotency_key_in_use相同幂等键的请求正在处理中,请勿并发提交
409idempotency_key_reused该幂等键已用于内容不同的请求,请换一个新键
500internal_error服务端异常。未产生任何变更,可用同一幂等键重试

鉴权恒先于参数诊断:缺少或无效的密钥一律先返回 401 / 403, 即使请求同时还缺参数也不会先报 400 —— 所以排查时请先确认密钥,再看 400 系列。 另外,因缺参而失败的请求不会占用你带的 Idempotency-Key,改正后可沿用同一个键重发。

★如何获取密钥

登录会员中心 → 左侧「账户」组 → API 密钥(/member/apikeys)。两个产品域名(aiapi / wapi)共用同一套密钥体系,靠「用途」区分;密钥共用,但调用地址按产品域不同:

生成多把密钥,分别用于不同系统 每把可设有效期(或长期有效) 每把可选用途:全部只读 / 仅 AI Token 接口 / 仅网站基础产品接口 需要下单时另勾「交易 / 下单」权限 随时独立吊销

「产品域」与「交易权限」是两件事:产品域决定这把密钥能访问哪个域名(不选 = 两个都只读可用); 而「交易 / 下单」是一个必须单独勾选的权限位 —— 不勾选时这把密钥即使泄露也只能读,下不了单、扣不了款、改不了解析。 要调用写入类端点,请勾选「交易 / 下单」,并确认产品域包含网站 / 域名基础产品接口。

还需在会员中心 → 安全中心 打开「开放 API 访问」总开关,密钥才会生效;关闭该开关会立即拒绝该账户下的全部调用。

本接口由系统自动生成文档 · 直接访问对外 API 域名(wapi.gzisp.net)即看到此页 · 业务调用请用会员中心签发的密钥