用户 API 文档

连接 AI 工具或脚本，查询你的站点、订单与域名，并执行站点备份、DNS 修改和续费下单等操作。

连接 MCP 管理用户 API Token OpenAPI JSON AI 接入指南

快速开始

登录用户控制台，在「个人资料 → 用户 API Token」创建令牌。
在支持 OpenAPI 的 AI 工具中导入 JSON 地址，将认证类型设为 Bearer，并在密钥设置中保存令牌。
先调用 GET /me 核对身份。个人令牌继承账号的用户 API 权限，可在控制台撤销。

查询当前用户

curl -fsS 'https://www.shopagg.com/api/v1/me' \
      -H "Authorization: Bearer ${SHOPAGG_API_TOKEN}" \
      -H 'Accept: application/json'

可以先让 AI「查看我的待支付订单和未来 30 天到期的资源」。下单前核对费用，变更 DNS 或站点运行状态前核对目标和影响。用户在浏览器完成支付。

连接用户 MCP

在控制台创建用户 API Token。客户端使用 Streamable HTTP，并在每个请求中发送 Authorization: Bearer <token>。账号需要处于正常状态并已绑定邮箱。

https://www.shopagg.com/mcp/user

Codex

在运行 Codex 的环境中设置 SHOPAGG_API_TOKEN，再注册服务。

codex mcp add shopagg --url 'https://www.shopagg.com/mcp/user' \
  --bearer-token-env-var SHOPAGG_API_TOKEN
codex mcp list

Codex MCP 配置说明

Claude Code

从设置了 SHOPAGG_API_TOKEN 的终端运行。命令将环境变量引用保存到个人配置，使用 /mcp 检查连接。

claude mcp add-json --scope user shopagg \
  '{"type":"http","url":"https://www.shopagg.com/mcp/user","headers":{"Authorization":"Bearer ${SHOPAGG_API_TOKEN}"}}'

Claude Code MCP 配置说明

连接后可问「列出我名下的站点、域名和待支付订单」。先查询资源 ID，核对停站、DNS 变更的影响和续费金额后再操作。续费创建待支付订单，付款在控制台完成。

写入须提供 UUID request_key。重试同一操作时复用该值和原参数，已记录结果可在 24 小时内重放。工具结果中的 status: 202 表示任务已受理，可用 list_website_operations 查询进度。撤销令牌后连接会失效。

查看 MCP 工具

站点

list_websites
get_website
get_website_status
list_website_operations
get_website_billing_options
start_website
stop_website
restart_website
suspend_website
resume_website
create_website_backup

订单

create_website_renewal_order
create_website_upgrade_order
list_orders
get_order
get_order_payment_status
create_domain_renewal_order

域名与 DNS

list_domains
get_domain
get_domain_renewal_options
list_dns_records
create_dns_record
update_dns_record
delete_dns_record

错误与重试

带 JSON 请求体时发送 Content-Type: application/json。对标有幂等键的操作，可为每次操作提供一个 UUID，重复提交同一请求时复用该值。状态为 202 时继续查询业务结果。

400: 当前请求无法执行。
401: 令牌缺失、无效、过期或已撤销。
403: 资源归属、账号状态或邮箱要求未通过。
404: 资源不存在。
409: 业务冲突或相同幂等请求仍在处理中。
422: 字段无效、业务状态不允许操作，或幂等键已用于其他请求。
429: 请求过于频繁，按 Retry-After 等待。

列表使用 data 返回结果。分页列表另外返回 links 和 meta。未声明幂等的写入出现超时时，先查询结果再决定是否重试。

账号

GET /me 查询当前账号

连接后先核对当前账号身份。

需要 Bearer Token

响应状态 200 / 401 / 403

GET /overview 查询账号总览

临期统计覆盖未来 30 天，近期和临期列表各自最多返回 5 条。

需要 Bearer Token

响应状态 200 / 401 / 403

PUT /account/profile 修改显示名称

修改当前账号的 name。

需要 Bearer Token

JSON 请求字段

name（string，必填）

响应状态 200 / 401 / 403 / 422

站点

GET /websites 列出我的站点

列出我的站点。

需要 Bearer Token

q: （query）搜索关键词。
page: （query）页码，从 1 开始。
per_page: （query）每页条数。
site_type: （query）站点产品类型。 b2b_hosted / b2c_wordpress
status: （query）当前站点状态。

响应状态 200 / 401 / 403 / 422

GET /websites/{website} 查询站点详情

从列表取得站点 ID。运行操作前读取 available_actions。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

GET /websites/{website}/status 查询站点状态

查询站点状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

GET /websites/{website}/stats 查询站点运行信息

运行数据取决于站点架构。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

GET /websites/{website}/operations 查询站点操作进度

根据 recommended_interval_ms 查询，使用操作 ID 查找 operations 元素并检查 status、is_terminal 和 error。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /websites/{website}/start 启动 B2C 站点

核对站点和对访问的影响、检查 available_actions 是否包含 start，并在提交后检查状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 200 / 202 / 400 / 401 / 403 / 404 / 409 / 422

POST /websites/{website}/stop 停止 B2C 站点

核对站点和对访问的影响、检查 available_actions 是否包含 stop，并在提交后检查状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 200 / 202 / 400 / 401 / 403 / 404 / 409 / 422

POST /websites/{website}/restart 重启 B2C 站点

核对站点和对访问的影响、检查 available_actions 是否包含 restart，并在提交后检查状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 200 / 202 / 400 / 401 / 403 / 404 / 409 / 422

POST /websites/{website}/suspend 暂停 B2B 站点

核对站点和对访问的影响、检查 available_actions 是否包含 suspend，并在提交后检查状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 200 / 401 / 403 / 404 / 409 / 422

POST /websites/{website}/unsuspend 恢复 B2B 站点运行

核对站点和对访问的影响、检查 available_actions 是否包含 unsuspend，并在提交后检查状态。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 200 / 401 / 403 / 404 / 409 / 422

GET /websites/{website}/backups 查询站点备份

字段随托管架构变化。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /websites/{website}/backups 创建手动备份

操作 ID 位于顶层或 data 内。提交后到站点操作查看进度。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

响应状态 202 / 401 / 403 / 404 / 409 / 422

GET /websites/{website}/billing-options 查询站点续费与升级报价

查询站点续费与升级报价。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /websites/{website}/renew-order 创建站点续费订单

先查询账单选项，核对可用期限及报价。用户确认后下单。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

duration_months（integer，必填） 1 / 3 / 6 / 12 / 24 / 36

响应状态 201 / 401 / 403 / 404 / 409 / 422

POST /websites/{website}/upgrade-order 创建站点升级订单

先查询账单选项，核对目标套餐及报价。用户确认后下单。

需要 Bearer Token

website: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

plan_id（string，必填）

响应状态 201 / 401 / 403 / 404 / 409 / 422

订单

GET /orders 列出我的订单

同时查看 pay_status（支付）和 order_status（履约）。

需要 Bearer Token

q: （query）搜索关键词。
page: （query）页码，从 1 开始。
per_page: （query）每页条数。
order_type: （query）订单类型。 site / b2b_site / domain / course / app_store / qa_bounty / enterprise_mail
pay_status: （query）支付状态。 unpaid / paid / refunded
awaiting_payment: （query）传 1 只查看待付款且可支付订单。 0 / 1

响应状态 200 / 401 / 403 / 422

GET /orders/{order} 查询订单详情

查询订单详情。

需要 Bearer Token

order: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /orders/site 创建 B2C 建站订单

查询套餐和可用区域，请用户确认区域、套餐、期限及费用。

需要 Bearer Token

Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

plan_id（string，必填）
region_id（string，必填）
duration_months（integer，必填） 1 / 3 / 6 / 12 / 24 / 36

响应状态 201 / 401 / 403 / 409 / 422

POST /orders/b2b-site 创建 B2B 建站订单

查询套餐和可用区域，请用户确认区域、套餐、期限及费用。

需要 Bearer Token

Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

plan_id（string，必填）
region_id（string，必填）
duration_months（integer，必填） 1 / 3 / 6 / 12 / 24 / 36

响应状态 201 / 401 / 403 / 409 / 422

POST /orders/{order}/pay-url 获取网页收银台链接

仅向订单本人提供短期的 data.url，由用户在浏览器支付，再查询支付状态。

需要 Bearer Token

order: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404 / 422

GET /orders/{order}/payment-status 查询订单支付与履约状态

查询订单支付与履约状态。

需要 Bearer Token

order: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

域名与 DNS

GET /domains 列出我的域名

列出我的域名。

需要 Bearer Token

q: （query）搜索关键词。
page: （query）页码，从 1 开始。
per_page: （query）每页条数。
status: （query）域名状态。 pending / active / expired / transferring / suspended / failed
dns_ready: （query）传 1 筛选已开通 DNS 管理的域名。 0 / 1

响应状态 200 / 401 / 403 / 422

GET /domains/{domain} 查询域名详情

路径中使用域名资源 ID。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

GET /domains/search 搜索可注册域名

搜索可注册域名。

公开接口

q: （query，必填）域名或搜索关键词。

响应状态 200 / 422

GET /domain-contacts 列出我的域名联系人

创建域名注册订单时复用本账号联系人的 ID。

需要 Bearer Token

响应状态 200 / 401 / 403

POST /orders/domain-register 创建域名注册订单

先搜索可注册域名，查询本人联系人，确认费用和年限后下单。

需要 Bearer Token

Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

domain（string，必填）
years（integer，必填）
contact_id（string，必填）

响应状态 201 / 401 / 403 / 409 / 422

GET /domains/{domain}/renewal-options 查询域名续费或赎回报价

查询域名续费或赎回报价。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /domains/{domain}/renew-order 创建域名续费订单

先核对报价是续费还是赎回、金额、期限和有效期，用户确认后下单。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

years（integer，必填）

响应状态 201 / 401 / 403 / 404 / 409 / 422

GET /domains/{domain}/dns-records 查询域名 DNS 记录

域名必须符合管理条件并开通 DNS 管理。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404 / 422

POST /domains/{domain}/dns-records 新增 DNS 记录

先读现有配置，确认类型、名称、记录值及影响。相同记录可直接复用并返回 200。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

type（string，必填） A / AAAA / CNAME / MX / TXT / NS / SRV / CAA
name（string，必填）
content（string，必填）
ttl（integer）
proxied（boolean）
priority（integer）

响应状态 200 / 201 / 401 / 403 / 404 / 409 / 422

PUT /domains/{domain}/dns-records/{recordId} 修改 DNS 记录

读取现有记录及记录 ID。确认变更，提交必填字段和需保留的可选属性，并重新读取核对。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。
recordId: （path，必填）从相应列表或详情取得的资源 ID。

JSON 请求字段

type（string，必填） A / AAAA / CNAME / MX / TXT / NS / SRV / CAA
name（string，必填）
content（string，必填）
ttl（integer）
proxied（boolean）
priority（integer）

响应状态 200 / 401 / 403 / 404 / 422

DELETE /domains/{domain}/dns-records/{recordId} 删除 DNS 记录

先向用户说明要删除的具体记录和影响，确认后执行。若超时则先列表查询。

需要 Bearer Token

domain: （path，必填）从相应列表或详情取得的资源 ID。
recordId: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404 / 422

企业邮箱

GET /enterprise-mail/plans 查询企业邮箱套餐

查询企业邮箱套餐。

公开接口

响应状态 200

GET /enterprise-mail 列出我的企业邮箱订阅

列出我的企业邮箱订阅。

需要 Bearer Token

响应状态 200 / 401 / 403

GET /enterprise-mail/{mailSubscription} 查询企业邮箱订阅详情

查询企业邮箱订阅详情。

需要 Bearer Token

mailSubscription: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404

POST /enterprise-mail/orders 创建企业邮箱订单

请用户确认套餐、费用及期限。

需要 Bearer Token

Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

mail_plan_id（string，必填）
duration_months（integer，必填） 12 / 24 / 36

响应状态 201 / 401 / 403 / 409 / 422

POST /enterprise-mail/{mailSubscription}/domain 绑定企业邮箱域名

先确认订阅与完整域名，绑定后核对返回的 DNS 配置。

需要 Bearer Token

mailSubscription: （path，必填）从相应列表或详情取得的资源 ID。
Idempotency-Key: （header）建议使用 UUID。重试同一操作时复用相同键、方法、路径和参数，服务端可在 24 小时内重放已记录响应。

JSON 请求字段

domain_name（string，必填）

响应状态 200 / 401 / 403 / 404 / 409 / 422

POST /enterprise-mail/{mailSubscription}/verify-dns 验证邮箱 DNS

适用于已绑定域名、待验证或已运行的订阅。

需要 Bearer Token

mailSubscription: （path，必填）从相应列表或详情取得的资源 ID。

响应状态 200 / 401 / 403 / 404 / 422 / 429

课程与社区

GET /courses 查询课程列表

查询课程列表。

需要 Bearer Token

q: （query）搜索关键词。
page: （query）页码，从 1 开始。
per_page: （query）每页条数。
category: （query）分类 slug。

响应状态 200 / 401 / 403 / 422

GET /courses/my 列出我的课程

列出我的课程。

需要 Bearer Token

响应状态 200 / 401 / 403

GET /qa/questions 查询公开问答

查询公开问答。

公开接口

q: （query）搜索关键词。
page: （query）页码，从 1 开始。
per_page: （query）每页条数。
category: （query）分类 slug。
sort: （query）排序。 latest / hot / bounty / solved / unanswered

响应状态 200 / 422

公开目录

GET /plans 查询在售站点套餐

查询在售站点套餐。

公开接口

响应状态 200

GET /regions 查询可用区域

site_type 和 plan_id 必须一起传，用于匹配套餐和托管资源。

公开接口

site_type: （query）站点产品类型。 b2b_hosted / b2c_wordpress
plan_id: （query）套餐 ID。

响应状态 200 / 404 / 422

GET /b2b/durations 查询 B2B 可购买期限

报价基于默认套餐。指定套餐的价格以套餐详情及下单结果为准。

公开接口

响应状态 200