呼び出し制限

Udesk オープンインターフェース（v2）を使用する際は、以下のルールに従う必要があります：

呼び出し形式

HTTP メソッド

Udesk オープンインターフェース（v2）では、以下の HTTP メソッドが使用される場合があります：

各インターフェースのドキュメントで使用する HTTP メソッドを明記します。インターフェースを呼び出す際は、具体的なインターフェースドキュメントを参照してください。

呼び出しアドレス

Udesk 開発インターフェースの呼び出しアドレスは、すべて以下の形式に従います：

https://[サブドメイン].udesk.cn/open_api_v1/[インターフェース相対アドレス]?[URLパラメータ]&email=[管理者メールアドレス]&timestamp=[タイムスタンプ]&sign=[署名]&nonce=[リクエストの一意識別子]&sign_version=[署名アルゴリズムバージョン]

角括弧で囲まれた部分の意味は以下の通りです：

変数 説明
サブドメイン Udeskサポートシステムにアクセスする際に使用するサブドメイン
インターフェース相対アドレス 呼び出す具体的なAPIの相対URL。各APIで明記されます
URLパラメータ インターフェースに必要なQuery Stringパラメータ
管理者メールアドレス ご自身のスーパー管理者メールアドレス
タイムスタンプ リクエストを開始した時刻のタイムスタンプ。Unix Time形式（"1970-01-01 00:00:00"からの経過秒数）
署名 認証署名。特に明記されていない限り、毎回のAPI呼び出しに必要です。計算方法は認証方法を参照してください
リクエストの一意識別子 15分間に1回しか使用できません
署名アルゴリズムバージョン 値は固定でv2です

各インターフェースドキュメントでは、以下のような呼び出し方法が記載されています： GET /customers これには HTTP メソッドとインターフェース相対アドレスが含まれており、他の部分は具体的な状況に応じて置き換える必要があります。

パラメータ

インターフェースドキュメントでは、以下の3種類のパラメータタイプが登場する場合があります：

作成・変更系のインターフェースを呼び出す際は、リクエストデータを JSON 形式で UTF-8 テキストに変換し、エンコードされた文字列を Request Body パラメータとして対応するインターフェースに渡す必要があります。 同時に、リクエストヘッダーの Content-Type フィールドを application/json に設定してください。

返却結果

Udesk オープンインターフェース（v2）の返却データも、JSON形式でエンコードされたUTF-8文字列です。

codeエラーコードと説明

codeエラーコード説明を参照してください。

認証方法

ルール説明

すべてのインターフェース呼び出しには署名パラメータ sign が必要です。sign 値が有効な場合のみリクエストが受理されます。

sign の計算方法は以下の通りです：

sign=SHA256(email&open_api_token&timestamp&nonce&sign_version)

注意: 若使用SHA256鉴权失败,请使用SHA1

各パラメータ：

例

以下のインターフェースを呼び出すと仮定します：

https://demo.udesk.cn/open_api_v1/customers

認証に必要なデータは以下の通りです：

名称 データ
管理者email admin@udesk.cn
API Token 233df89e-b4a2-42e0-89af-f295b1078686
timestamp 1494474404
nonce 2d931510-d99f-494a-8c67-87feb05e1594
sign_version v2

signの計算

sha256("admin@udesk.cn&233df89e-b4a2-42e0-89af-f295b1078686&1494474404&2d931510-d99f-494a-8c67-87feb05e1594&v2")
#=> 6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52

注意: 若使用sha256鉴权失败,请使用sha1

最終的なリクエストURL：

https://demo.udesk.cn/open_api_v1/customers?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

認証失敗時の返却データ

属性名 値 説明 備考
code 2059 open api署名が不正です 認証未通過(認証パラメータエラー)

認証トークン取得インターフェース

このインターフェースは、認証に必要なトークンを取得するために使用されます。

リクエストメソッド

POST /log_in

リクエストパラメータ（Request Body）

パラメータ名 必須 説明
email はい スーパー管理者メールアドレス
password はい スーパー管理者パスワード

レスポンスデータ

属性名 型 説明
code 整数 リターンコード: 1000 は成功を表します
open_api_auth_token 文字列 API 認証トークン

例

curl https://demo.udesk.cn/open_api_v1/log_in \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "email": "admin@udesk.cn",
    "password": "password"
}'

レスポンス

{
    "code": 1000,
    "open_api_auth_token": "233df89e-b4a2-42e0-89af-f295b1078686"
}

通知コールバックアドレス設定インターフェース

顧客一括インポートインターフェースの実行終了後、呼び出し元に実行結果を通知するために使用されます。 認証：認証方法を参照してください。

注：このアドレスに通知されるデータ構造は以下を参照してください。

リクエストメソッド

POST /set_notice_url

リクエストパラメータ（Request Body）

パラメータ名 型 必須 説明
notice_url オブジェクト はい 通知アドレス

notice_url

パラメータ名 型 必須 説明
organization 文字列 はい インポート会社通知アドレス
customer 文字列 はい インポート顧客通知アドレス
batch_create_ticket 文字列 いいえ チケット一括作成通知アドレス

注：1つのパラメータのみを入力した場合、もう1つのパラメータはデフォルトで同じ通知アドレスに設定されます。

レスポンスデータ

パラメータ名 型 説明
code 整数 リターンコード：1000 は成功を表します
notice_url オブジェクト 通知アドレス、構造はパラメータと同じです
### サンプル 
curl https://demo.udesk.cn/open_api_v1/set_notice_url?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "notice_url": {
        "organization": "https://www.demo.com/import/organizations/finish",
        "customer": "https://www.demo.com/import/customers/finish"
    }
}'

レスポンス

{
    "code": 1000,
    "notice_url": {
        "organization": "https://www.demo.com/import/organizations/finish",
        "customer": "https://www.demo.com/import/customers/finish"
    }
}

顧客インポート後の通知データ

顧客の一括インポート後、JSONデータが本インターフェースで設定された通知コールバックURLに送信されます。パラメータの説明は以下の通りです：

パラメータ名 タイプ 説明
errors 配列 エラーデータの情報。詳細は以下を参照
success_count 文字列 インポート成功データの数
failed_count 文字列 インポート失敗データの数

errorsデータ構造

パラメータ名 説明
"0","1",... インポート顧客配列内の配列インデックス
"Mysql2::Error:...","Mysql2::Error:...",... 現在の顧客データインポートエラーの原因

注：errorsデータ内の配列インデックスとエラーメッセージはすべてカンマで区切られています。詳細はサンプルを参照してください。

サンプル：

{
    "errors"=>
    [
        "0", "Mysql2::Error: Duplicate entry '1056_2@qq.com-28480' for key 'index_customers_on_email_and_company_id': UPDATE `customers` SET `customers`.`email` = '1056_2@qq.com' WHERE `customers`.`id` = 1492034492",
        "1", "Mysql2::Error: Duplicate entry '1056_3@qq.com-28480' for key 'index_customers_on_email_and_company_id': UPDATE `customers` SET `customers`.`email` = '1056_3@qq.com' WHERE `customers`.`id` = 1492034502"
    ],
        "success_count"=>"0",
        "failed_count"=>"2"
 }

チケット一括作成後の通知データ

チケットを一括作成した後、JSONデータが本インターフェースに設定された通知コールバックURLに送信されます。パラメータの説明は以下の通りです：

パラメータ名 タイプ 説明
code 数値 リクエストステータス。チケットインターフェースのcodeコード説明を参照
data オブジェクト データ結果
success_count 数値 成功数
success_unique_ids 配列 成功した識別子の配列
failed_count 数値 失敗数
failed_unique_ids 配列 失敗した識別子の配列
result 配列 データインポートステータス
message 文字列 成功または失敗の説明
ticket_id 数値 チケットID
unique_id 文字列 データ作成時に渡された識別子

例：

{
    "code": 1000,
    "data": {
        "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
        "result": [
            {
                "code": 1000,
                "message": "チケット作成成功",
                "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
                "ticket_id": 79211,
                "unique_id": "データ識別子1"
            },
            {
                "code": 1000,
                "message": "チケット作成成功",
                "trace_id": "8ddade3a3c2a081d275f16002a19bd8d",
                "ticket_id": 79212,
                "unique_id": "データ識別子2"
            }
        ],
        "success_count": 2,
        "failed_count": 0,
        "success_unique_ids": [
            "データ識別子1",
            "データ識別子2"
        ],
        "failed_unique_ids": []
    }
}

共通データ

ページネーション情報

リスト取得などのインターフェースでは、通常、返されるデータにページネーション情報（meta）が含まれます。その内容は以下の通りです：

属性名 タイプ 説明
current_page 整数 現在のページ番号
total_pages 整数 総ページ数
total_count 整数 データ総数

コードエラーコード説明

エラーコード message情報 exception:message情報 説明
2002 サブドメインが無効です なし ドメイン入力エラー
2005 パラメータが不正です なし パスワード入力エラー
2015 管理者のみ操作可能です なし 認証に使用されたIDが管理者ではありません
該当リソースが見つかりません なし アカウント入力エラーまたは該当アカウントが存在しません
2058 お客様の会社はプロフェッショナル版ではありません なし 会社が有料プランに加入していません
2059 open api署名が不正です なし 認証パラメータエラー
20621 タイムスタンプの形式が不正です messageと同じ 必須パラメータ{timestamp}が未入力または形式エラー
20622 タイムスタンプの誤差は5分を超えることはできません messageと同じ パラメータ{timestamp}と現在時刻の差が5分を超えています
20623 リクエストは一度のみ有効です、15分以内にnonce値は重複できません messageと同じ 認証パラメータ{nonce}が15分以内に既に使用されています
20624 open api nonceが空です messageと同じ 認証パラメータ{nonce}が未入力または空です
2000 不明なエラー param is missing or the value is empty: notice_url notice_urlパラメータが空です notice_urlパラメータは空にできません