模板管理&簽名管理

本文檔描述了模板配置和簽名配置相關的 RESTful API 介面。

基礎信息

• 域名: https://smsapi.engagelab.com
• 認證方式: Basic Authentication (Base64編碼)
  • 格式：Authorization: Basic base64(apikey:apisecret)
  • 示例：將 apikey:apisecret 進行 Base64 編碼後，在請求頭中添加 Authorization: Basic <編碼後的字符串>
• Content-Type: application/json

響應格式

成功響應

成功響應直接返回數據對象或數組：

              
              {
  "template_id": "123456789",
  "template_name": "示例模板",
  ...
}

            

或列表響應：

              
              [
  {
    "template_id": "123456789",
    "template_name": "示例模板",
    ...
  }
]

            

錯誤響應

錯誤響應格式：

              
              {
  "code": 400,
  "message": "錯誤信息描述"
}

            

模板配置介面

1. 獲取模板配置列表

介面描述: 獲取當前業務下的所有模板配置列表

請求信息:

• 方法: GET
• 路徑: /v1/template-configs
• 認證: 需要

請求參數: 無

響應示例:

              
              [
  {
    "template_id": "123456789",
    "template_name": "訂單通知模板",
    "template_type": "utility",
    "template_content": "您的訂單{order_no}已發貨，預計{delivery_time}送達",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "公司名稱",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

響應字段說明:

2. 獲取模板配置詳情

介面描述: 根據模板ID獲取模板配置的詳細信息

請求信息:

• 方法: GET
• 路徑: /v1/template-configs/:templateId
• 認證: 需要

路徑參數:

響應示例:

              
              {
  "template_id": "123456789",
  "template_name": "訂單通知模板",
  "template_type": "utility",
  "template_content": "您的訂單{order_no}已發貨，預計{delivery_time}送達",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "公司名稱",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

錯誤響應:

• 400: 模板ID格式錯誤或模板不存在
• 500: 服務器內部錯誤

3. 創建模板配置

介面描述: 創建新的模板配置

請求信息:

• 方法: POST
• 路徑: /v1/template-configs
• 認證: 需要

請求體:

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

            

請求字段說明:

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 參數格式錯誤、參數驗證失敗、簽名配置不存在、簽名狀態未審核通過
• 500: 服務器內部錯誤

業務規則:

• 模板創建後狀態為"待審核"（status=1）
• 如果添加簽名，簽名必須是已審核通過狀態

4. 更新模板配置

介面描述: 更新已存在的模板配置

請求信息:

• 方法: PUT
• 路徑: /v1/template-configs/:templateId
• 認證: 需要

路徑參數:

請求體: 同創建介面，所有字段必填

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 參數格式錯誤、模板不存在、模板狀態為待審核不能更新、存在待發送或運行中的計劃不能更新、簽名配置不存在、簽名狀態未審核通過
• 500: 服務器內部錯誤

業務規則:

• 待審核狀態的模板不能更新
• 如果存在待發送或運行中的消息計劃使用該模板，則不能更新
• 更新後模板狀態會變回"待審核"（status=1）

5. 刪除模板配置

介面描述: 刪除指定的模板配置

請求信息:

• 方法: DELETE
• 路徑: /v1/template-configs/:templateId
• 認證: 需要

路徑參數:

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 模板ID格式錯誤、模板不存在、存在待發送或運行中的計劃不能刪除
• 500: 服務器內部錯誤

業務規則:

• 如果存在待發送或運行中的消息計劃使用該模板，則不能刪除

簽名配置接口

1. 獲取簽名配置列表

接口描述: 獲取當前業務下的所有簽名配置列表

請求信息:

• 方法: GET
• 路徑: /v1/sign-configs
• 認證: 需要

請求參數: 無

響應示例:

              
              [
  {
    "sign_id": "987654321",
    "sign_name": "公司名稱",
    "status": 2,
    "related_template_count": 5,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

響應字段說明:

2. 獲取簽名配置詳情

接口描述: 根據簽名ID獲取簽名配置的詳細信息

請求信息:

• 方法: GET
• 路徑: /v1/sign-configs/:signId
• 認證: 需要

路徑參數:

響應示例:

              
              {
  "sign_id": "987654321",
  "sign_name": "公司名稱",
  "status": 2,
  "related_template_count": 5,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

錯誤響應:

• 400: 簽名ID格式錯誤、簽名不存在、簽名不屬於當前業務
• 500: 服務器內部錯誤

3. 創建簽名配置

接口描述: 創建新的簽名配置

請求信息:

• 方法: POST
• 路徑: /v1/sign-configs
• 認證: 需要

請求體:

              
              {
  "sign_name": "公司名稱"
}

            

請求字段說明:

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 參數格式錯誤、參數驗證失敗、簽名名稱已存在
• 500: 服務器內部錯誤

業務規則:

• 簽名創建後狀態為"待審核"（status=1）
• 同一業務下簽名名稱不能重複

4. 更新簽名配置

接口描述: 更新已存在的簽名配置

請求信息:

• 方法: PUT
• 路徑: /v1/sign-configs/:signId
• 認證: 需要

路徑參數:

請求體: 同創建接口

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 參數格式錯誤、簽名不存在、簽名不屬於當前業務、簽名狀態為待審核不能更新、簽名名稱已存在、存在待發送或運行中的計劃不能更新
• 500: 服務器內部錯誤

業務規則:

• 待審核狀態的簽名不能更新
• 如果存在待發送或運行中的消息計劃使用該簽名，則不能更新
• 更新後簽名狀態會變回"待審核"（status=1）

5. 刪除簽名配置

接口描述: 刪除指定的簽名配置

請求信息:

• 方法: DELETE
• 路徑: /v1/sign-configs/:signId
• 認證: 需要

路徑參數:

響應示例:

              
              {
  "code": 0,
  "message": "success"
}

            

錯誤響應:

• 400: 簽名ID格式錯誤、簽名不存在、簽名不屬於當前業務、存在待發送或運行中的計劃不能刪除
• 500: 服務器內部錯誤

業務規則:

• 如果存在待發送或運行中的消息計劃使用該簽名，則不能刪除

狀態碼說明

模板配置狀態 (status)

簽名配置狀態 (status)

簽名位置 (sign_position)

模板類型 (template_type)

錯誤碼說明

常見錯誤信息：

• invalid templateId: 模板ID格式錯誤
• template config not exist: 模板配置不存在
• invalid signId: 簽名ID格式錯誤
• sign config not exist: 簽名配置不存在
• sign_name already exist: 簽名名稱已存在
• can not update pending status template: 待審核狀態的模板不能更新
• can not update pending status sign: 待審核狀態的簽名不能更新
• there are pending or running plans using current template, can not update: 存在使用該模板的待發送或運行中的計劃，不能更新
• there are pending or running plans using current sign, can not update: 存在使用該簽名的待發送或運行中的計劃，不能更新
• sign status is not approved, can not use: 簽名狀態未審核通過，不能使用

注意事項

1. 所有接口都需要通過認證中間件驗證
2. 所有接口都會自動關聯當前認證用戶的業務ID（businessId）
3. 模板和簽名的創建、更新操作都會觸發審核流程
4. 如果模板或簽名被消息計劃使用，在計劃處於待發送或運行中狀態時，不能更新或刪除
5. 模板內容不能包含禁用字符：【、】、、、測試、test、[、]
6. 簽名名稱不能包含禁用字符：【、】、[、]
7. 模板和簽名的ID都是字符串類型的數字