跳转到正文

netcup 技术文档

域名

旧版 API (Legacy API)

了解旧版 API (Legacy API) 的工作原理。

您可以在以下位置找到该 API 的技术文档： API 技术文档

客户控制面板 (CCP) 中的 API 允许您以编程方式执行各种操作。

当前可用的 API 服务

  • DNS API
    • 通过 DNS API，您可以修改使用我们 netcup 域名服务器的域名的 DNS 区域 (Zone)，并获取有关 DNS 区域和记录的信息。
  • 域名代理 API (Domain reselling API)
    • 仅在与我们签订域名代理合同后方可使用
    • 该 API 允许您注册和转移域名、创建联系人句柄、将句柄分配给域名等等。
  • netcup API
    • 借助全新的 netcup API，您现在可以通过 API 自动管理 CloudDNS 域名的 DNS 记录。请注意，新版 netcup API 目前仅支持域名管理；未来将陆续添加更多功能。

身份验证

申请旧版 API 密码

要使用旧版 API 功能，您需要一个旧版 API 密钥 (Legacy API Key) 和一个旧版 API 密码 (Legacy API Password)。

 

  1. 登录到 客户控制面板 (CCP).
  2. 前往 域名服务 （位于左侧菜单项）。
  3. 在 结果 (Results) 部分中，点击 放大镜图标 （位于相应域名旁边）。

如果域名使用的是传统 DNS，则需要旧版 API 密钥 ——您可以通过 DNS 选项卡。

您可以在客户控制面板 (CCP) 的 主数据 > API (Master Data > API).

创建旧版 API 密钥

要创建旧版 API 密钥，请点击 创建 API 密钥 (Creating an API Key) 按钮，该按钮位于右下角的 旧版 API 密钥 (Legacy API Keys) 部分中输入您的信息。

 

旧版 API 密钥同样由我们系统生成，且长度足以保证极高的安全性。

突出显示“旧版 API 密钥 (Legacy API Keys)”部分的 API 概览页面。
  1. 请阅读《API 使用条款》，并勾选复选框表示您同意这些条款。
  2. 然后，点击右下角的 确认 (Confirm) 按钮。
包含描述字段和使用条款的“创建新的旧版 API 密钥”弹窗。

您新创建的 API 密钥随后将显示在 旧版 API 密钥 (Legacy API Keys) 部分中，现在您可以在您的客户端中集成并使用它们了。

客户控制面板 (CCP) 中的 API 概览，突出显示了“旧版 API 密钥 (Legacy API Keys)”部分以及已创建的 API 密钥。
重新生成旧版 API 密码

在 旧版 API 密钥 (Legacy API Keys) 部分中，点击 重新生成 API 密码 (Regenerating API Password) 按钮（位于右下角）。此密码由系统自动生成——您无法自行设置密码。

突出显示“旧版 API 密钥 (Legacy API Keys)”部分的 API 概览页面。

一旦创建了新密码，您必须立即在客户端中更新它。API 密码仅会在确认消息中向您显示一次。如果您忘记了该密码，则需要重新生成一个新密码，因为每个客户账户只分配一个旧版 API 密码。因此，请务必将该密码妥善保存在安全的地方。

勾选复选框以表示您同意创建密码的相关条款和条件，然后点击 确认 (Confirm) 按钮。

包含如何重置密码说明的“重新生成旧版 API 密码”弹窗。

妥善保存好密码后，请点击 关闭 按钮。

包含如何安全保存密码的说明以及一次性旧版 API 密码的“新旧版 API 密码”弹窗。

删除 API 密钥

您可以创建多个 API 密钥并单独删除它们。

如果您删除了某个 API 密钥，您将无法再使用该密钥访问 API。

  1. 点击您想要连接到现有服务器的域名左侧的 垃圾桶图标 （位于您要删除的 API 密钥旁边）。
  2. 点击您想要连接到现有服务器的域名左侧的 确认 (Confirm) 按钮。
“删除 API 密钥”弹窗。

API 身份验证

要使用 API，您必须先进行身份验证。每项任务都需要使用会话 ID (Session ID) 形式的有效会话进行身份验证。

 

当使用 login 方法时，您需要向我们发送：

  • 您的客户编号 (Customer number)
  • 您的 API 密钥 (API key)
  • 您的 API 密码 (API password)

 

随后，您将收到由我们生成的会话 ID 作为返回值，您需要将该会话 ID 与 API 密钥配合使用才能调用其他方法。通过使用您的会话 ID，您即完成了对我们 API 的身份验证。

 

会话在闲置 15 分钟后会自动过期。或者，您也可以使用 logout 方法，使会话立即失效。

API 日志

在您的 客户控制面板 (CCP)中，您可以在 域名服务 区域下的 API 日志 (API Log)中查看最近执行的 API 操作。如果您不是域名代理商，该按钮会在您至少执行过一次 API 操作后显示。

在那里，您可以查看时间、操作名称、状态、简短反馈、操作涉及的句柄或域名、所使用的 API 密钥，以及消息（通过 ackpoll）被读取的时间。

API 日志

正如上方截图所示，在同一天且同一时、分、秒内执行的操作不一定按时间先后顺序排列。

 

点击操作左侧的放大镜图标，即可查看详细反馈、请求报文和响应报文。您还可以看到服务器请求 ID、客户端请求 ID、反馈代码以及所使用的报文格式。

 

反馈代码基于常见的 HTTP 状态码分组规则：

  • 2*** 成功消息
  • 4*** 通常为客户端侧的错误
  • 5*** 通常为服务器端侧的错误

 

以下操作会被记录到日志中：

  • cancelDomain
  • changeOwnerDomain
  • createDomain
  • createHandle
  • deleteHandle
  • getAuthcodeDomain
  • transferDomain
  • updateDnsRecords
  • updateDnsZone
  • updateDomain
  • updateHandle

技术信息

请注意，以下信息适用于旧版 API (Legacy API)。如果您使用的是配备 CloudDNS 的较新域名，可以在此处查看更多信息： CloudDNS 云解析

API 端点 (Endpoint)

API 端点位于以下 URI：

 

https://ccp.netcup.net/run/webservice/servers/endpoint.php

关于 API 请求的一般信息

  • 输入和输出均采用 UTF-8 编码。
  • 包含特殊字符（例如德语变音符号）的域名在传输前必须转换为 Punycode 编码。根据注册局的不同，某些特殊字符可能仍然不受支持，此时您将收到一条错误消息。
  • 如果来自注册局的反馈状态发生变化（例如： 在域名转移过程中从订单受理 “回执确认 (return receipt)” 到 “转移成功 (transfer successful)”），则在执行 poll时，系统会携带新的反馈重新发送该消息，即使该消息此前已通过 ackpoll.

验证 (Validation)

  • 可以使用 WSDL 中包含的 XSD 进行数据验证。

SOAP 请求的 URI

https://ccp.netcup.net/run/webservice/servers/endpoint.php?WSDL

关于 SOAP 请求的说明
  • 请按照函数文档或 WSDL 中的说明，在客户端的 SOAP 调用中指定参数。
  • 例如，使用由我们生成的 SOAP 客户端

 

https://ccp.netcup.net/run/webservice/servers/endpoint.php?PHPSOAPCLIENT

 

  • 我们不保证该客户端完全没有错误。市面上有许多免费解决方案可以根据 WSDL 生成您常用编程语言的代码。
关于 JSON 请求的说明

发送到服务器的消息负载 (Payload) 必须通过 POST 方式提交。登录请求示例如下：

{
  "action":"login",
  "param":{
     "apikey":"xxxxxxxxxxxx",
     "apipassword":"xxxx",
     "customernumber":"123456"
  }
}

JSON 请求 (REST) 的 URI

https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON

关于 JSON 请求的重要说明
  • 对于 REST 形式的请求，请使用 JSON URI。
  • 在 JSON 请求中，参数的顺序无关紧要，因为参数是通过键名 (Key) 定义的。

第三方技术客户端

请注意，我们对以下客户端的功能性、稳定性、可靠性等不承担任何责任。这些客户端并非由 netcup GmbH 开发或委托开发，也未经我们测试。我们无法为其提供技术支持。如有任何疑问，请联系相应客户端的开发者。

我们的一些用户开发了可配合我们 API 使用的客户端。我们非常感谢用户的热心贡献，并在此向您介绍这些项目。如果您也为我们的某个 API 开发了客户端，但尚未出现在下方列表中，欢迎随时发送电子邮件向我们简要介绍您的项目，我们将把您的客户端收录进来。

目录

  • 1 客户控制面板 (CCP) API 客户端列表
    • 1.1 DNS API
      • 1.1.1 DNS 管理
      • 1.1.2 动态 DNS (Dynamic DNS)
      • 1.1.3 Let’s Encrypt 客户端
      • 1.1.4 库 / 接口

客户控制面板 (CCP) API 客户端列表

DNS API

DNS 管理
  • ncdapi（非官方 netcup DNS API 客户端）
动态 DNS (DDNS)
Let's Encrypt 客户端
库 / 接口

DNS API

客户控制面板 (CCP) API 的 DNS 功能 (DNS API) 允许您修改使用我们 netcup 域名服务器的域名的 DNS 区域 (Zone)，以及获取有关 DNS 区域和记录的信息。 

 

其所提供的功能主要对应您在客户控制面板 (CCP) 的“DNS”区域中已有的操作选项。您可以在我们的帮助中心找到详尽的相关文档。

 

下面我们将介绍使用 DNS API 的基础知识。

前提条件

使用 DNS API 无需满足任何特殊要求。任何在我们这里拥有域名的客户都可以使用 DNS API。但前提是要编辑的域名必须使用 netcup 的域名服务器。如果您使用外部域名服务器，我们则无法为其提供 API。DNS API 面向在修改和创建 DNS 记录方面已有一定经验的客户。

 

请注意：无效或错误的 DNS 记录可能会影响您域名的正常解析和功能。

功能

通过 DNS API，您目前可以：

  • 登录或登出 API
    • 方法： login 或 logout
  • 获取域名的 DNS 区域 (Zone) 信息
    • 方法： infoDnsZone
  • 获取某个区域的所有 DNS 记录
    • 方法： infoDnsRecords
  • 修改域名的 DNS 区域配置
    • 方法： updateDnsZone
  • 修改某个区域的 DNS 记录
    • 方法： updateDnsRecords

您通过 API 所做的所有更改在客户控制面板 (CCP) 中同样可见，反之亦然。

域名代理 API (Domain Reselling API)

借助客户控制面板 (CCP) API 的域名代理功能（域名代理 API），您可以作为域名代理商对域名执行各种操作。该 API 允许您注册和转移域名、创建联系人句柄、为域名分配句柄等等。

 

其可用功能主要对应域名代理服务在客户控制面板 (CCP) 中已向您提供的各项功能。您可以参阅我们的相关文档了解详情。

 

下面我们将介绍使用域名代理 API 的基础知识。

前提条件

要使用域名代理 API，您需要满足以下特定要求：

  • 您必须是 netcup 的域名代理商才能使用域名代理 API：订购代理商级别 (Order Reseller Level)
  • 域名代理 API 面向在域名相关操作方面已具备丰富经验的客户。
  • 在使用需要指定域名服务器的 API 函数时，您必须自行运维至少两台自己的域名服务器。在这种情况下，您无法通过 API 直接指定使用我们提供的域名服务器。如果您想使用我们的域名服务器，请在完成注册或转移后通过您的客户控制面板 (CCP) 执行必要操作。
    • 例如，您可以在您的云服务器 (VPS) 上使用 netcup 预配置的 PowerDNS 镜像来自己搭建域名服务器。

功能

通过域名代理 API，您目前可以：

  • 登录或登出 API
    • 方法： login 或 logout
  • 创建、编辑和删除联系人句柄
    • 方法： createHandle、updateHandle 和 deleteHandle
  • 列出所有已创建的联系人句柄
    • 方法： listallHandle
  • 注册和转移域名
    • 方法： createDomain 和 transferDomain
  • 列出所有已创建的域名
    • 方法： listallDomains
  • 获取域名的授权码 (Auth-Code)
    • 方法： getAuthcodeDomain
  • 取消域名
    • 方法： cancelDomain
  • 执行域名所有者变更
    • 方法： changeOwnerDomain
  • 执行域名更新（更改句柄和域名服务器）
    • 方法： updateDomain
  • 获取有关域名或联系人句柄的信息
    • 方法： infoDomain 或 infoHandle
  • 获取特定顶级域名 (TLD) 的价格
    • 方法： priceTopleveldomain
  • 接收已执行域名订单的反馈并将其标记为已读
    • 方法： poll 和 ackpoll

您通过 API 所做的所有更改在客户控制面板 (CCP) 中同样可见，反之亦然。

限制条件

  • 通过 API 执行域名订单时（使用 createDomain / transferDomain 方法）：
    • 必须指定您自己创建的句柄。无法使用我们的标准句柄。
      • 如果域名设置的是我们的标准句柄，则只能通过客户控制面板 (CCP) 终止该域名或变更其所有权。
    • 通过 API 创建的域名始终作为付费附加域名处理。无法通过 API 注册包含域名（赠送域名）。
  • 如前文前提条件中所述，在使用需要域名服务器信息的 API 函数时，您需要指定并运维自己的域名服务器。您也可以在我们的云服务器 (VPS) 上使用我们的 PowerDNS 镜像。

 

如果您仍需使用上述受限功能，可以通过您的客户控制面板 (CCP) 执行所需的操作。

  • 日志中仅记录以下操作：cancelDomain、createDomain、changeOwnerDomain、createHandle、deleteHandle、getAuthcodeDomain、transferDomain、updateDnsRecords、updateDnsZone、updateDomain、updateHandle

您可能还对以下内容感兴趣：

最后更新：2026 年 9 月 30 日

api

这篇文章有帮助吗？