推送計劃API

此模塊API主要針對的是推送計劃ID本身的創建、修改和查詢操作。

調用驗證

詳情參見 REST API 概述的鑒權方式說明。

創建與更新推送計劃

本接口用於 創建或更新推送計劃。通過傳入 plan_id 和 plan_description，系統將根據 plan_id 是否存在進行創建或更新操作。

調用地址

POST v4//v4/push_plan

          POST v4//v4/push_plan

此代碼塊在浮窗中顯示

请求参数

參數名稱	類型	是否必填	說明
plan_id	string	是	推送計劃唯一識別符格式規則：字母（區分大小寫）、數字、下劃線組合，禁止以下劃線開頭長度限制：最大 50 字符唯一性約束：設置後不可修改更新策略：當 plan_id 已存在時更新 plan_description，不存在時創建新計劃
plan_description	string	是	推送計劃描述信息內容要求：需包含推送場景、目標用戶、推送內容等業務關鍵信息格式規範：支持中英文、數字及常用標點符號長度建議：不超過 200 字符（系統不做強制限制）

请求示例

{ "plan_id": "push_20231001_001", "plan_description": "雙十一大促活動推送計劃，覆蓋全量用戶" }

          {
  "plan_id": "push_20231001_001",
  "plan_description": "雙十一大促活動推送計劃，覆蓋全量用戶"
}

此代碼塊在浮窗中顯示

返回參數說明

成功響應

{ "plan_id": "push_20231001_001" }

          {
  "plan_id": "push_20231001_001"
}

此代碼塊在浮窗中顯示

失敗響應

{ "error": { "code": 27303, "message": "Empty plan id" } }

          {
  "error": {
    "code": 27303,
    "message": "Empty plan id"
  }
}

此代碼塊在浮窗中顯示

查詢推送計劃

本接口用於 分頁查詢推送計劃列表，支持按發送來源過濾和模糊搜索計劃描述/計劃ID。

調用地址

GET v4/push_plan/list?page_index=x&page_size=xx&send_source=x&search_description=xxx

          GET v4/push_plan/list?page_index=x&page_size=xx&send_source=x&search_description=xxx

此代碼塊在浮窗中顯示

请求参数

參數名稱	類型	是否必填	說明
page_index	int	是	分頁頁碼（從 `1` 開始計數）
page_size	int	是	每頁數據條數，最大支持 `100` 條
send_source	int	否	發送來源標識：`0`-API，`1`-Web控制台
search_description	string	否	模糊匹配計劃描述或計劃ID（支持中英文、數字、下劃線）

请求示例

GET /v4/push_plan/list?page_index=1&page_size=20&send_source=1&search_description=雙十一

          GET /v4/push_plan/list?page_index=1&page_size=20&send_source=1&search_description=雙十一

此代碼塊在浮窗中顯示

返回參數說明

成功響應

{ "push_plan_info": [ { "push_id": "push_20231111", "plan_description": "雙十一全站推送計劃", "count": 15, "create_time": "2023-11-01T10:00:00Z", "last_used_time": "2023-11-11T20:30:00Z" } ], "total": 1 }

          {
  "push_plan_info": [
    {
      "push_id": "push_20231111",
      "plan_description": "雙十一全站推送計劃",
      "count": 15,
      "create_time": "2023-11-01T10:00:00Z",
      "last_used_time": "2023-11-11T20:30:00Z"
    }
  ],
  "total": 1
}

此代碼塊在浮窗中顯示

失敗響應

{ "error": { "code": 1003, "message": "Parameter value is invalid" } }

          {
    "error": {
        "code": 1003,
        "message": "Parameter value is invalid"
    }
}

此代碼塊在浮窗中顯示

根據推送計劃查詢Msgid

本接口用於 獲取指定推送計劃在最近一個月內的關聯消息ID，支持批量查詢多個計劃的關聯消息數據。

調用地址

GET /v4/status/plan/msg/?plan_ids=xxxxxx,xxxxxx&start_date=yyyy-MM-dd&end_date=yyyy-MM-dd

          GET /v4/status/plan/msg/?plan_ids=xxxxxx,xxxxxx&start_date=yyyy-MM-dd&end_date=yyyy-MM-dd

此代碼塊在浮窗中顯示

请求参数

參數名稱	類型	是否必填	說明
plan_ids	string	是	推送計劃ID列表，多個ID用英文逗號分隔，最多支持100個
start_date	string	是	開始日期（格式：`yyyy-MM-dd`），必須滿足： 1. 當前日期前推30天內 2. 結束日期>=開始日期
end_date	string	是	結束日期（格式：`yyyy-MM-dd`），必須滿足： 1. 與開始日期間隔≤31天 2. 不早於開始日期

请求示例

GET /v4/status/plan/msg/?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-15

          GET /v4/status/plan/msg/?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-15

此代碼塊在浮窗中顯示

返回參數說明

成功響應

{ "push_20231101": { "msg_ids": ["msg_001", "msg_002"] }, "push_20231102": { "msg_ids": ["msg_003"] } }

          {
  "push_20231101": {
    "msg_ids": ["msg_001", "msg_002"]
  },
  "push_20231102": {
    "msg_ids": ["msg_003"]
  }
}

此代碼塊在浮窗中顯示

失敗響應

{ "error": { "code": 21044, "message": "The time interval exceeds one month." } }

          {
    "error": {
        "code": 21044,
        "message": "The time interval exceeds one month."
    }
}

此代碼塊在浮窗中顯示

錯誤碼說明

錯誤碼	說明	建議處理方式
21015	創建推送計劃請求參數錯誤	檢查 `plan_id` 或 `plan_description` 類型是否正確
27300	推送計劃標識不合法	檢查 `plan_id` 使其符合命名規則
27301	推送計劃描述不合法	檢查 `plan_description` 使其符合規則
27303	推送計劃標識為空	創建推送計劃時給一個有效的推送計劃標識
27304	推送計劃標識長度超過限制	使推送計劃標識長度小於50
21004	創建推送計劃權限校驗失敗	確認調用方是否有接口訪問權限
27000	服務端內部錯誤	聯繫技術支持或重試
1003	查詢推送計劃的參數非法	檢查 `page_index/page_size` 是否大於0
21004	查詢推送計劃權限校驗失敗	確認調用方是否有接口訪問權限
27302	超過推送計劃使用上限	聯繫技術支持提高上限
21009	系統內部錯誤,不可重試	聯繫技術支持
23001	根據推送計劃查詢Msgid權限校驗失敗	確認調用方是否有接口訪問權限
3010	查詢接口api調用量超出限制	聯繫技術支持
23002	根據推送計劃查詢Msgid傳入有效pl參數錯誤	檢查 plan_ids 的有效性或日期參數是否傳遞
21003	傳入日期非法	檢查日期有效性
21044	開始與結束日期間隔超過一個月	使開始與結束日期間隔小於一個月