顧客管理API概要

はじめに#

顧客管理サービスが提供するAPIを利用するためには、API認証が発行するトークンが必要です。
詳しくはこちらをご参照ください。

接続情報#

Host#

business-support-k5.jp-east-1.paas.cloud.global.fujitsu.com

各APIはHTTPSで提供します。

URL例#

https://business-support-k5.jp-east-1.paas.cloud.global.fujitsu.com/API/v2/api/customers

API一覧#

No	API名	Method	URI
1	顧客を登録する	POST	/API/v2/api/customers
2	顧客を変更する	PUT	/API/v2/api/customers/{customer_id}
3	顧客を削除する	DELETE	/API/v2/api/customers/{customer_id}
4	顧客を検索する	GET	/API/v2/api/customers
5	顧客の件数を取得する	GET	/API/v2/api/customerslistcount
6	全顧客数を取得する	GET	/API/v2/api/customerscount
7	グループを作成する	POST	/API/v2/api/group
8	グループを変更する	PUT	/API/v2/api/group/{group_id}
9	グループを削除する	DELETE	/API/v2/api/group/{group_id}
10	グループを検索する	GET	/API/v2/api/group
11	グループの件数を取得する	GET	/API/v2/api/grouplistcount
12	グループに紐づく顧客を追加する	POST	/API/v2/api/grouprelation
13	グループに紐づく顧客を削除する	DELETE	/API/v2/api/grouprelation

共通仕様#

No	各APIにおける共通の仕様についての説明
1	文字コードについて
2	null項目の返却
3	更新系APIでの未設定項目処理
4	「version_info」について
5	ページング指定方法
6	ソート項目
7	フリー項目定義
8	フリー項目１～フリー項目１０定義

1. 文字コードについて#

リクエストデータの文字コードはUTF-8を使用してください。
レスポンスデータの文字コードはUTF-8を使用しています。

2. null項目の返却#

API実行時、nullの項目は項目自体返却しません。

3. 更新系APIでの未設定項目処理#

各種更新系API実行時、未設定の項目はnullが設定されます。

4.「version_info」について#

「version_info」は排他制御に使用しています。事前に取得した変更前情報の「version_info」を設定してください。排他制御は「楽観的排他制御」です。

5. ページング指定方法#

APIにて取得可能な件数が多い場合、取得したい結果の件数を限定することが可能です。例えば、「開始位置」に「100」「終了位置」に「200」と指定することにより、検索結果の100件目から200件目のレコードが取得できます。また、検索結果の総件数を知りたい場合は件数検索を行うAPIを利用します。件数検索APIにて総件数を確認し、その後ページング指定の検索を行うことにより、一覧画面のページングが実現できます。

ページング指定が可能なAPIは以下です。

No	API名
1	顧客を検索する
2	グループを検索する

ページング時に設定するリクエストパラメータは以下です。

No	リクエストパラメータ
1	start_position　（開始位置）
2	end_position　（終了位置）

6. ソート項目#

検索APIにて、ソート項目として指定可能な項目名を「ソート項目名１」～「ソート項目名３」の値として定義し、それぞれに「ソート順１」～「ソート順３」を指定することで取得結果のソートが可能となります。ソート項目として指定可能な項目は以下の通りです。

No	API名	ソート項目名
1	顧客を検索する	entry_system_date
		entry_id
		update_system_date
		update_id
		customer_id
		status
		temporary_registration_date_and_time
		official_registration_date_and_time
		cancellation_date_and_time
		free_item1
		free_item2
		free_item3
		free_item4
		free_item5
		free_item6
		free_item7
		free_item8
		free_item9
		free_item10
2	グループを検索する	entry_system_date
		entry_id
		update_system_date
		update_id
		group_id
		group_name
		free_item1
		free_item2
		free_item3
		free_item4
		free_item5
		free_item6
		free_item7
		free_item8
		free_item9
		free_item10

7. フリー項目定義#

APIの仕様として既に準備されている項目以外にAPI利用者が任意の項目を「フリー項目」部分に定義し登録することが可能です。

フリー項目の設定または取得が可能なAPIは以下です。

No	API名
1	顧客を登録する
2	顧客を変更する
3	グループを作成する
4	グループを変更する

フリー項目の定義の仕方#

以下は、「顧客を登録する」の入力パラメータです。任意に定義可能な部分は「free_item」オブジェクトの中となります。オブジェクト内であれば、配列やオブジェクトを任意に定義することが可能です。ただし、「free_item」自体は必ずオブジェクトとして定義する必要があります。

「free_item」の定義例

{
    "entry_id":"O00000000000003",
    "customer_name1":"富士通",
    "customer_name2":"太郎",
    "nationality":"JPN",
    "gender":"01",
    "date_of_birth":"19800101",
    "apply_start_date":"20161001",
    "free_item":{　-- ここから
        "free1":"100",     |
        "free2":"テスト",  　　|- 項目名、項目数含め任意に定義可能です
        "free3":"ABC"      |
    },             -- ここまでがオブジェクトです
    "free_item1":"任意項目１",
    "free_item2":"任意項目２",
    "free_item3":"任意項目３"
}

「free_item」の誤った定義例「配列として定義」

{
    "entry_id":"O00000000000003",
    "customer_name1":"富士通",
    "customer_name2":"太郎",
    "nationality":"JPN",
    "gender":"01",
    "date_of_birth":"19800101",
    "apply_start_date":"20161001",
    "free_item":[  -- オブジェクトではなく、配列として定義するのはNGです
        {
        "free1":"100",
        "free2":"テスト",
        "free3":"ABC"
        },
    "free_item1":"任意項目１",
    "free_item2":"任意項目２",
    "free_item3":"任意項目３"
    ]
}

「free_item」の誤った定義例「単一の項目として定義」

{
    "entry_id":"O00000000000003",
    "customer_name1":"富士通",
    "customer_name2":"太郎",
    "nationality":"JPN",
    "gender":"01",
    "date_of_birth":"19800101",
    "apply_start_date":"20161001",
    "free_item":"テスト",  -- オブジェクトではなく、単一の項目として定義するのはNGです
    "free_item1":"任意項目１",
    "free_item2":"任意項目２",
    "free_item3":"任意項目３"
}

フリー項目の変更の仕方#

任意に定義されたフリー項目はAPIの内部では、１つの文字列として扱います。そのため、任意に定義されたフリー項目の一部の項目のみを変更することは行えません。

登録時のデータを以下とします。

{
    "free_item":{
        "free1":"100",
        "free2":"テスト",
        "free3":"ABC"
    }
}

変更を行いたい項目「free2」のみを変更したい場合は以下のように一部の項目ではなく、free_itemの全体の内容も定義する必要があります。

{
    "free_item":{
        "free1":"100",
        "free2":"富士通太郎",  -- 変更する項目
        "free3":"ABC"
    }
}

その他注意事項#

フリー項目の登録可能文字数は各APIに定義されています。カウントされる文字は項目の定義、設定値だけでなく、{}や"",:[]も対象です。
クレジットカード情報を登録する場合は、お客様責任で登録をお願いします。

8. フリー項目１～フリー項目１０定義#

API利用者が任意の設定値を「フリー項目１」～「フリー項目１０」部分に登録することが可能です。
また「フリー項目１」～「フリー項目１０」を指定した検索も可能です。

フリー項目１～フリー項目１０の設定または取得が可能なAPIは以下です。

No	API名
1	顧客を登録する
2	顧客を変更する
3	グループを作成する
4	グループを変更する

フリー項目１～フリー項目１０の登録の仕方#

以下は、「顧客を登録する」の入力パラメータです。任意に登録可能な部分は「free_item1」～「free_item10」の中です。

「free_item1」～「free_item10」の定義例

{
    "entry_id":"O00000000000003",
    "customer_name1":"富士通",
    "customer_name2":"太郎",
    "nationality":"JPN",
    "gender":"01",
    "date_of_birth":"19800101",
    "apply_start_date":"20161001",
    "free_item":{
        "free1":"100",
        "free2":"テスト",
        "free3":"ABC"
    },
    "free_item1":"任意項目１",  -- 「free_item」と異なりオブジェクトではなく、単一の項目として定義します
    "free_item2":"任意項目２",
    "free_item3":"任意項目３"
}

その他注意事項#

クレジットカード情報を登録する場合は、お客様責任で登録をお願いします。

リクエストヘッダー情報#

各API共通ヘッダー

Name	Type	Description
Access-Token	object	アクセストークン取得APIで取得したトークン
locale	object	ロケール情報の設定
Content-Type	object	application/json

エラー情報#

API実行エラーの際、レスポンスのボディーに返却されます。

Name		Type	Description
errorLevel		string	エラーレベルフレームワークから返却するメッセージ情報のエラーレベル
framework		object	フレームワークオブジェクト
	systemErrorCode	string	システムエラーコードフレームワークから返却するエラーコード
business		object	業務オブジェクト
	businessErrorInfo	string	業務エラー情報
	responseErrorCode	string	応答エラーコード APIから返却するエラーコード
	embeddedString	string	エラーメッセージ

Top