新增網站網域 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 時回退業務預設值，並非所有應用程式都有相同固定門檻。依 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"}}