顧客リストの取得

このインターフェースは、複数の顧客情報を一度に取得するために使用されます。

リクエストメソッド

GET /api/v1/customers.json

リクエストパラメータ（Query String）

パラメータ名 必須 説明
page 否 ページ番号。1から開始。デフォルトは1です。
per_page 否 1ページあたりの件数。デフォルト20、最大100です。

レスポンスデータ

属性名 型 説明
status 整数型 実行結果コード。0は成功を表します。
message 文字列型 実行結果の説明。
size 整数型 今回返されたデータの件数。
total 整数型 データの総件数。
total_pages 整数型 総ページ数。
contents 配列 顧客リスト。各顧客の内容は顧客データ構造を参照してください。

例

curl https://demo.udesk.cn/api/v1/customers?page=1&per_page=10&sign=129da7df812jdfsa9912jfdadf81

レスポンス

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "contents": [
        {
            "id": 1,
            "email": "customer@sample.com",
            "nick_name": "テストユーザー",
            "telephone": "13000000001",
            "cellphone": "13000000001"
        }
    ]
}

顧客の検索または作成

このインターフェースは、IDまたはメールアドレスに基づいて顧客を検索するために使用されます。見つからない場合は、新しい顧客を作成して返します。

リクエストメソッド

GET /api/v1/customers/find_or_create_customer.json

リクエストパラメータ（Query String）

パラメータ名 必須 説明
id 否 顧客ID。emailが空の場合、idは必須です。
email 否 顧客のメールアドレス。idが空の場合、emailは必須です。

id と email の両方が提供された場合、検索順序は最初に id で検索し、見つからなければ次に email で検索します。それでも見つからない場合は顧客を作成します。

返却データ

属性名 タイプ 説明
status 整数 実行結果コード、0は成功を表す
message 文字列 実行結果の説明
customer オブジェクト 顧客情報、顧客データ構造を参照

例

curl https://demo.udesk.cn/api/v1/customers/find_or_create_customer?email=customer@sample.com&sign=129da7df812jdfsa9912jfdadf81

返却

{
    "status": 0,
    "message": "成功",
    "customer": {
        "id": 1,
        "email": "customer@sample.com",
        "nick_name": "テストユーザー",
        "telephone": "13000000001",
        "cellphone": "13000000001"
    }
}

顧客詳細情報の取得

このAPIは、指定されたIDの単一顧客情報を取得するために使用されます。

リクエストメソッド

GET /api/v1/customers/:id.json

リクエストパラメータ（URL中）

パラメータ名 必須 説明
id はい 顧客ID

返却データ

属性名 タイプ 説明
status 整数 実行結果コード、0は成功を表す
message 文字列 実行結果の説明
size 整数 今回返却されたデータ数（廃止）
total 整数 データ総数（廃止）
contents オブジェクト 顧客情報、顧客データ構造を参照

例

curl https://demo.udesk.cn/api/v1/customers/1?sign=129da7df812jdfsa9912jfdadf81

返却

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "contents": {
        "id": 1,
        "email": "customer@sample.com",
        "nick_name": "テストユーザー",
        "telephone": "13000000001",
        "cellphone": "13000000001"
    }
}

カスタマーカスタムフィールドリストの取得

このインターフェースは、すべてのカスタマーカスタムフィールド情報を一度に取得するために使用されます。

リクエストメソッド

GET /api/v2/user_fields.json

リクエストパラメータ

なし

レスポンスデータ

属性名 タイプ 説明
status 整数 実行結果コード、0は成功を表します
message 文字列 実行結果の説明
user_fields 配列 カスタムフィールドリスト、各要素の構造はカスタマーカスタムフィールドを参照してください

このインターフェースはカスケードフィールドをサポートしていません。カスケードフィールドの情報は取得できますが、その options の形式は正しくありません。

例

curl https://demo.udesk.cn/api/v2/user_fields?sign=129da7df812jdfsa9912jfdadf81

レスポンス

{
    "status": 0,
    "message": "success",
    "user_fields": [
        {
            "field_name": "TextField_9",
            "field_label": "単行テキストフィールド",
            "content_type": "text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_10",
            "field_label": "複数行テキストフィールド",
            "content_type": "area_text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_11",
            "field_label": "日付フィールド",
            "content_type": "date",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_12",
            "field_label": "時間フィールド",
            "content_type": "time",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_13",
            "field_label": "日時フィールド",
            "content_type": "datetime",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_14",
            "field_label": "リンクフィールド",
            "content_type": "link",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_15",
            "field_label": "正の整数フィールド",
            "content_type": "number",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_16",
            "field_label": "数値フィールド",
            "content_type": "numeric",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "SelectField_5",
            "field_label": "ドロップダウンリストフィールド",
            "content_type": "droplist",
            "comment": null,
            "options": [
                {"0": "ドロップダウンオプション1"},
                {"1": "ドロップダウンオプション2"},
                {"2": "ドロップダウンオプション3"}
            ],
            "permission": 2,
            "requirment": true
        },
        {
            "field_name": "SelectField_6",
            "field_label": "ラジオボタンフィールド",
            "content_type": "radio",
            "comment": null,
            "options": [
                {"0": "ラジオボタンオプション1"},
                {"1": "ラジオボタンオプション2"}
            ],
            "permission": 2,
            "requirment": true
        },
        {
            "field_name": "SelectField_6",
            "field_label": "チェックボックスフィールド",
            "content_type": "checkbox",
            "comment": null,
            "options": [
                {"0": "チェックボックスオプション1"},
                {"1": "チェックボックスオプション2"},
                {"2": "チェックボックスオプション3"},
                {"3": "チェックボックスオプション4"}
            ],
            "permission": 2,
            "requirment": false
        }
    ]
}

データ構造-顧客

属性名 タイプ 説明
id 整数型 一意の識別子
email 文字列 メールアドレス
nick_name 文字列 氏名
cellphone 文字列 最初の連絡先電話番号
telephone 文字列 連絡先電話番号（非推奨、内容はcellphoneと同じ）

データ構造-顧客カスタムフィールド

属性 タイプ 説明
field_name 文字列 識別名
field_label 文字列 名称
content_type 文字列 タイプ
comment 文字列 備考
options 配列 選択タイプのカスタムフィールドのオプション。以下の<選択タイプカスタムフィールドオプション構造>を参照
permission 整数型 顧客権限（非推奨）
requirement ブール型 必須項目かどうか（非推奨）

content_type の取り得る値

値 意味
text 1行テキスト
area_text 複数行テキスト
date 日付
time 時間
datetime 日時
link リンク
number 正の整数
numeric 数値
droplist ドロップダウンリスト
checkbox チェックボックス
radio ラジオボタン
chained_droplist カスケード
### permission の取り得る値
値 意味
0 顧客には非表示
1 顧客に表示されるが編集不可
2 顧客が編集可能
3 顧客必須入力

options の構造

ドロップダウンリスト、チェックボックス、ラジオボタンのoptionsの形式は[{"选项索引":"选项名称"}, ...]です。例えば、ラジオボタンの「性別」のoptionsは以下のようになります：

{
    "options": [
        {"0": "男性"},
        {"1": "女性"},
        {"2": "非公開"}
    ]
}

カスタムフィールドとその値の設定方法

カスタムフィールドはテキストタイプと選択タイプに分けられます。テキストタイプの値は特定の形式の文字列であり、選択タイプの値はそのオプションのインデックス値です。 以下に、顧客を例として、カスタムフィールドの設定方法を説明します。

以下のような顧客カスタムフィールドがあると仮定します：

[
    {
        "field_name": "TextField_1",
        "field_label": "単行テキストフィールド",
        "content_type": "text",
    },
    {
        "field_name": "TextField_2",
        "field_label": "複数行テキストフィールド",
        "content_type": "area_text",
    },
    {
        "field_name": "TextField_3",
        "field_label": "日付フィールド",
        "content_type": "date",
    },
    {
        "field_name": "TextField_4",
        "field_label": "時間フィールド",
        "content_type": "time",
    },
    {
        "field_name": "TextField_5",
        "field_label": "日時フィールド",
        "content_type": "datetime",
    },
    {
        "field_name": "TextField_6",
        "field_label": "リンクフィールド",
        "content_type": "link",
    },
    {
        "field_name": "TextField_7",
        "field_label": "正の整数フィールド",
        "content_type": "number",
    },
    {
        "field_name": "TextField_8",
        "field_label": "数値フィールド",
        "content_type": "numeric",
    },
    {
        "field_name": "SelectField_1",
        "field_label": "ドロップダウンリストフィールド",
        "content_type": "droplist",
        "options": [
            {"0": "ドロップダウンオプション1"},
            {"1": "ドロップダウンオプション2"},
            {"2": "ドロップダウンオプション3"}
        ],
    },
    {
        "field_name": "SelectField_2",
        "field_label": "ラジオボタンフィールド",
        "content_type": "radio",
        "options": [
            {"0": "ラジオボタンオプション1"},
            {"1": "ラジオボタンオプション2"}
        ],
    },
    {
        "field_name": "SelectField_3",
        "field_label": "チェックボックスフィールド",
        "content_type": "checkbox",
        "options": [
            {"0": "チェックボックスオプション1"},
            {"1": "チェックボックスオプション2"},
            {"2": "チェックボックスオプション3"},
            {"3": "チェックボックスオプション4"}
        ],
    }
]

ある顧客において、その表現は以下のようになります：

{
    "customer": {
        "custom_fields": {
            "TextField_1": "通常のテキスト内容",                    // 通常テキスト
            "TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2",  // 複数行テキスト
            "TextField_3": "2016-08-11",                      // 日付
            "TextField_4": "14:44:36",                        // 時間
            "TextField_5": "2017-05-03 14:44",                // 日時
            "TextField_6": "https://www.sample.com",           // リンク
            "TextField_7": "13",                              // 正の整数
            "TextField_8": "13.33",                           // 数値
            "SelectField_1": "0",                             // ドロップダウンリスト、ドロップダウンオプション1
            "SelectField_2": "0",                             // ラジオボタン、ラジオボタンオプション1
            "SelectField_3": "0,3",                           // チェックボックス、チェックボックスオプション1、チェックボックスオプション4
        }
    }
}

statusエラーコード説明

エラーコード message情報 説明 備考
1001 指定されたidが存在しません 指定された{id}または{email}がありません ”顧客の検索または作成“インターフェースに使用
指定されたidが存在しません URL内のパラメータ{id}が誤っており、値に一致しませんでした ”顧客詳細情報の取得“インターフェースに使用