テンプレート＆送信者ID

このドキュメントは、テンプレート設定および署名設定に関連するRESTful APIインターフェースについて説明します。

基本情報

• ドメイン: https://smsapi.engagelab.com
• 認証方法: Basic認証（Base64エンコード）
  • フォーマット: Authorization: Basic base64(apikey:apisecret)
  • 例: apikey:apisecretをBase64エンコードし、リクエストヘッダーにAuthorization: Basic <エンコードされた文字列>を追加します。
• Content-Type: application/json

レスポンス形式

成功レスポンス

成功レスポンスはデータオブジェクトまたは配列を直接返します:

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

            

またはリスト形式のレスポンス:

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

            

エラーレスポンス

エラーレスポンス形式:

              
              {
  "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: サーバー内部エラー

ビジネスルール:

• 保留中または実行中のメッセージプランで使用されているテンプレートは削除できません。

シグネチャ設定API

1. シグネチャ設定リストの取得

API説明: 現在のビジネスにおけるすべてのシグネチャ設定リストを取得します。

リクエスト情報:

• メソッド: GET
• パス: /v1/sign-configs
• 認証: 必須

リクエストパラメータ: なし

レスポンス例:

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

            

レスポンスフィールド説明:

2. シグネチャ設定詳細の取得

API説明: シグネチャ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. シグネチャ設定の作成

API説明: 新しいシグネチャ設定を作成します。

リクエスト情報:

• メソッド: POST
• パス: /v1/sign-configs
• 認証: 必須

リクエストボディ:

              
              {
  "sign_name": "会社名"
}

            

リクエストフィールド説明:

レスポンス例:

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

            

エラーレスポンス:

• 400: パラメータ形式エラー、パラメータ検証失敗、またはシグネチャ名が既に存在する。
• 500: サーバー内部エラー。

ビジネスルール:

• 新しく作成されたシグネチャのステータスは「審査中」(status=1)です。
• 同じビジネス内でシグネチャ名は重複できません。

4. シグネチャ設定の更新

API説明: 既存のシグネチャ設定を更新します。

リクエスト情報:

• メソッド: PUT
• パス: /v1/sign-configs/:signId
• 認証: 必須

パスパラメータ:

リクエストボディ: 作成APIと同じ。

レスポンス例:

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

            

エラーレスポンス:

• 400: パラメータ形式エラー、シグネチャが存在しない、現在のビジネスに属していない、ステータスが審査中で更新できない、シグネチャ名が既に存在する、または保留中または実行中のプランがあり更新できない。
• 500: サーバー内部エラー。

ビジネスルール:

• 審査中のステータスのシグネチャは更新できません。
• 保留中または実行中のメッセージプランで使用されている場合、更新できません。
• 更新後、シグネチャのステータスは「審査中」(status=1)に戻ります。

5. シグネチャ設定の削除

API説明: 指定されたシグネチャ設定を削除します。

リクエスト情報:

• メソッド: 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. すべてのAPIは認証ミドルウェア検証を必要とします。
2. すべてのAPIは認証されたユーザーのビジネスID (businessId) を自動的に関連付けます。
3. テンプレートおよびシグネチャの作成および更新操作は審査プロセスをトリガーします。
4. テンプレートまたはシグネチャがメッセージプランで使用されている場合、プランが保留中または実行中のステータスである間は更新または削除できません。
5. テンプレート内容には禁止文字を含めることはできません: 【, 】, ,, test, [, ]。
6. シグネチャ名には禁止文字を含めることはできません: 【, 】, [, ]。
7. テンプレートおよびシグネチャIDは数値文字列です。