建立範本設定

建立新的範本設定，支援設定範本名稱、類型、內容、發送國家及簽名資訊。建立後範本狀態為「待審核」，需通過審核後方可使用。

呼叫位址

POST https://smsapi.engagelab.com/v1/template-configs

呼叫驗證

請參考呼叫驗證了解如何進行 API 鑑權。

請求範例

請求頭

POST /v1/template-configs HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

此代碼塊在浮窗中顯示

請求體

{ "template_name": "訂單通知範本", "template_type": "utility", "template_content": "您的訂單{order_no}已發貨，預計{delivery_time}送達", "country_codes": "CN,US", "add_signature": true, "sign_id": "987654321", "sign_position": 2 }

              
              {
  "template_name": "訂單通知範本",
  "template_type": "utility",
  "template_content": "您的訂單{order_no}已發貨，預計{delivery_time}送達",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	選項	說明
template_name	String	必填	範本名稱，最大 255 個字元
template_type	String	必填	範本類型：`authentication`（認證/驗證碼類）、`utility`（通知類）、`marketing`（行銷類）；歷史值 `otp` 會相容映射為 `authentication`
template_content	String	必填	範本內容，不能包含：`【`、`】`、`、`、`測試`、`test`、`[`、`]`
country_codes	String	必填	主要發送國家代碼，逗號分隔
add_signature	Boolean	可選	是否加入簽名，預設 false
sign_id	String	條件必填	當 add_signature 為 true 時必填，簽名 ID
sign_position	Integer	條件必填	當 add_signature 為 true 時必填，簽名位置：1-前綴，2-後綴

返回參數

成功返回

http 狀態碼為 200，響應體包含欄位如下：

欄位	類型	描述
template_id	String	建立的範本 ID

成功範例

{ "template_id": "123456789" }

              
              {
  "template_id": "123456789"
}

此代碼塊在浮窗中顯示

失敗返回

http 狀態碼為 4xx/5xx，響應體包含欄位如下：

欄位	類型	描述
code	Integer	錯誤碼
message	String	錯誤詳情

異常範例

{ "code": 400, "message": "sign status is not approved, can not use" }

              
              {
  "code": 400,
  "message": "sign status is not approved, can not use"
}

此代碼塊在浮窗中顯示

錯誤碼

錯誤碼	HTTP 狀態	可能涉及的錯誤
`1000`	`500`	服務內部異常；查詢範本清單/詳情失敗；建立、更新、刪除範本時資料庫操作失敗；查詢簽名資訊或待發送計畫失敗
`2001`	`401`	鑑權失敗；Authorization 缺失、格式錯誤、token 無效
`2002`	`401/403`	開發者 token 過期、被停用；業務已刪除
`2005`	`400`	IP 不在白名單：`ip forbidden`
`3001`	`400`	請求 JSON 格式錯誤：`not correct parameter format`
`3002`	`400`	`templateId` 格式錯誤；`template_name` 為空或超過 255 字元；`template_type` 非法；`template_content` 為空；`country_codes` 為空；`add_signature=true` 時缺少 `sign_id`；`sign_position` 非法；範本內容包含禁用字元
`3002`	`400`	認證類範本校驗失敗：必須包含 `{{code}}`；且只支援 `{{code}}`、`{{ttl}}` 兩個變數
`3003`	`400`	加入簽名時簽名未審核通過；範本不屬於目前業務；待審核範本不能更新；有待發送或執行中的計畫使用該範本，不能更新/刪除
`4001`	`400`	範本不存在：`template config not exist`；建立/更新範本時引用的簽名不存在：`sign config not exist`

常見錯誤資訊：

sign config not exist：簽名設定不存在
sign status is not approved, can not use：簽名狀態未審核通過，不能使用
template config not exist：範本設定不存在
ip forbidden：IP 不在白名單
not correct parameter format：請求 JSON 格式錯誤

注意事項

範本建立後狀態為「待審核」（status=1），需通過審核後方可用於發送簡訊
如果加入簽名，簽名必須是已審核通過狀態
範本內容不能包含禁用字元：【、】、、、測試、test、[、]
範本和簽名的 ID 都是字串類型的數字

附錄

範本設定狀態 (status)

值	說明
1	待審核
2	審核通過
3	審核拒絕

範本類型 (template_type)

值	說明
authentication	認證/驗證碼類
utility	通知類
marketing	行銷類

歷史值 otp 會相容映射為 authentication。認證類範本內容必須包含 {{code}}，且只支援 {{code}}、{{ttl}} 兩個變數。

簽名位置 (sign_position)

值	說明
0	無簽名
1	前綴
2	後綴