Beta 公告: 本 API 文档为 Beta 版本. 端点, 字段, 错误代码, 以及行为可能在不另行通知的情况下发生变化且不保证向后兼容. 请勿依赖它来处理关键生产工作流程.

快速上手我们的 RESTful API

Dynadot API 专为与您的系统无缝集成而设计。它具备可预测的面向资源 URL，支持 JSON 编码请求体，返回 JSON 与 XML 编码响应，并遵循标准 HTTP 方法、身份验证及响应代码。

你可以在测试模式和正式模式下使用 Dynadot API。具体使用哪种模式，取决于你用来验证请求的 API 密钥。测试模式允许你模拟并验证 API 集成，而不会影响线上数据或交易。

Dynadot API 主要专注于 域名管理、订单处理及相关服务。您可以执行注册、转移和续费域名，管理 DNS设置，以及查看或更新账户订单等操作。

温馨提示: 批量创建, 更新, 删除不受支持, 并且每种请求类型均仅限一个对象或操作.

生成您的 API 密钥

在开始发起任何 API 请求之前，务必先生成您的 API Key 和 API Secret。

这些密钥用于身份验证，也能确保你调用我们 API 时各项操作安全无虞。

你可以通过 账户设置 中的 API 部分同时生成 API Key 和 API Secret。

1. 登录您的 Dynadot 账户.

2. 前往 工具 > API.

3. 在此页面生成您的 API密钥 和 API 密钥.

加入我们的社区

有想法或建议? 直接与我们的专业工程师交流吧.

Discord

HTTP 方法

API 使用标准 HTTP 方法对资源执行操作:

方法描述
GETGET 请求: 获取指定资源的详细信息
POSTPOST 请求：创建新资源
PUTPUT 请求: 完整更新指定的资源
DELETEDELETE 请求: 删除指定的资源

URL

所有 API 请求的基础 URL 为：

https://api.dynadot.com/

完整的 URL 格式：

http://api.dynadot.com/restful/version_code/resource/{resource_identify}/action
示例 :
https://api.dynadot.com/restful/v2/domains/{domain_name}/search

版本

API 的当前版本是 v2.0.0

在构建 API 请求 URL 时，只需包含主版本即可。次版本和补丁更新均设计为向后兼容，不会引入破坏现有代码的变更。这样既能保证稳定性，又能让您无需修改实现，便可受益于渐进式改进和修复。

未来版本发布时，我们会在一段时间内继续兼容旧版本。新功能与重大变更将随主版本号的提升而引入。

标题

API 请求的标头包含请求的元数据。这些元数据为服务器正确处理请求提供了必不可少的上下文。常用的标头包括：

Content-Type

指定请求正文中发送数据的格式。服务器会据此正确解析请求。目前唯一可接受的值是：application/json

示例 :
Content-Type: application/json

接受

让服务器知晓客户端所期望的响应格式。

可能的值: application/json, application/xml

示例 :
Accept: application/json

授权

所有 API 请求都必须包含 API 密钥以进行身份验证。你可以在账户控制面板中获取 API 密钥。

您可以在 API 设置页面生成 API 密钥
身份验证头示例 :
Authorization: Bearer YOUR_API_KEY

X-Request-ID

X-Request-ID 请求头是一个 （可选） 请求头，用于唯一标识每个 API 请求。加入此请求头后，有助于跨系统和日志跟踪、关联请求，让调试与监控 API 活动更加轻松。

X-Request-ID 的值必须是有效的 UUID (通用唯一识别码), 遵循以下标准格式: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (例如, 123e4567-e89b-12d3-a456-426614174000).

示例 :
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

X-Signature 新建

X-Signature 标头是事务性请求的强制性安全机制, 包括获取敏感信息或更新数据的请求. 它要求客户端使用 HMAC-SHA256 对请求负载进行签名以确保 API 请求的真实性, 完整性, 以及不可否认性.

生成签名时，您需要用到以下各项值

1. API密钥: 您的专属 API 密钥.

2. 完整路径与查询: API 端点的完整路径以及查询参数.

3. X-Request-Id：请求 ID。如果拿不到，可以填一个空字符串。

4. 请求体: 请求正文. 如果它为空或 null, 您可以输入空字符串.

待签名字符串是上述值的组合, 按以下顺序拼接:

apiKey + "\n" + fullPathAndQuery + "\n" + (xRequestId or empty String) + "\n" + (requestBody or empty String)
示例
apiKey = "your_api_key"
fullPathAndQuery = "/restful/v2/some/endpoint?param=value"
xRequestId = "unique-request-id"
requestBody = "{\"key\":\"value\"}"

stringToSign = "your_api_key\n/restful/v2/some/endpoint?param=value\nunique-request-id\n{\"key\":\"value\"}"
生成 HMAC-SHA256 签名

构建 stringToSign 后, 使用 HMAC-SHA256 并以您的 密钥 作为密钥来计算签名, 然后对结果进行 Base64 编码.

签名按以下步骤生成:

1. 使用 HMAC-SHA256 算法.

2. 使用 stringToSign (UTF-8) 作为输入消息.

3. 将您的 secret (UTF-8) 用作密钥.

4. 将 HMAC 输出编码为 Base64 (标准 Base64)

将生成的 签名 作为请求头中 X-Signature 的值

Example :
X-Signature: {HMAC-SHA256 Signature}
Example Code :
import base64
import hashlib
import hmac
import uuid

def create_signature(api_key, api_secret, full_path_and_query, x_request_id, request_body=""):
    string_to_sign = (
        api_key + "\n" +
        full_path_and_query + "\n" +
        (x_request_id or "") + "\n" +
        (request_body or "")
    )

    digest = hmac.new(
        api_secret.encode("utf-8"),
        string_to_sign.encode("utf-8"),
        hashlib.sha256
    ).digest()

    return base64.b64encode(digest).decode("utf-8")

api_key = "your_api_key"
api_secret = "your_secret"
full_path_and_query = "/restful/v2/accounts/info"
x_request_id = str(uuid.uuid4())
request_body = ""

x_signature = create_signature(
    api_key,
    api_secret,
    full_path_and_query,
    x_request_id,
    request_body
)

print("X-Request-ID:", x_request_id)
print("X-Signature:", x_signature)

请求体

API 请求正文用于向服务器发送数据。它通常包含在 POST、PUT 或 PATCH 请求中（通常不用于 GET 或 DELETE 请求）。

内容格式

正文数据的格式由 Content-Type 标头决定. 常见格式包括:

JSON

典型用例

POST 请求: POST 方法用于在服务器上创建新资源. 请求体通常包含资源详情..

PUT 请求：PUT 方法用于通过完全替换来更新现有资源。请求体包含完整的更新后资源。

DELETE 请求: DELETE 方法用于从服务器上删除已有资源. 它没有请求体.

GET 请求: GET 方法用于从服务器中获取现有资源. 它没有请求体

响应格式

所有 API 响应均以 JSON 或 XML 格式返回, 正文数据的格式由 Accept 头决定, 提供所请求的数据或错误消息, 如适用.

内容格式

响应通常包含 3 个部分：Code、Message、Data

代码: 请求的状态

消息: 状态的更多说明

数据: 响应正文

JSON/XML

错误处理

HTTP 状态码是服务器返回的标准化三位数字, 如同请求结果的晴雨表, 用来表明客户端请求的结局. 它们提供关键信息, 说明请求是已成功处理, 需要进一步操作, 还是遇到了错误. 这些状态码分为五大类, 每一类代表一种不同的响应类型.

我们的 API 状态码遵循 HTTP/1.1 协议，这一广受认可的标准可确保通信一致、稳定可靠。借助 HTTP/1.1，我们利用持久连接、增强缓存等特性，优化客户端与服务器之间的交互。

2xx (成功): 表示命令已被接收并接受
4xx（客户端错误）：表示客户端在请求中出了错，例如提供了无效输入，或缺少适当授权。
5xx (服务器错误): 表示服务器遇到错误或无法完成该请求.

Webhook 概览

Webhooks 是自动化流程、集成系统的利器。它们让你能实时接收账户或域名设置中事件与变更的通知。配置 Webhook 后，便可根据特定事件触发外部系统操作、更新数据库或发送通知。

Dynadot API 支持各种事件的 webhook 通知，例如 域名注册、转移、续费和 过期时间，以便您能采取相应的应对措施。

要使用 webhook, 你需要提供一个 URL 端点, 用来接收通知. 你可以在 账户设置 中配置 webhook 的 URL, key 和 secret. 当事件发生时, Dynadot 会向指定的 URL 发送带有相关数据的 POST 请求.

Webhook 请求头

Webhook 请求头中包含了关于该请求的元数据，这些元数据为服务器妥善处理请求提供了必不可少的上下文。常用的请求头包括：

Content-Type

指定请求正文中发送数据的格式。服务器会据此正确解析请求。目前唯一可接受的值是：application/json

示例 :
Content-Type: application/json

授权

所有 Webhook 请求都会包含一个用于身份验证的 Webhook 密钥。你可以从账户仪表盘中获取你的 Webhook 密钥。

您可以在 API 设置页面管理您的 WEBHOOK_KEY
身份验证头示例 :
Authorization: Bearer WEBHOOK_KEY

X-Signature

X-Signature 请求头是事务型请求必备的安全机制，包括获取敏感信息或更新数据的请求。它要求客户端使用 HMAC-SHA256 对请求负载进行签名，从而确保 Webhook 请求的真实性、完整性和不可抵赖性。

生成签名时，您需要用到以下各项值

1. WEBHOOK 密钥: 您的专属 WEBHOOK 密钥.

2. 完整路径与查询：WEBHOOK 端点的完整路径以及查询参数。

3. X-Request-Id：请求 ID。如果拿不到，可以填一个空字符串。

4. 请求体: 请求正文. 如果它为空或 null, 您可以输入空字符串.

待签名字符串是上述值的组合, 按以下顺序拼接:

webhookKey + "\n" + fullPathAndQuery + "\n" + (xRequestId or empty String) + "\n" + (requestBody or empty String)
示例
webhookKey = "your_webhook_key"
fullPathAndQuery = "/v2/some/endpoint?param=value"
xRequestId = "unique-request-id"
requestBody = "{\"key\":\"value\"}"

stringToSign = "your_webhook_key\n/v2/some/endpoint?param=value\nunique-request-id\n{\"key\":\"value\"}"
生成 HMAC-SHA256 签名

构建 stringToSign 后, 使用 HMAC-SHA256 并以您的 密钥 作为密钥来计算签名, 然后对结果进行 Base64 编码.

签名按以下步骤生成:

1. 使用 HMAC-SHA256 算法.

2. 使用 stringToSign (UTF-8) 作为输入消息.

3. 将您的 secret (UTF-8) 用作密钥.

4. 将 HMAC 输出编码为 Base64 (标准 Base64)

将生成的 签名 作为请求头中 X-Signature 的值

Example :
X-Signature: {HMAC-SHA256 Signature}
Example Code :
import base64
import hashlib
import hmac
import uuid

def create_signature(webhook_key, webhook_secret, full_path_and_query, x_request_id, request_body=""):
    string_to_sign = (
        webhook_key + "\n" +
        full_path_and_query + "\n" +
        (x_request_id or "") + "\n" +
        (request_body or "")
    )

    digest = hmac.new(
        webhook_secret.encode("utf-8"),
        string_to_sign.encode("utf-8"),
        hashlib.sha256
    ).digest()

    return base64.b64encode(digest).decode("utf-8")

webhook_key = "your_webhook_key"
webhook_secret = "your_secret"
full_path_and_query = "/v2/some/webhook/path"
x_request_id = str(uuid.uuid4())
request_body = ""

x_signature = create_signature(
    webhook_key,
    webhook_secret,
    full_path_and_query,
    x_request_id,
    request_body
)

print("X-Request-ID:", x_request_id)
print("X-Signature:", x_signature)

Webhook 请求格式

内容格式

webhook 请求的请求体包含触发该通知的事件信息。请求体数据的格式由 Content-Type 标头决定，通常为 application/json。

请求正文包括以下参数:

示例：

JSON/XML

参数

请求正文包含以下参数：

参数描述
活动触发该通知的事件类型。
事件 ID触发该通知的事件 ID。
时间戳事件发生的时间戳.
数据与该事件关联的数据。

Webhook 响应格式

内容格式

webhook 请求的响应将以 JSON 格式发送, 具体取决于请求中指定的 Content-Type 头.

响应正文会说明请求的处理状态, 比如是已成功处理, 还是遇到了错误.

响应通常包含 1 个部分：状态

示例：

JSON/XML

速率限制

为确保安全，请求应通过 https（安全套接字）发送。同一时间只能处理 1 个请求，因此请等待当前请求完成后再发送下一个请求。

根据您账户的价格档位，您将获得不同的线程数：

价格档位线程数速率限制
普通会员1 个线程60/分钟 (1/秒)
黄金会员5 个线程600/分钟 (10/秒)
铂金会员35 个线程6000/分钟 (100/秒)

注意: place_auction_bid & get_auction_bid 目前不受上述速率限制约束.

示例 :

对于 域名评估 命令，你会根据账户的价格等级获得不同的允许请求次数：

价格档位速率限制
普通会员50/天
黄金会员100/天
铂金会员300/天
示例 :

沙盒

Dynadot API 沙盒环境让你能安心测试 API 集成，不会影响你的正式账户或真实资金。

如何访问沙盒

1. 登录您的 Dynadot 账户并前往 API 设置页面:

2. https://www.dynadot.com/account/domain/setting/api.html

3. 生成您的 API 沙盒 Key 和 API 沙盒 Secret Key。

4. 生成后，请稍等片刻，让系统有时间激活您的沙盒密钥并创建沙盒账户。

5. 您的沙盒账户将预先充值 10,000 的余额，涵盖所有支持的货币，供测试使用。

使用沙盒 API

沙盒环境中的 API 命令，在功能上与生产环境别无二致。

唯一的区别在于基础 URL:

生产环境 API URL: https://api.dynadot.com

沙盒 API URL: https://api-sandbox.dynadot.com

重要提示

沙盒环境中，部分 API 命令可能用不了。请查看具体命令文档，确认是否有 "支持 API 沙盒" 标记。

沙盒主要供测试使用。某些命令可能与生产环境有所不同，且沙盒 无法完全模拟所有可能出现的复杂场景 可在生产环境中找到。

变更日志概览

变更日志详细记录了 API 每个版本中引入的变更、改进、错误修复和新功能。它通过记录每次更新的影响，为用户和开发者提供透明度。它由两个关键部分组成：

API 版本

这部分重点介绍 API 的版本管理机制, 它帮助开发者跟踪功能的演进并确保兼容性. 每个 API 版本都有一个唯一的版本号 (例如, v1.0.1, v2.2.3) 来标识, 并代表一个重要的里程碑或发布版本. 版本管理让用户可以在准备好时选择更新, 从而以最小的干扰维持集成.

变更日志历史

变更日志历史记录详细展示了每个版本中引入的更新、缺陷修复、弃用与增强。它列出了对端点、参数、身份验证机制或响应格式所做的具体变更。本节让开发人员能完全透明地了解发生了哪些变化，并据此调整自己的实现。通过维护清晰而详尽的变更日志，我们希望为开发人员提供所需的工具和信息，帮助他们高效且自信地管理集成。

API 版本

我们的 API 目前版本为 v2.0.0

版本代码用于系统地识别和管理 API 更新. 它们遵循语义化版本 (SemVer) 格式:

<Major><Minor><Patch>

版本代码的每个组成部分都各司其职并帮助开发者有效传达变更的范围与类型.

主版本

定义: 指可能破坏向后兼容性的重大变更.

格式:

x.<Minor>.x
示例: v1.0.0 -> v2.0.0: 完整的 API 重构或不兼容的模式变更.

次版本

定义：表示向后兼容的功能新增。

格式:

x.<Minor>.x
示例: v1.0.0 -> v1.1.0: 在保持向后兼容的同时新增端点或方法.

补丁版本

定义：指向后兼容的缺陷修复或细微优化。

格式:

x.x.<Patch>
示例: v1.0.0 -> v1.1.0: 修复 API 端点中的一个小错误.

API 变更日志

变更日志是软件或 API 每个版本中变更、改进、错误修复和新功能的详细记录。它通过记录每次更新的影响，让用户和开发者对变化一目了然。

变更日志中的典型条目通常包含：

描述: 简要说明更改了什么.

受影响的组件：受此次变更影响的具体模块、端点或功能。

示例: 新增支持此新 API 命令 <域名注册>

变更日志历史

持续跟踪 Dynadot API 的每一次变更.

2025年10月9日
v2.0.0新功能与关键变更 沙盒环境现已上线 沙盒环境正式上线，可供安全测试与集成验证。 敏感操作强制校验 X-Signature 请求头 为提升安全性，所有敏感 API 命令现已强制要求提供 X-Signature 请求头。 (可选) 机器可读 API 文档 我们现在支持结构化、机器可读的 API 文档，让与自动化工具的集成更加轻松。 搜索访问受限 出于性能与数据管控考虑，某些搜索相关端点的访问已受限。 IP 白名单已优化 经销商账户使用 API 时，不再要求至少输入 1 个 IP（仅限 RESTful API） API 文档优化 更新文档首页的版本选择器，导航更便捷 统一参数命名的大小写规范 扩充了 bulk_search 接口的文档与使用指南 新增隐藏/显示侧边导航功能
引入强制分页参数，以提升响应效率与一致性。 page（整数，必填）——指定当前页面索引，从 1 开始。 page_size (整数, 必填) – 定义每页返回的条目数量。get_listings
津ICP备2023009172号-6