RESTful API-Dokumentation: Verwaltung von Vorlagen- und Signaturkonfigurationen

Dieses Dokument beschreibt die RESTful API-Schnittstellen für die Verwaltung von Vorlagen- und Signaturkonfigurationen. Die API ermöglicht Unternehmen eine effiziente Steuerung und Automatisierung ihrer Kommunikationsprozesse.

Grundlegende Informationen

• Domain: https://smsapi.engagelab.com
• Authentifizierungsmethode: Basic Authentication (Base64-Kodierung)
  • Format: Authorization: Basic base64(apikey:apisecret)
  • Beispiel: Kodieren Sie apikey:apisecret in Base64 und fügen Sie anschließend Authorization: Basic <kodierter String> dem Request-Header hinzu.
• Content-Type: application/json

Antwortformat

Erfolgreiche Antwort

Erfolgreiche Antworten geben direkt ein Datenobjekt oder ein Array zurück:

{
  "template_id": "123456789",
  "template_name": "Beispielvorlage",
  ...
}

Oder als Listenantwort:

[
  {
    "template_id": "123456789",
    "template_name": "Beispielvorlage",
    ...
  }
]

Fehlerantwort

{
  "code": 400,
  "message": "Fehlerbeschreibung"
}

Schnittstellen zur Vorlagenkonfiguration

1. Vorlagenkonfigurationsliste abrufen

Beschreibung: Gibt die Liste aller Vorlagenkonfigurationen für das aktuelle Unternehmen zurück.

• Methode: GET
• Pfad: /v1/template-configs
• Authentifizierung: Erforderlich

Request-Parameter: Keine

Beispielantwort:

[
  {
    "template_id": "123456789",
    "template_name": "Bestellbenachrichtigung",
    "template_type": "utility",
    "template_content": "Ihre Bestellung {order_no} wurde versandt und wird voraussichtlich bis {delivery_time} geliefert.",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "Firmenname",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

Feldbeschreibung der Antwort:

Feldname	Typ	Beschreibung
template_id	string	Vorlagen-ID
template_name	string	Vorlagenname
template_type	string	Vorlagentyp: utility (Benachrichtigung), marketing (Marketing)
template_content	string	Vorlageninhalt
country_codes	string	Hauptversand-Ländercodes, durch Kommas getrennt
status	int	Status: 1–Prüfung ausstehend, 2–Genehmigt, 3–Abgelehnt
sign_id	string	Signatur-ID (optional)
sign_name	string	Signaturname (optional)
sign_position	int	Signaturposition: 0–Keine, 1–Präfix, 2–Suffix (optional)
sign_status	int	Signaturstatus (optional)
audit_remark	string	Prüfungsanmerkungen
created_time	int64	Erstellungszeitpunkt (Unix-Timestamp)
updated_time	int64	Aktualisierungszeitpunkt (Unix-Timestamp)

2. Vorlagenkonfigurationsdetails abrufen

Beschreibung: Gibt die Detailinformationen einer Vorlagenkonfiguration anhand der Vorlagen-ID zurück.

• Methode: GET
• Pfad: /v1/template-configs/:templateId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
templateId	string	Ja	Vorlagen-ID

Beispielantwort:

{
  "template_id": "123456789",
  "template_name": "Bestellbenachrichtigung",
  "template_type": "utility",
  "template_content": "Ihre Bestellung {order_no} wurde versandt und wird voraussichtlich bis {delivery_time} geliefert.",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "Firmenname",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

Fehlerantworten:

• 400: Fehlerhaftes Vorlagen-ID-Format oder Vorlage existiert nicht
• 500: Interner Serverfehler

3. Vorlagenkonfiguration erstellen

Beschreibung: Erstellt eine neue Vorlagenkonfiguration.

• Methode: POST
• Pfad: /v1/template-configs
• Authentifizierung: Erforderlich

Request-Body:

{
  "template_name": "Bestellbenachrichtigung",
  "template_type": "utility",
  "template_content": "Ihre Bestellung {order_no} wurde versandt und wird voraussichtlich bis {delivery_time} geliefert.",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

Feldbeschreibung der Anfrage:

Feldname	Typ	Erforderlich	Beschreibung
template_name	string	Ja	Vorlagenname, maximal 255 Zeichen
template_type	string	Ja	Vorlagentyp: utility (Benachrichtigung), marketing (Marketing)
template_content	string	Ja	Vorlageninhalt, darf folgende Zeichen nicht enthalten: 【, 】, ,, 测试, test, [, ]
country_codes	string	Ja	Hauptversand-Ländercodes, durch Kommas getrennt
add_signature	bool	Nein	Gibt an, ob eine Signatur hinzugefügt werden soll, Standard: false
sign_id	string	Bedingt	Erforderlich, wenn add_signature true ist, Signatur-ID
sign_position	int	Bedingt	Erforderlich, wenn add_signature true ist, Signaturposition: 1–Präfix, 2–Suffix

Beispielantwort:

{
  "template_id": "123456789"
}

Feldname	Typ	Beschreibung
template_id	string	Erstellte Vorlagen-ID

Fehlerantworten:

• 400: Fehlerhaftes Parameterformat, Validierung fehlgeschlagen, Signaturkonfiguration existiert nicht, Signaturstatus nicht genehmigt
• 500: Interner Serverfehler

Geschäftsregeln:

• Nach Erstellung ist der Status der Vorlage „Prüfung ausstehend“ (status=1).
• Wird eine Signatur hinzugefügt, muss diese genehmigt sein.

4. Vorlagenkonfiguration aktualisieren

Beschreibung: Aktualisiert eine bestehende Vorlagenkonfiguration.

• Methode: PUT
• Pfad: /v1/template-configs/:templateId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
templateId	string	Ja	Vorlagen-ID

Request-Body: Wie bei der Erstellung, alle Felder erforderlich.

Beispielantwort:

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

Fehlerantworten:

• 400: Fehlerhaftes Parameterformat, Vorlage existiert nicht, Status „Prüfung ausstehend“ verhindert Aktualisierung, ausstehende oder laufende Pläne verhindern Aktualisierung, Signaturkonfiguration existiert nicht, Signaturstatus nicht genehmigt
• 500: Interner Serverfehler

Geschäftsregeln:

• Vorlagen im Status „Prüfung ausstehend“ können nicht aktualisiert werden.
• Wenn es ausstehende oder laufende Nachrichtenpläne gibt, die diese Vorlage verwenden, kann sie nicht aktualisiert werden.
• Nach der Aktualisierung wird der Status der Vorlage wieder auf „Prüfung ausstehend“ (status=1) gesetzt.

5. Vorlagenkonfiguration löschen

Beschreibung: Löscht eine bestimmte Vorlagenkonfiguration.

• Methode: DELETE
• Pfad: /v1/template-configs/:templateId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
templateId	string	Ja	Vorlagen-ID

Beispielantwort:

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

Fehlerantworten:

• 400: Fehlerhaftes Vorlagen-ID-Format, Vorlage existiert nicht, ausstehende oder laufende Pläne verhindern Löschung
• 500: Interner Serverfehler

Geschäftsregeln:

• Wenn es ausstehende oder laufende Nachrichtenpläne gibt, die diese Vorlage verwenden, kann sie nicht gelöscht werden.

Schnittstellen zur Signaturkonfiguration

1. Signaturkonfigurationsliste abrufen

Beschreibung: Gibt die Liste aller Signaturkonfigurationen für das aktuelle Unternehmen zurück.

• Methode: GET
• Pfad: /v1/sign-configs
• Authentifizierung: Erforderlich

Request-Parameter: Keine

Beispielantwort:

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

Feldbeschreibung der Antwort:

Feldname	Typ	Beschreibung
sign_id	string	Signatur-ID
sign_name	string	Signaturname
status	int	Status: 1–Prüfung ausstehend, 2–Genehmigt, 3–Abgelehnt
related_template_count	int64	Anzahl verknüpfter Vorlagen
audit_remark	string	Prüfungsanmerkungen
created_time	int64	Erstellungszeitpunkt (Unix-Timestamp)
updated_time	int64	Aktualisierungszeitpunkt (Unix-Timestamp)

2. Signaturkonfigurationsdetails abrufen

Beschreibung: Gibt die Detailinformationen einer Signaturkonfiguration anhand der Signatur-ID zurück.

• Methode: GET
• Pfad: /v1/sign-configs/:signId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
signId	string	Ja	Signatur-ID

Beispielantwort:

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

Fehlerantworten:

• 400: Ungültiges Signatur-ID-Format, Signatur existiert nicht oder gehört nicht zum aktuellen Unternehmen.
• 500: Interner Serverfehler.

3. Signaturkonfiguration erstellen

Beschreibung: Erstellt eine neue Signaturkonfiguration.

• Methode: POST
• Pfad: /v1/sign-configs
• Authentifizierung: Erforderlich

Request-Body:

{
  "sign_name": "Firmenname"
}

Feldbeschreibung der Anfrage:

Feldname	Typ	Erforderlich	Beschreibung
sign_name	string	Ja	Signaturname, 2–60 Zeichen, darf folgende Zeichen nicht enthalten: 【, 】, [, ]

Beispielantwort:

{
  "sign_id": "987654321"
}

Feldname	Typ	Beschreibung
sign_id	string	Erstellte Signatur-ID

Fehlerantworten:

• 400: Fehlerhaftes Parameterformat, Validierung fehlgeschlagen oder Signaturname existiert bereits.
• 500: Interner Serverfehler.

Geschäftsregeln:

• Der Status der Signatur nach Erstellung ist „Prüfung ausstehend“ (status=1).
• Signaturnamen dürfen innerhalb eines Unternehmens nicht doppelt vergeben werden.

4. Signaturkonfiguration aktualisieren

Beschreibung: Aktualisiert eine bestehende Signaturkonfiguration.

• Methode: PUT
• Pfad: /v1/sign-configs/:signId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
signId	string	Ja	Signatur-ID

Request-Body: Wie bei der Erstellung.

Beispielantwort:

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

Fehlerantworten:

• 400: Fehlerhaftes Parameterformat, Signatur existiert nicht, Signatur gehört nicht zum aktuellen Unternehmen, Status „Prüfung ausstehend“ verhindert Aktualisierung, Signaturname existiert bereits oder ausstehende/laufende Pläne verhindern Aktualisierung.
• 500: Interner Serverfehler.

Geschäftsregeln:

• Signaturen im Status „Prüfung ausstehend“ können nicht aktualisiert werden.
• Wenn es ausstehende oder laufende Nachrichtenpläne gibt, die diese Signatur verwenden, kann sie nicht aktualisiert werden.
• Nach der Aktualisierung wird der Status der Signatur wieder auf „Prüfung ausstehend“ (status=1) gesetzt.

5. Signaturkonfiguration löschen

Beschreibung: Löscht eine bestimmte Signaturkonfiguration.

• Methode: DELETE
• Pfad: /v1/sign-configs/:signId
• Authentifizierung: Erforderlich

Pfadparameter:

Parametername	Typ	Erforderlich	Beschreibung
signId	string	Ja	Signatur-ID

Beispielantwort:

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

Fehlerantworten:

• 400: Ungültiges Signatur-ID-Format, Signatur existiert nicht, Signatur gehört nicht zum aktuellen Unternehmen oder ausstehende/laufende Pläne verhindern Löschung.
• 500: Interner Serverfehler.

Geschäftsregeln:

• Wenn es ausstehende oder laufende Nachrichtenpläne gibt, die diese Signatur verwenden, kann sie nicht gelöscht werden.

Statuscode-Beschreibungen

Vorlagenkonfigurationsstatus (status)

Wert	Beschreibung
1	Prüfung ausstehend
2	Genehmigt
3	Abgelehnt

Signaturkonfigurationsstatus (status)

Wert	Beschreibung
1	Prüfung ausstehend
2	Genehmigt
3	Abgelehnt

Signaturposition (sign_position)

Wert	Beschreibung
0	Keine Signatur
1	Präfix
2	Suffix

Vorlagentyp (template_type)

Wert	Beschreibung
utility	Benachrichtigung
marketing	Marketing

Fehlercode-Beschreibungen

Fehlercode	HTTP-Statuscode	Beschreibung
0	200	Erfolg
400	400	Parameterfehler oder Geschäftslogikfehler
500	500	Interner Serverfehler

Häufige Fehlermeldungen:

• „invalid templateId“: Ungültiges Vorlagen-ID-Format.
• „template config not exist“: Vorlagenkonfiguration existiert nicht.
• „invalid signId“: Ungültiges Signatur-ID-Format.
• „sign config not exist“: Signaturkonfiguration existiert nicht.
• „sign_name already exist“: Signaturname existiert bereits.
• „can not update pending status template“: Vorlagen im Status „Prüfung ausstehend“ können nicht aktualisiert werden.
• „can not update pending status sign“: Signaturen im Status „Prüfung ausstehend“ können nicht aktualisiert werden.
• „there are pending or running plans using current template, can not update“: Es gibt ausstehende oder laufende Pläne, die diese Vorlage verwenden; Aktualisierung nicht möglich.
• „there are pending or running plans using current sign, can not update“: Es gibt ausstehende oder laufende Pläne, die diese Signatur verwenden; Aktualisierung nicht möglich.
• „sign status is not approved, can not use“: Signaturstatus ist nicht genehmigt und kann nicht verwendet werden.

Hinweise

1. Alle Schnittstellen erfordern eine Authentifizierungsmiddleware.
2. Bei allen Schnittstellen wird die businessId des authentifizierten Nutzers automatisch zugeordnet.
3. Das Erstellen und Aktualisieren von Vorlagen und Signaturen löst einen Prüfprozess aus.
4. Wenn eine Vorlage oder Signatur von einem Nachrichtenplan genutzt wird, kann sie nicht aktualisiert oder gelöscht werden, solange der Plan im Status „ausstehend“ oder „laufend“ ist.
5. Vorlageninhalte dürfen folgende Zeichen nicht enthalten: 【, 】, 、, 测试, test, [, ].
6. Signaturnamen dürfen folgende Zeichen nicht enthalten: 【, 】, [, ].
7. Die IDs von Vorlagen und Signaturen bestehen aus numerischen Zeichenfolgen.