共通ルール

注意：できるだけクライアント側でこのシリーズのAPIを使用しないでください

セキュリティおよび認証

Http Basic Auth方式を採用し、リクエストヘッダーに認証情報を追加します。その中で：

• ユーザー名はテナントのuuidです。
• パスワードはテナントのkeyです。

例：

curl https://mchat.udesk.cn/api/v1/merchants \
-X GET \
-u 'uuid:key' \ # 認証
-H 'content-type: application/json'

呼び出し

• HTTPSを使用する必要があります。
• ベースURL: https://mchat.udesk.cn/api/v1
• セキュリティ検証情報を含める必要があります。
• GET、POST、PUT、DELETEなどのHTTPメソッドをサポートします。
• リクエストおよびレスポンスボディ内のデータは、すべてJSON形式でエンコードされたUTF-8文字列です。
• POST/PUTリクエストのRequest Headerには、Content-Type: application/jsonを含める必要があります。
• すべてのリクエストのRequest Headerには、Accept: application/jsonを含めるべきです。

返却データ

HTTPステータスコードを通じてインターフェースの返却結果を判定します：

• リクエスト成功時: 2xx
• 認証失敗時: 401
• エラー発生時: 400
• 回復不可能なエラー発生時: 500

エラー時のResponse Bodyの内容形式は以下の通りです：

{
    "code": "tenant_not_found",
    "message": "アクセスされたテナント「ab476257-5230-42f2-ae14-ea2a8e9ceb1d」は存在しません"
}

ページネーション

基本的にすべてのリスト取得系インターフェースは、page、per_pageパラメータをサポートしています：

属性	タイプ	必須	デフォルト値	説明
page	整数型	いいえ	1	最小値は1、1未満は1として扱われます。
per_page	整数型	いいえ	30	最大値は各インターフェースによって決定され、最大値を超える場合は最大値として扱われます。

ページネーションをサポートするインターフェースは、返却時にページネーション情報を付加します：

meta:
    page: 現在のページ番号
    per_page: 1ページあたりの数量
    page_total: 総ページ数
    item_total: データ総数

データ形式

タイプ	形式	空値	例
日時	テキスト、ISO8601	null	2006-01-02T15:04:05.000+08:00
時間	テキスト、ISO8601	null	2006-01-02
日付	テキスト、ISO8601	null	15:04:05+08:00
タイムスタンプ	整数、UNIXタイムスタンプ	0	1136185445(2006-01-02 15:04:05)
文字列	テキスト	""	"Hello"、"サンプル"
整数型	整数	0	1、1998
数値	実数	0	3.1415926
ブール値	true/false	false	true、false
オブジェクト	JSONオブジェクト	null	{"age": 13}
### データ例

データ名	例
タイムスタンプ	1136185445
日付	2006-01-02
時間	15:04:05+08:00
日時	2006-01-02T15:04:05.000+08:00
テナント uuid	ab476257-5230-42f2-ae14-ea2a8e9ceb1d
テナント key	eba52e58c494cf68dd1077ddb174264c
マーチャント euid	merchant01
マーチャント im_username	demo_merchant_1@udeskchannel.com
マーチャント im_password	115b87a91d1af96d13ffe390660b5743
顧客 euid	customer01
顧客 im_username	demo_customer_1@udeskchannel.com
顧客 im_password	b0f61445454ed0e81aca820eb9ee264c
顧客 openid	5e6c112f-772e-4ae2-a35f-338b961007d9
メッセージ uuid	0bbcd6ba-b8d6-4ad4-b90f-a634454e0d47

---

マーチャントリストの取得

GET /merchants

リクエストパラメータ

# Query String
page: ページ番号
per_page: 1ページあたりの件数, 最大100件

レスポンスデータ

merchants:
    id: 識別子
    euid: 一意識別子
    name: マーチャント名
    subdomain: udesk カスタマーサポートシステムのサブドメイン
    im_agent_total: IM エージェント数
    ticket_agent_total: チケットエージェント数
    created_at: 作成日時
    updated_at: 最終更新日時
meta:
    page: 現在のページ番号
    per_page: 1ページあたりの件数
    page_total: 総ページ数
    item_total: データ総数

例

curl https://mchat.udesk.cn/api/v1/merchants \
-X GET \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json'

レスポンス

{
    "merchants": [
        {
            "id": 1,
            "euid": "merchant01",
            "name": "テストマーチャント1",
            "subdomain": "m01",
            "im_agent_total": 2,
            "ticket_agent_total": 2,
            "created_at": "2006-01-02T15:04:05.000+08:00",
            "updated_at": "2006-01-02T15:04:05.000+08:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 10,
        "page_total": 1,
        "item_total": 1
    }
}

---

マーチャント作成

POST /merchants

リクエストパラメータ

# リクエストボディ
merchant:
    euid: 外部ユニーク識別子
    name: マーチャント名
    subdomain: Udesk カスタマーサポートシステムのサブドメイン
    im_agent_total: IM エージェント数
    ticket_agent_total: チケットエージェント数
admin:
    email: Udesk カスタマーサポートプラットフォーム管理者メールアドレス
    password: Udesk カスタマーサポートプラットフォーム管理者パスワード

レスポンスデータ

merchant:
    id: 識別子
    euid: ユニーク識別子
    name: マーチャント名
    subdomain: Udesk カスタマーサポートシステムのサブドメイン
    im_agent_total: IM エージェント数
    ticket_agent_total: チケットエージェント数
    created_at: 作成日時
    updated_at: 最終更新日時

例

curl https://mchat.udesk.cn/api/v1/merchants \
-X POST \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json' \
-d '
{
    "merchant": {
        "euid": "merchant01",
        "name": "テストマーチャント1",
        "subdomain": "m01",
        "im_agent_total": 2,
        "ticket_agent_total": 2
    },
    "admin": {
        "email": "admin@merchant01.com",
        "password": "password123"
    }
}'

レスポンス

{
    "merchant": {
        "id": 1,
        "euid": "merchant01",
        "name": "テストマーチャント1",
        "subdomain": "m01",
        "im_agent_total": 2,
        "ticket_agent_total": 2
        "created_at": "2006-01-02T15:04:05.000+08:00",
        "updated_at": "2006-01-02T15:04:05.000+08:00"
    }
}

---

マーチャント更新

PUT /merchants/:id

リクエストパラメータ

# URL
id: マーチャント外部識別子

# リクエストボディ
merchant:
    name: マーチャント名
    im_agent_total: IM エージェント数
    ticket_agent_total: チケットエージェント数

返却データ

加盟店作成インターフェースと同じです。

例

curl https://mchat.udesk.cn/api/v1/merchants/1 \
-X PUT \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json' \
-d '
{
    "merchant": {
        "name": "テスト加盟店1",
        "im_agent_total": 2,
        "ticket_agent_total": 2
    }
}'

返却は加盟店作成インターフェースと同じです。

---

加盟店ロゴを変更

PUT /merchants/:id/logo

注意: このインターフェースの Content-Type は image/jpeg または image/png です

リクエストパラメータ

# URL
id: 加盟店外部識別子

# Request Body
画像ファイルの内容

返却データ

加盟店作成インターフェースと同じです。

例

curl https://mchat.udesk.cn/api/v1/merchants/1/logo \
-X PUT \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: image/png' \
--data-binary @filename.png

返却は加盟店作成インターフェースと同じです。

---

加盟店を削除

DELETE /merchants/:id

リクエストパラメータ

# URL
id: 加盟店外部識別子

返却データ

加盟店作成インターフェースと同じです。

例

curl https://mchat.udesk.cn/api/v1/merchants/1 \
-X DELETE \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json'

返却は加盟店作成インターフェースと同じです。

---

サブマーチャントの初期化

POST /merchants/init_sub_merchants

リクエストパラメータ

# リクエストボディ
merchant_ids: マーチャントIDの文字列。複数ある場合はカンマで区切ります。

レスポンスデータ

code: 200 # 成功
message: 'success'

例

curl https://mchat.udesk.cn/api/v1/merchants/init_sub_merchants \
-X POST \
-u 'ab476257-5230-42f2-ae14-ea2a8e9ceb1d:eba52e58c494cf68dd1077ddb174264c' \
-H 'content-type: application/json' \
-d '
{
    "merchant_ids": "1,2"
}'

レスポンス

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

---

顧客の未読メッセージ数を取得

GET https://mchat.udesk.cn/client/v1/:uuid/customers/unread

このAPIは認証不要です。 uuid はテナントのuuidです。

リクエストパラメータ

euid: 顧客のeuid。必須。

レスポンスデータ

unread: Boolean, 未読メッセージがあるかどうか

例

curl https://mchat.udesk.cn/client/v1/ab476257-5230-42f2-ae14-ea2a8e9ceb1d/customers/unread?euid=1

レスポンス

{
    "unread": true
}

---

コードエラー

エラーコード	message情報	exception:message情報	説明
unknown	不明なエラー	なし	パラメータpageまたはper_pageの形式が不正です（例：負の数や文字列）。
proj_internal_error	検証失敗	なし	登録メールアドレスが既に使用されているか、サブドメインが既に使用されています。
save_failed	マーチャントの保存に失敗しました	なし	外部識別子euidが重複しているか、IMまたはチケットエージェントの総数がテナントのインスタントメッセージングサポート数の上限を超えています。
record_not_found	マーチャントが見つかりません	なし	指定されたIDに対応するマーチャントが見つかりません。
	顧客が見つかりません	なし	指定されたeuidに対応する顧客が見つかりません。
tenant_not_found	「xxx」は存在しません	なし	アクセスしたテナント「xxx」は存在しません。
2015	管理者のみ操作可能です	管理者のみ操作可能です	APIを呼び出す際のメールアドレスは管理者のものである必要があります。管理者以外は操作できません。
2059	open apiの署名が不正です	open apiの署名が不正です	open apiの署名が不正です。詳細は認証セクションのドキュメントを参照してください。