呼び出し形式
HTTP メソッド
Udesk オープンインターフェース（v1）では、以下の HTTP メソッドが使用される場合があります：
- GET：データ取得インターフェースに使用
- POST：作成インターフェースに使用
- PUT：変更インターフェースに使用
- DELETE：削除インターフェースに使用
各インターフェースのドキュメントには使用する HTTP メソッドが明記されています。インターフェースを呼び出す際は、具体的なインターフェースドキュメントに従ってください。
呼び出しアドレス
Udesk オープンインターフェース（v1）の呼び出しアドレスは以下の形式に従います：
https://[サブドメイン].udesk.cn/api/[バージョン]/[インターフェース相対アドレス]?[クエリストリング]&sign=[署名]
角括弧で囲まれた部分の意味は以下の通りです：
| 変数 | 説明 |
|---|---|
| サブドメイン | Udesk カスタマーサポートシステムをご利用の際に割り当てられたサブドメイン |
| バージョン | インターフェースのバージョン。Udesk オープンインターフェース（v1）は小規模なアップグレードを経ているため、この値は v1 または v2 のいずれかで、それぞれバージョン1.1とバージョン1.2を表します |
| インターフェース相対アドレス | インターフェースの相対アドレス |
| クエリストリング | アドレスのパラメータ部分。この部分は署名計算に参加します。詳細は認証方法を参照してください |
| 署名 | 認証署名。特に明記されていない限り、インターフェース呼び出しのたびに必要です。計算方法は[認証][]を参照してください |
各インターフェースドキュメントには、以下のような呼び出し方法が記載されています：
GET /api/v1/ticketsこれには HTTP メソッド、インターフェースバージョン、およびインターフェース相対アドレスが含まれており、その他の部分は具体的な状況に応じて置き換える必要があります。
パラメータ
インターフェースドキュメントでは、以下の3種類のパラメータタイプが登場する場合があります：
- URL 内：呼び出しアドレスに埋め込まれたパラメータ。例：
/tickets/:idの:id。 - クエリストリング：呼び出しアドレスのクエリストリング部分のパラメータ。例：
/tickets?page=2のpage。 - リクエストボディ：リクエストボディ内の内容。
作成、変更系のインターフェースを呼び出す際は、リクエストデータを JSON 形式で UTF-8 テキストに変換し、エンコードされた文字列をリクエストボディタイプのパラメータとして対応するインターフェースに渡す必要があります。 同時に、リクエストヘッダーの Content-Type フィールドを application/json に設定してください。（コールセンターオペレーター発信インターフェースおよび通話記録取得インターフェースはこの設定は不要です）
返却結果
Udesk オープンインターフェース（v1）の返却データも、JSON 形式でエンコードされた UTF-8 文字列です。
認証方法
すべてのAPI呼び出しには署名パラメータ sign が必要です。sign 値が有効な場合のみリクエストが受理されます。
sign の計算方法は以下の通りです：
sign=MD5(QueryString + "&" + Secret)
ここで：
QueryStringはURL内のパラメータ（signパラメータを除く）で、"&" で区切られた "key=value" 形式の文字列です。パラメータの順序は呼び出しURL内での順序に従います。Secretはシングルサインオン共有シークレットキーです。ウェブサイト管理画面の【管理センター】->【管理】->【シングルサインオン】->【共有シークレット】で確認できます。
QueryStringが空の場合、"sign=MD5(Secret)" となります。このため、V1バージョンのAPIにはセキュリティリスクがあるため、可能な限り新しいバージョンのAPIの使用を推奨します。 値がないパラメータがある場合は、"key=key" の形式で組み立てる必要があります。詳細は例を参照してください。
例
共有シークレットキーが以下の場合：
99d80d18b0b9a994a8d0283e830e5099
元のリクエストURLが以下の場合：
https://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value
sign(32桁小文字)を計算：
md5("per_page=20&page=1&no_value=no_value&99d80d18b0b9a994a8d0283e830e5099")
#=> c029b77b0da250875d89d52c7ab582a0
最終的なリクエストURL：
https://demo.udesk.cn/api/v1/tickets?per_page=20&page=1&no_value&sign=c029b77b0da250875d89d52c7ab582a0