English · 简体中文 · 繁體中文 · 日本語 · Русский · Bahasa Indonesia · Deutsch · Français · 한국어 · العربية
[返回项目介绍](../README_ZH.md) 通过 API 注册域名、管理 DNS、更新动态 IP，并自动化账户操作。示例统一使用 DNSHE API 地址和占位凭据；请将示例域名、ID 和密钥替换为你自己的资源。 ## 目录 - [快速开始](#快速开始) - [认证与请求约定](#认证与请求约定) - [域名管理](#域名管理) - [DNS 记录管理](#dns-记录管理) - [动态 DNS（DDNS）](#动态-dnsddns) - [API 密钥管理](#api-密钥管理) - [域名转赠](#域名转赠) - [配额查询](#配额查询) - [WHOIS 查询](#whois-查询) - [错误处理与速率限制](#错误处理与速率限制) - [客户端示例](#客户端示例) - [安全建议与常见问题](#安全建议与常见问题) - [技术支持](#技术支持) ## 快速开始 ```text https://api005.dnshe.com/index.php?m=domain_hub ``` 基础地址已包含 `m=domain_hub`，追加路由参数时使用 `&`。除 GET 查询参数外，请求与响应使用 JSON。普通鉴权请求默认每分钟 60 次，运营方可调整；功能可用性取决于账户和部署配置。命令示例使用 Bash/sh，请先配置下列环境变量。 ```bash export DNSHE_API_KEY='replace-with-your-api-key' export DNSHE_API_SECRET='replace-with-your-api-secret' export DNSHE_DDNS_TOKEN='replace-with-your-ddns-token' ``` ## 认证与请求约定 首次密钥请在客户中心 → [管理域名](https://my.dnshe.com/index.php?m=domain_hub) → API 管理中创建。鉴权请求必须携带 `X-API-Key` 和 `X-API-Secret` 请求头，URL 或请求体传递凭据的方式已禁用。GET 参数放在查询字符串中，写操作使用 JSON 并设置 `Content-Type: application/json`。`endpoint` 选择资源，`action` 选择操作；`quota` 和 `whois` 无需 `action`。DDNS 使用单独的 Token。 ## 域名管理 ### 1.1 列出域名 `GET` · `endpoint=subdomains` · `action=list` #### 参数 - `page` — `integer`; 可选; 默认值 / 范围: `1`. - `cursor_id` — `integer`; 可选. - `per_page` — `integer`; 可选; 默认值 / 范围: `200; 1–500`. - `include_total` — `boolean`; 可选; 默认值 / 范围: `false`. - `search` — `string`; 可选. - `rootdomain` — `string`; 可选. - `status` — `string`; 可选; 默认值 / 范围: `active | suspended | expired`. - `created_from / created_to` — `string`; 可选; 默认值 / 范围: `YYYY-MM-DD`. - `sort_by` — `string`; 可选; 默认值 / 范围: `id`. - `sort_dir` — `string`; 可选; 默认值 / 范围: `desc; asc | desc`. - `fields` — `string`; 可选; 默认值 / 范围: `all`. `page` 是从 1 开始的兼容页码。大数据量推荐首次传 `cursor_id=0`；当 `pagination.has_more=true` 时，将 `pagination.next_cursor_id` 用作下次游标，变为 false 时停止。游标模式固定按 ID 排序，不使用 OFFSET。`per_page` 默认 200、最大 500，建议先用 50–100。`include_total=1` 会额外统计总数，大数据量时可能较慢。`search` 匹配前缀或根域名；`rootdomain`、`status`、`created_from`、`created_to` 用于过滤，日期格式为 YYYY-MM-DD。`sort_by` 支持 `id`、`created_at`、`updated_at`、`expires_at`、`subdomain`；`sort_dir` 为 `asc` 或 `desc`。 `fields` 为逗号分隔的字段列表或 `all`，支持 `id`、`subdomain`、`rootdomain`、`full_domain`、`status`、`created_at`、`updated_at`、`expires_at`、`never_expires`、`cloudflare_zone_id`、`provider_account_id`。自定义选择仍会补充 `id`。`count` 表示本次返回集合的数量，不应当作所有匹配域名的总数。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&cursor_id=0&per_page=100&fields=id,subdomain,rootdomain,status" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&search=test&rootdomain=de5.net&status=active&sort_by=expires_at&sort_dir=asc&per_page=50" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 响应示例 ```json { "success": true, "count": 2, "subdomains": [ { "id": 1, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active", "created_at": "2025-10-19 10:00:00", "updated_at": "2025-10-19 10:00:00" }, { "id": 2, "subdomain": "api", "rootdomain": "de5.net", "full_domain": "api.de5.net", "status": "active", "created_at": "2025-10-19 11:00:00", "updated_at": "2025-10-19 11:00:00" } ] } ``` ```json { "success": true, "count": 1, "subdomains": [ { "id": 901, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active" } ], "pagination": { "mode": "cursor", "page": 1, "per_page": 100, "has_more": true, "cursor_id": 0, "next_cursor_id": 901 } } ``` ### 1.2 注册域名 `POST` · `endpoint=subdomains` · `action=create` #### 参数 - `subdomain` — `string`; 必填. - `domain` — `string`; 必填. `subdomain` 是域名前缀，例如 `myapp`；`domain` 是可用根域名，例如 `de5.net`。注册使用 `action=create` 和请求字段 `domain`；响应中的 `rootdomain` 及同名列表过滤参数不是注册字段。仍需符合可用性和账户配额要求。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=create" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain": "myapp", "domain": "de5.net" }' ``` #### 响应示例 ```json { "success": true, "message": "Subdomain registered successfully", "subdomain_id": 3, "full_domain": "myapp.de5.net" } ``` ### 1.3 获取域名详情 `GET` · `endpoint=subdomains` · `action=get` #### 参数 - `subdomain_id` — `integer`; 必填. 使用当前鉴权账户拥有的域名 ID，响应包含域名对象、`dns_records` 与 `dns_count`。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=get&subdomain_id=1" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 响应示例 ```json { "success": true, "subdomain": { "id": 1, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active", "created_at": "2025-10-19 10:00:00", "updated_at": "2025-10-19 10:00:00" }, "dns_records": [ { "id": 1, "name": "test.de5.net", "type": "A", "content": "203.0.113.10", "ttl": 600, "priority": null, "status": "active", "created_at": "2025-10-19 10:05:00" } ], "dns_count": 1 } ``` ### 1.4 删除域名 `POST / DELETE` · `endpoint=subdomains` · `action=delete` #### 参数 - `subdomain_id` — `integer`; 必填. 删除账户名下的目标域名及关联 DNS 记录，响应通过 `dns_records_deleted` 报告删除数量。提交前请确认目标 ID。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 1 }' ``` #### 响应示例 ```json { "success": true, "message": "Subdomain deleted successfully", "subdomain_id": 1, "full_domain": "test.de5.net", "dns_records_deleted": 4 } ``` ### 1.5 续期域名 `POST / PUT` · `endpoint=subdomains` · `action=renew` #### 参数 - `subdomain_id` — `integer`; 必填. DNSHE 正常免费续期仍然免费，示例为 `charged_amount=0`。通用插件可配置收费赎回；涉及赎回时，请先确认域名状态和控制台规则。根据响应的 `previous_expires_at`、`new_expires_at`、`never_expires`、`remaining_days`、`charged_amount` 判断实际结果。 续期失败包括：HTTP 403 `renewal disabled`、`redemption period requires administrator`、`renewal window expired`；HTTP 422 且 `error_code=renewal_not_yet_available`；HTTP 402 `insufficient balance for redemption renewal`；HTTP 404 表示域名不存在或不属于当前账户。请检查续期窗口或联系支持，不要无间隔重试。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=renew" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 3 }' ``` #### 响应示例 ```json { "success": true, "message": "Subdomain renewed successfully", "subdomain_id": 3, "subdomain": "myapp", "previous_expires_at": "2027-05-01 00:00:00", "new_expires_at": "2028-05-01 00:00:00", "renewed_at": "2027-04-30 00:00:00", "never_expires": 0, "status": "active", "remaining_days": 367, "charged_amount": 0 } ``` ## DNS 记录管理 ### 2.1 列出 DNS 记录 `GET` · `endpoint=dns_records` · `action=list` #### 参数 - `subdomain_id` — `integer`; 必填. 优先使用列表或创建接口返回的模块 `id`，新公开记录使用 15 位外显 ID。`record_id` 是 DNS 供应商的记录标识。修改/删除至少提供其中一个，同时提供时必须指向同一记录，否则返回 `dns_record_identifier_mismatch`。旧内部 ID 继续兼容。参考文档说明纯数字 `record_id` 至少兼容至 2027-06-12，新调用请将模块 ID 放入 `id`。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=list&subdomain_id=1" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 响应示例 ```json { "success": true, "count": 2, "records": [ { "id": 1, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997", "name": "test.de5.net", "type": "A", "content": "203.0.113.10", "ttl": 600, "priority": null, "line": null, "proxied": false, "status": "active", "created_at": "2025-10-19 10:05:00", "updated_at": "2025-10-19 10:05:00" }, { "id": 2, "name": "www.test.de5.net", "type": "CNAME", "content": "test.de5.net", "ttl": 600, "priority": null, "proxied": false, "status": "active", "created_at": "2025-10-19 10:10:00" } ] } ``` ### 2.2 创建 DNS 记录 `POST` · `endpoint=dns_records` · `action=create` #### 参数 - `subdomain_id` — `integer`; 必填. - `type` — `string`; 必填. - `name` — `string`; 可选; 默认值 / 范围: `@`. - `content` — `string`; 可选. - `ttl` — `integer`; 可选; 默认值 / 范围: `600`. - `priority` — `integer`; 可选; 默认值 / 范围: `MX: 10; SRV: 0`. - `line` — `string`; 可选. - `record_weight / weight` — `integer`; 可选. - `record_port / port` — `integer`; 可选; 默认值 / 范围: `1–65535`. - `record_target / target` — `string`; 可选. - `caa_flag` — `integer`; 可选; 默认值 / 范围: `0; 0–255`. - `caa_tag` — `string`; 可选; 默认值 / 范围: `issue; 1–15 [A-Za-z0-9]`. - `caa_value` — `string`; 可选. `type` 支持 A、AAAA、CNAME、MX、TXT、NS、SRV、CAA。`name` 是相对于已注册域名的名称，省略、空值或 `@` 表示域名本身，不接受完整域名；通配符 `*` 只能位于最左侧标签。`content` 必填，除非由 SRV/CAA 结构化参数组装。`ttl` 默认 600 秒；`priority` 在 MX 中默认 10，在 SRV 中默认 0。 SRV 的 `record_weight`/`weight`、`record_port`/`port`、`record_target`/`target` 分别表示权重、端口（1–65535）和目标主机，目标 `.` 表示服务不可用。CAA 使用 `caa_flag`（0–255，默认 0）、`caa_tag`（1–15 位字母数字，默认 `issue`）和 `caa_value`。`line` 仅适用于 AliDNS，其他供应商拒绝非空值。 后台可通过 `disable_ns_management` 禁用 NS 写入。域名委派到外部 DNS 后，创建或修改非 NS 记录会返回 `external_dns_delegated`；删除旧记录、校准和过期清理不受此限制。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=create" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 1, "type": "A", "content": "203.0.113.10", "ttl": 600 }' ``` #### 响应示例 ```json { "success": true, "message": "DNS record created successfully", "id": 738492016583241, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" } ``` ### 2.3 修改 DNS 记录 `POST / PUT / PATCH` · `endpoint=dns_records` · `action=modify` #### 参数 - `id` — `integer`; 可选. - `record_id` — `string`; 可选. - `type / name / content` — `string`; 可选. - `ttl / priority` — `integer`; 可选. - `line` — `string`; 可选. - `record_weight / weight` — `integer`; 可选. - `record_port / port` — `integer`; 可选. - `record_target / target` — `string`; 可选. - `caa_flag` — `integer`; 可选. - `caa_tag / caa_value` — `string`; 可选. 提供 `id` 或 `record_id`，以及需要修改的字段。名称规则及 SRV/CAA 选项与创建相同。两个标识同时提供时必须指向同一记录，响应返回模块 ID 和供应商记录 ID。 优先使用列表或创建接口返回的模块 `id`，新公开记录使用 15 位外显 ID。`record_id` 是 DNS 供应商的记录标识。修改/删除至少提供其中一个，同时提供时必须指向同一记录，否则返回 `dns_record_identifier_mismatch`。旧内部 ID 继续兼容。参考文档说明纯数字 `record_id` 至少兼容至 2027-06-12，新调用请将模块 ID 放入 `id`。 后台可通过 `disable_ns_management` 禁用 NS 写入。域名委派到外部 DNS 后，创建或修改非 NS 记录会返回 `external_dns_delegated`；删除旧记录、校准和过期清理不受此限制。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=modify" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "id": 738492016583241, "type": "A", "content": "203.0.113.20", "ttl": 600 }' ``` #### 响应示例 ```json { "success": true, "message": "DNS record updated successfully", "id": 738492016583241, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" } ``` ### 2.4 删除 DNS 记录 `POST / DELETE` · `endpoint=dns_records` · `action=delete` #### 参数 - `id` — `integer`; 可选. - `record_id` — `string`; 可选. 优先使用列表或创建接口返回的模块 `id`，新公开记录使用 15 位外显 ID。`record_id` 是 DNS 供应商的记录标识。修改/删除至少提供其中一个，同时提供时必须指向同一记录，否则返回 `dns_record_identifier_mismatch`。旧内部 ID 继续兼容。参考文档说明纯数字 `record_id` 至少兼容至 2027-06-12，新调用请将模块 ID 放入 `id`。 #### 请求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "id": 1 }' ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" }' ``` #### 响应示例 ```json { "success": true, "message": "DNS record deleted successfully" } ``` ## 动态 DNS（DDNS） `GET / POST / PUT` · `endpoint=ddns` · `action=update` 在域名管理 → DDNS 中，为指定 A/AAAA 记录创建专用 Token。通过 `Authorization: Bearer