模板管理&签名管理

本文档描述了模板配置和签名配置相关的 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都是字符串类型的数字