Template&Sender ID

Información básica

• Dominio: https://smsapi.engagelab.com
• Método de autenticación: Autenticación básica (codificación Base64)
  • Formato: Authorization: Basic base64(apikey:apisecret)
  • Ejemplo: codificar apikey:apisecret en Base64 y, a continuación, añadir Authorization: Basic <cadena codificada> al encabezado de la solicitud.
• Content-Type: application/json

Formato de respuesta

Respuesta correcta

Las respuestas correctas devuelven directamente un objeto de datos o un array:

              
              {
  "template_id": "123456789",
  "template_name": "Example Template",
  ...
}

            

O una respuesta de lista:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Example Template",
    ...
  }
]

            

Respuesta de error

Formato de respuesta de error:

              
              {
  "code": 400,
  "message": "Error description"
}

            

Interfaces de configuración de plantillas

1. Obtener lista de configuraciones de plantilla

Descripción de la interfaz: Obtener la lista de todas las configuraciones de plantilla del negocio actual.

Información de la solicitud:

• Método: GET
• Ruta: /v1/template-configs
• Autenticación: Obligatoria

Parámetros de solicitud: Ninguno

Ejemplo de respuesta:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Order Notification Template",
    "template_type": "utility",
    "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "Company Name",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Descripción de campos de respuesta:

2. Obtener detalles de configuración de plantilla

Descripción de la interfaz: Obtener información detallada de una configuración de plantilla por ID de plantilla.

Información de la solicitud:

• Método: GET
• Ruta: /v1/template-configs/:templateId
• Autenticación: Obligatoria

Parámetros de ruta:

Ejemplo de respuesta:

              
              {
  "template_id": "123456789",
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "Company Name",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Respuestas de error:

• 400: error de formato del ID de plantilla o la plantilla no existe
• 500: error interno del servidor

3. Crear configuración de plantilla

Descripción de la interfaz: Crear una nueva configuración de plantilla.

Información de la solicitud:

• Método: POST
• Ruta: /v1/template-configs
• Autenticación: Obligatoria

Cuerpo de la solicitud:

              
              {
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

            

Descripción de campos de la solicitud:

Ejemplo de respuesta:

              
              {
  "template_id": "123456789"
}

            

Descripción de campos de respuesta:

Respuestas de error:

• 400: error de formato de parámetro, fallo de validación de parámetros, la configuración de firma no existe, el estado de la firma no está aprobado
• 500: error interno del servidor

Reglas de negocio:

• Tras la creación, las plantillas quedan en estado «Pendiente de revisión» (status=1).
• Si se añade una firma, la firma debe estar en estado aprobado.

4. Actualizar configuración de plantilla

Descripción de la interfaz: Actualizar una configuración de plantilla existente.

Información de la solicitud:

• Método: PUT
• Ruta: /v1/template-configs/:templateId
• Autenticación: Obligatoria

Parámetros de ruta:

Cuerpo de la solicitud: Igual que en la interfaz de creación; todos los campos son obligatorios.

Ejemplo de respuesta:

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

            

Respuestas de error:

• 400: error de formato de parámetro, la plantilla no existe, no se puede actualizar una plantilla en estado pendiente de revisión, no se pueden actualizar planes de mensajes en estado pendiente o en ejecución, la configuración de firma no existe, el estado de la firma no está aprobado
• 500: error interno del servidor

Reglas de negocio:

• Las plantillas en estado pendiente de revisión no se pueden actualizar.
• Si existen planes de mensajes en estado pendiente o en ejecución que utilicen la plantilla, no se puede actualizar.
• Tras la actualización, el estado de la plantilla volverá a «Pendiente de revisión» (status=1).

5. Eliminar configuración de plantilla

Descripción de la interfaz: Eliminar una configuración de plantilla específica.

Información de la solicitud:

• Método: DELETE
• Ruta: /v1/template-configs/:templateId
• Autenticación: Obligatoria

Parámetros de ruta:

Ejemplo de respuesta:

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

            

Respuestas de error:

• 400: error de formato del ID de plantilla, la plantilla no existe, no se pueden eliminar planes de mensajes en estado pendiente o en ejecución
• 500: error interno del servidor

Reglas de negocio:

• Si existen planes de mensajes en estado pendiente o en ejecución que utilicen la plantilla, no se puede eliminar.

Interfaz de configuración de firmas

1. Obtener lista de configuraciones de firma

Descripción de la interfaz: Obtener la lista de todas las configuraciones de firma del negocio actual.

Información de la solicitud:

• Método: GET
• Ruta: /v1/sign-configs
• Autenticación: Obligatoria

Parámetros de solicitud: Ninguno

Ejemplo de respuesta:

              
              [
  {
    "sign_id": "987654321",
    "sign_name": "Company Name",
    "status": 2,
    "related_template_count": 5,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Descripción de campos de respuesta:

2. Obtener detalles de configuración de firma

Descripción de la interfaz: Obtener información detallada de una configuración de firma por ID de firma.

Información de la solicitud:

• Método: GET
• Ruta: /v1/sign-configs/:signId
• Autenticación: Obligatoria

Parámetros de ruta:

Ejemplo de respuesta:

              
              {
  "sign_id": "987654321",
  "sign_name": "Company Name",
  "status": 2,
  "related_template_count": 5,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Respuestas de error:

• 400: formato de ID de firma no válido, la firma no existe o la firma no pertenece al negocio actual.
• 500: error interno del servidor.

3. Crear configuración de firma

Descripción de la interfaz: Crear una nueva configuración de firma.

Información de la solicitud:

• Método: POST
• Ruta: /v1/sign-configs
• Autenticación: Obligatoria

Cuerpo de la solicitud:

              
              {
  "sign_name": "Company Name"
}

            

Descripción de campos de la solicitud:

Ejemplo de respuesta:

              
              {
  "sign_id": "987654321"
}

            

Descripción de campos de respuesta:

Respuestas de error:

• 400: error de formato de parámetro, fallo de validación de parámetros o el nombre de la firma ya existe.
• 500: error interno del servidor.

Reglas de negocio:

• Tras la creación, el estado de la firma es «Pendiente de revisión» (status=1).
• Los nombres de firma no se pueden duplicar dentro del mismo negocio.

4. Actualizar configuración de firma

Descripción de la interfaz: Actualizar una configuración de firma existente.

Información de la solicitud:

• Método: PUT
• Ruta: /v1/sign-configs/:signId
• Autenticación: Obligatoria

Parámetros de ruta:

Cuerpo de la solicitud: Igual que en la interfaz de creación.

Ejemplo de respuesta:

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

            

Respuestas de error:

• 400: error de formato de parámetro, la firma no existe, la firma no pertenece al negocio actual, la firma está en estado pendiente de revisión y no se puede actualizar, el nombre de la firma ya existe o existen planes de mensajes pendientes o en ejecución que impiden la actualización.
• 500: error interno del servidor.

Reglas de negocio:

• Las firmas en estado pendiente de revisión no se pueden actualizar.
• Si existen planes de mensajes en estado pendiente o en ejecución que utilicen la firma, no se puede actualizar.
• Tras la actualización, el estado de la firma volverá a «Pendiente de revisión» (status=1).

5. Eliminar configuración de firma

Descripción de la interfaz: Eliminar una configuración de firma específica.

Información de la solicitud:

• Método: DELETE
• Ruta: /v1/sign-configs/:signId
• Autenticación: Obligatoria

Parámetros de ruta:

Ejemplo de respuesta:

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

            

Respuestas de error:

• 400: formato de ID de firma no válido, la firma no existe, la firma no pertenece al negocio actual o existen planes de mensajes pendientes o en ejecución que impiden la eliminación.
• 500: error interno del servidor.

Reglas de negocio:

• Si existen planes de mensajes en estado pendiente o en ejecución que utilicen la firma, no se puede eliminar.

Descripción de códigos de estado

Estado de configuración de plantilla (status)

Estado de configuración de firma (status)

Posición de firma (sign_position)

Tipo de plantilla (template_type)

Descripción de códigos de error

Mensajes de error comunes:

• invalid templateId: formato de ID de plantilla no válido.
• template config not exist: la configuración de plantilla no existe.
• invalid signId: formato de ID de firma no válido.
• sign config not exist: la configuración de firma no existe.
• sign_name already exist: el nombre de la firma ya existe.
• can not update pending status template: las plantillas en estado pendiente de revisión no se pueden actualizar.
• can not update pending status sign: las firmas en estado pendiente de revisión no se pueden actualizar.
• there are pending or running plans using current template, can not update: existen planes de mensajes pendientes o en ejecución que utilizan la plantilla; no se puede actualizar.
• there are pending or running plans using current sign, can not update: existen planes de mensajes pendientes o en ejecución que utilizan la firma; no se puede actualizar.
• sign status is not approved, can not use: el estado de la firma no está aprobado; no se puede utilizar.

Notas

1. Todas las interfaces requieren validación del middleware de autenticación.
2. Todas las interfaces asociarán automáticamente el ID de negocio (businessId) del usuario autenticado.
3. Las operaciones de creación y actualización de plantillas y firmas activarán el proceso de revisión.
4. Si una plantilla o firma es utilizada por un plan de mensajes, no se puede actualizar ni eliminar mientras el plan esté en estado pendiente o en ejecución.
5. El contenido de la plantilla no puede contener caracteres prohibidos: 【, 】, 、, 测试, test, [, ].
6. Los nombres de firma no pueden contener caracteres prohibidos: 【, 】, [, ].
7. Los ID de plantillas y firmas son cadenas numéricas.