添加网站域名 API

为 VIP WebPush 应用单次添加一个网站域名。SDK、Service Worker 部署及用户授权仍由客户完成。

使用应用所在数据中心的 AppKey 和 MasterSecret 进行 Basic 鉴权。domain 必填，以 portalweb 保存域名校验为基础，必须显式使用小写 https://，且只接受小写输入。支持域名、IPv4 及域名/IP 加数字端口；IPv6 拒绝。按最新验收规则接受端口 65536，不设 65535 准入上限；0 和前导零仍拒绝。允许末尾单独的根斜杠 /，查重时与无斜杠形式等价；拒绝 /page 等路径段、查询、片段、空白、localhost（含子域名和尾点形式）、HTTP 和通配符。IPv4 仅查格式，不限制用途；不检查 DNS、可达性或证书。合法输入原样保存。request_id 可选，最多 128 字节，回显边界见下文。

Basic Auth

POST /v4/web/domains

              
              curl -X POST https://webpushapi-sgp.engagelab.com/v4/web/domains \
  -u APP_KEY:MASTER_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "https://shop-001.example.com",
    "request_id": "req-001"
  }'

            

HTTP 200:

              
              {
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

integration_status: pending / integrated. config_status: ready (pending: reserved).

              
              {
  "error": {
    "code": 27601,
    "message": "DOMAIN_ALREADY_EXISTS"
  },
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

顺序重复添加不重复占用额度，查重忽略大小写、末尾斜杠和默认 443 端口。新域名保留校验通过的小写主机名及提交的端口；已有域名保留原存储形式及接入状态。重复请求返回 HTTP 400 和已有域名信息。API 与控制台共享额度。请串行添加，并避免与控制台同时修改；并发写入可能相互覆盖。配置沿用控制台现有生效流程，可能存在延迟。API 操作记录在服务日志中，不展示在控制台操作日志中。超时或 5xx 后使用相同域名重试。不提供删除、修改、批量添加和购买额度能力。

本接口复用 deviceapi 现有的应用 QPS 配额；未配置时沿用系统默认值。按 AppKey 和接口独立计数，重复调用也消耗 QPS。超限返回 HTTP 400、错误码 23010（Rate limit exceeded for the API），请退避后重试。

请求校验、错误码与 request_id 回显

请求体上限为 4 KiB。domain 必须是非空字符串：缺失、null、空字符串、数字、布尔值、数组或对象，或 JSON 格式错误、包含多份 JSON、请求体超限、request_id 超过 128 字节时，返回 HTTP 400 / 21003 Invalid request。此阶段不回显 request_id。有效非空字符串进入域名格式校验后，不符合格式才返回 HTTP 400 / 27600 INVALID_DOMAIN。

只有请求结构校验通过后，合法非空 request_id 才会在后续业务响应中原样回显，包括 27600、27601 和限流 23010。未提供或为空时省略该字段；请求解析前因 Basic 鉴权头格式无效而提前拒绝时也不回显。

限流优先使用应用 app_qps；未配置或为 0 时回退业务默认值，不能将某次 QA 的默认值当成所有应用的固定阈值。按 AppKey + /v4/web/domains 独立计数，重复请求同样消耗 QPS，且限流在域名查重之前执行。超限返回 HTTP 400 / 23010 Rate limit exceeded for the API，不返回 HTTP 429；请退避后重试。

              
              {"error":{"code":21003,"message":"Invalid request"}}

            

              
              {"request_id":"invalid-domain","error":{"code":27600,"message":"INVALID_DOMAIN"}}

            

              
              {"request_id":"qps-example","error":{"code":23010,"message":"Rate limit exceeded for the API"}}