Template&Sender ID

Ce document décrit les interfaces API RESTful relatives à la configuration des modèles et à la configuration des signatures.

Informations de base

• Domaine : https://smsapi.engagelab.com
• Méthode d'authentification : Authentification Basic (encodage Base64)
  • Format : Authorization: Basic base64(apikey:apisecret)
  • Exemple : Encoder apikey:apisecret en Base64, puis ajouter Authorization: Basic <chaîne encodée> dans l'en-tête de la requête.
• Content-Type : application/json

Format de la réponse

Réponse réussie

Les réponses réussies renvoient directement un objet de données ou un tableau :

              
              {
  "template_id": "123456789",
  "template_name": "Exemple de modèle",
  ...
}

            

Ou une réponse sous forme de liste :

              
              [
  {
    "template_id": "123456789",
    "template_name": "Exemple de modèle",
    ...
  }
]

            

Réponse d'erreur

Format de la réponse d'erreur :

              
              {
  "code": 400,
  "message": "Description de l'erreur"
}

            

Interfaces de configuration des modèles

1. Obtenir la liste des configurations de modèles

Description de l'interface : Récupérer la liste de toutes les configurations de modèles du commerce actuel.

Informations de la requête :

• Méthode : GET
• Chemin : /v1/template-configs
• Authentification : Requise

Paramètres de la requête : Aucun

Exemple de réponse :

              
              [
  {
    "template_id": "123456789",
    "template_name": "Modèle de notification de commande",
    "template_type": "utility",
    "template_content": "Votre commande {order_no} a été expédiée et devrait arriver avant {delivery_time}.",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "Nom de l'entreprise",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Description des champs de la réponse :

2. Obtenir les détails d'une configuration de modèle

Description de l'interface : Récupérer les informations détaillées d'une configuration de modèle par ID de modèle.

Informations de la requête :

• Méthode : GET
• Chemin : /v1/template-configs/:templateId
• Authentification : Requise

Paramètres de chemin :

Exemple de réponse :

              
              {
  "template_id": "123456789",
  "template_name": "Modèle de notification de commande",
  "template_type": "utility",
  "template_content": "Votre commande {order_no} a été expédiée et devrait arriver avant {delivery_time}.",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "Nom de l'entreprise",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Réponses d'erreur :

• 400 : Erreur de format d'ID de modèle ou modèle inexistant
• 500 : Erreur interne du serveur

3. Créer une configuration de modèle

Description de l'interface : Créer une nouvelle configuration de modèle.

Informations de la requête :

• Méthode : POST
• Chemin : /v1/template-configs
• Authentification : Requise

Corps de la requête :

              
              {
  "template_name": "Modèle de notification de commande",
  "template_type": "utility",
  "template_content": "Votre commande {order_no} a été expédiée et devrait arriver avant {delivery_time}.",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

            

Description des champs de la requête :

Exemple de réponse :

              
              {
  "template_id": "123456789"
}

            

Description des champs de la réponse :

Réponses d'erreur :

• 400 : Erreur de format de paramètre, validation échouée, configuration de signature inexistante, statut de signature non validé
• 500 : Erreur interne du serveur

Règles métier :

• Les modèles sont en statut "En attente de validation" (status=1) après création.
• Si une signature est ajoutée, elle doit être validée.

4. Mettre à jour une configuration de modèle

Description de l'interface : Mettre à jour une configuration de modèle existante.

Informations de la requête :

• Méthode : PUT
• Chemin : /v1/template-configs/:templateId
• Authentification : Requise

Paramètres de chemin :

Corps de la requête : Identique à l'interface de création, tous les champs sont requis.

Exemple de réponse :

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

            

Réponses d'erreur :

• 400 : Erreur de format de paramètre, modèle inexistant, modèle en attente de validation non modifiable, plans en attente ou en cours non modifiables, configuration de signature inexistante, statut de signature non validé
• 500 : Erreur interne du serveur

Règles métier :

• Les modèles en attente de validation ne peuvent pas être modifiés.
• Si des plans de messages en attente ou en cours utilisent le modèle, il ne peut pas être modifié.
• Après modification, le statut du modèle repasse à "En attente de validation" (status=1).

5. Supprimer une configuration de modèle

Description de l'interface : Supprimer une configuration de modèle spécifiée.

Informations de la requête :

• Méthode : DELETE
• Chemin : /v1/template-configs/:templateId
• Authentification : Requise

Paramètres de chemin :

Exemple de réponse :

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

            

Réponses d'erreur :

• 400 : Erreur de format d'ID de modèle, modèle inexistant, plans en attente ou en cours non supprimables
• 500 : Erreur interne du serveur

Règles métier :

• Si des plans de messages en attente ou en cours utilisent le modèle, il ne peut pas être supprimé.

Interface de configuration des signatures

1. Obtenir la liste des configurations de signatures

Description de l'interface : Récupérer la liste de toutes les configurations de signatures du commerce actuel.

Informations de la requête :

• Méthode : GET
• Chemin : /v1/sign-configs
• Authentification : Requise

Paramètres de la requête : Aucun

Exemple de réponse :

              
              [
  {
    "sign_id": "987654321",
    "sign_name": "Nom de l'entreprise",
    "status": 2,
    "related_template_count": 5,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Description des champs de la réponse :

2. Obtenir les détails d'une configuration de signature

Description de l'interface : Récupérer les informations détaillées d'une configuration de signature par ID de signature.

Informations de la requête :

• Méthode : GET
• Chemin : /v1/sign-configs/:signId
• Authentification : Requise

Paramètres de chemin :

Exemple de réponse :

              
              {
  "sign_id": "987654321",
  "sign_name": "Nom de l'entreprise",
  "status": 2,
  "related_template_count": 5,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Réponses d'erreur :

• 400 : Format d'ID de signature invalide, signature inexistante ou signature n'appartenant pas au commerce actuel.
• 500 : Erreur interne du serveur.

3. Créer une configuration de signature

Description de l'interface : Créer une nouvelle configuration de signature.

Informations de la requête :

• Méthode : POST
• Chemin : /v1/sign-configs
• Authentification : Requise

Corps de la requête :

              
              {
  "sign_name": "Nom de l'entreprise"
}

            

Description des champs de la requête :

Exemple de réponse :

              
              {
  "sign_id": "987654321"
}

            

Description des champs de la réponse :

Réponses d'erreur :

• 400 : Erreur de format de paramètre, validation échouée ou nom de signature déjà existant.
• 500 : Erreur interne du serveur.

Règles métier :

• Le statut de la signature après création est "En attente de validation" (status=1).
• Les noms de signature ne peuvent pas être dupliqués dans un même commerce.

4. Mettre à jour une configuration de signature

Description de l'interface : Mettre à jour une configuration de signature existante.

Informations de la requête :

• Méthode : PUT
• Chemin : /v1/sign-configs/:signId
• Authentification : Requise

Paramètres de chemin :

Corps de la requête : Identique à l'interface de création.

Exemple de réponse :

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

            

Réponses d'erreur :

• 400 : Erreur de format de paramètre, signature inexistante, signature n'appartenant pas au commerce actuel, signature en attente de validation non modifiable, nom de signature déjà existant, ou présence de plans en attente ou en cours empêchant la modification.
• 500 : Erreur interne du serveur.

Règles métier :

• Les signatures en attente de validation ne peuvent pas être modifiées.
• Si des plans de messages en attente ou en cours utilisent la signature, elle ne peut pas être modifiée.
• Après modification, le statut de la signature repasse à "En attente de validation" (status=1).

5. Supprimer une configuration de signature

Description de l'interface : Supprimer une configuration de signature spécifiée.

Informations de la requête :

• Méthode : DELETE
• Chemin : /v1/sign-configs/:signId
• Authentification : Requise

Paramètres de chemin :

Exemple de réponse :

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

            

Réponses d'erreur :

• 400 : Format d'ID de signature invalide, signature inexistante, signature n'appartenant pas au commerce actuel, ou présence de plans en attente ou en cours empêchant la suppression.
• 500 : Erreur interne du serveur.

Règles métier :

• Si des plans de messages en attente ou en cours utilisent la signature, elle ne peut pas être supprimée.

Description des codes de statut

Statut de la configuration de modèle (status)

Statut de la configuration de signature (status)

Position de la signature (sign_position)

Type de modèle (template_type)

Description des codes d'erreur

Messages d'erreur courants :

• invalid templateId : Format d'ID de modèle invalide.
• template config not exist : Configuration de modèle inexistante.
• invalid signId : Format d'ID de signature invalide.
• sign config not exist : Configuration de signature inexistante.
• sign_name already exist : Nom de signature déjà existant.
• can not update pending status template : Les modèles en attente de validation ne peuvent pas être modifiés.
• can not update pending status sign : Les signatures en attente de validation ne peuvent pas être modifiées.
• there are pending or running plans using current template, can not update : Des plans en attente ou en cours utilisent le modèle, modification impossible.
• there are pending or running plans using current sign, can not update : Des plans en attente ou en cours utilisent la signature, modification impossible.
• sign status is not approved, can not use : Le statut de la signature n'est pas validé, utilisation impossible.

Remarques

1. Toutes les interfaces nécessitent une validation par un middleware d'authentification.
2. Toutes les interfaces associent automatiquement l'ID du commerce de l'utilisateur authentifié (businessId).
3. Les opérations de création et de mise à jour des modèles et signatures déclenchent un processus de validation.
4. Si un modèle ou une signature est utilisé par un plan de messages, il ne peut pas être modifié ou supprimé tant que le plan est en attente ou en cours.
5. Le contenu du modèle ne peut pas contenir les caractères interdits : 【, 】, 、, 测试, test, [, ].
6. Les noms de signature ne peuvent pas contenir les caractères interdits : 【, 】, [, ].
7. Les IDs des modèles et des signatures sont des chaînes numériques.