テンプレート＆送信者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
}

            

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

レスポンス例:

              
              {
  "template_id": "123456789"
}

            

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

エラーレスポンス:

• 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": "会社名"
}

            

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

レスポンス例:

              
              {
  "sign_id": "987654321"
}

            

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

エラーレスポンス:

• 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は数値文字列です。