契約管理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/basiccontract
API一覧#
| No | API名 | Method | URI |
|---|---|---|---|
| 1 | 基本契約を編集する | POST | /API/v2/api/basiccontract |
| 2 | 基本契約を検索する | GET | /API/v2/api/basiccontract |
| 3 | 基本契約の件数を取得する | GET | /API/v2/api/basiccontractlistcount |
| 4 | サービス契約を編集する | POST | /API/v2/api/servicecontracts |
| 5 | サービス契約を検索する | GET | /API/v2/api/servicecontracts |
| 6 | サービス契約の件数を取得する | GET | /API/v2/api/servicecontractslistcount |
| 7 | 割引契約を編集する | POST | /API/v2/api/discountcontracts |
| 8 | 割引契約を検索する | GET | /API/v2/api/discountcontracts |
| 9 | 割引契約の件数を取得する | GET | /API/v2/api/discountcontractslistcount |
| 10 | 全サービス契約・割引契約数を取得する | GET | /API/v2/api/servicecontractscount |
| 11 | サービスマスタを編集する | POST | /API/v2/api/services |
| 12 | サービスマスタを検索する | GET | /API/v2/api/services |
| 13 | サービスマスタの件数を取得する | GET | /API/v2/api/serviceslistcount |
| 14 | カテゴリマスタを編集する | POST | /API/v2/api/category |
| 15 | カテゴリマスタを検索する | GET | /API/v2/api/category |
| 16 | カテゴリマスタの件数を取得する | GET | /API/v2/api/categorycount |
| 17 | カテゴリ所属マスタを編集する | POST | /API/v2/api/categorybelonging |
| 18 | カテゴリ所属マスタを検索する | GET | /API/v2/api/categorybelonging |
| 19 | カテゴリ所属マスタの件数を取得する | GET | /API/v2/api/categorybelongingcount |
共通仕様#
| No | 各APIにおける共通の仕様についての説明 |
|---|---|
| 1 | 文字コードについて |
| 2 | null項目の返却 |
| 3 | 更新系APIでの未設定項目処理 |
| 4 | 「version_info」について |
| 5 | ページング指定方法 |
| 6 | ソート項目 |
| 7 | フリー項目定義 |
| 8 | フリー項目１～フリー項目１０定義 |
| 9 | 管理番号 |
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 | サービス契約を検索する |
| 3 | 割引契約を検索する |
| 4 | サービスマスタを検索する |
| 5 | カテゴリマスタを検索する |
| 6 | カテゴリ所属マスタを検索する |
ページング時に設定するリクエストパラメータは以下です。
| No | リクエストパラメータ |
|---|---|
| 1 | start_position （開始位置） |
| 2 | end_position （終了位置） |
6. ソート項目#
検索APIにて、ソート項目として指定可能な項目名を「ソート項目名１」～「ソート項目名３」の値として定義し、それぞれに「ソート順１」～「ソート順３」を指定することで取得結果のソートが可能となります。 ソート項目として指定可能な項目は以下の通りです。
| No | API名 | ソート項目名 |
|---|---|---|
1 |
entry_system_date |
|
entry_id |
||
update_system_date |
||
update_id |
||
bill_to_id |
||
administration_number |
||
apply_start_date |
||
apply_end_date |
||
customer_id |
||
basic_contract_id |
||
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 |
||
service_contract_id |
||
service_code |
||
service_application_date |
||
service_end_application_date |
||
apply_start_date |
||
apply_end_date |
||
charging_start_date |
||
charging_end_date |
||
customer_id |
||
basic_contract_id |
||
bill_to_id |
||
cancel_date |
||
administration_number |
||
status |
||
order_number |
||
contract_number |
||
number_of_contracts |
||
free_item1 |
||
free_item2 |
||
free_item3 |
||
free_item4 |
||
free_item5 |
||
free_item6 |
||
free_item7 |
||
free_item8 |
||
free_item9 |
||
free_item10 |
||
3 |
entry_system_date |
|
entry_id |
||
update_system_date |
||
update_id |
||
discount_contract_id |
||
service_code |
||
service_application_date |
||
service_end_application_date |
||
apply_start_month |
||
apply_end_month |
||
customer_id |
||
basic_contract_id |
||
administration_number |
||
status |
||
order_number |
||
contract_number |
||
service_contract_id |
||
free_item1 |
||
free_item2 |
||
free_item3 |
||
free_item4 |
||
free_item5 |
||
free_item6 |
||
free_item7 |
||
free_item8 |
||
free_item9 |
||
free_item10 |
||
4 |
entry_system_date |
|
entry_id |
||
update_system_date |
||
update_id |
||
service_code |
||
service_name |
||
service_division |
||
apply_start_date |
||
apply_end_date |
||
reception_start_date |
||
reception_end_date |
||
release_start_date |
||
release_end_date |
||
basic_product_id |
||
administration_number |
||
product_type |
||
category_id |
||
status |
||
display_priority |
||
free_item1 |
||
free_item2 |
||
free_item3 |
||
free_item4 |
||
free_item5 |
||
free_item6 |
||
free_item7 |
||
free_item8 |
||
free_item9 |
||
free_item10 |
||
5 |
entry_system_date |
|
entry_id |
||
update_system_date |
||
update_id |
||
category_id |
||
category_name |
||
apply_start_date |
||
apply_end_date |
||
display_flag |
||
service_code |
||
upper_hierarchy_category_id |
||
display_priority |
||
free_item1 |
||
free_item2 |
||
free_item3 |
||
free_item4 |
||
free_item5 |
||
free_item6 |
||
free_item7 |
||
free_item8 |
||
free_item9 |
||
free_item10 |
||
6 |
entry_system_date |
|
entry_id |
||
update_system_date |
||
update_id |
||
category_belonging_id |
||
category_id |
||
service_code |
||
apply_start_date |
||
apply_end_date |
||
display_priority |
||
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 | サービスマスタを編集する |
| 5 | カテゴリマスタを編集する |
| 6 | カテゴリ所属マスタを編集する |
フリー項目の定義の仕方#
以下は、「基本契約を編集する」の入力パラメータです。 任意に定義可能な部分は「free_item」オブジェクトの中となります。 オブジェクト内であれば、配列やオブジェクトを任意に定義することが可能です。ただし、「free_item」自体は必ずオブジェクトとして定義する必要があります。
「free_item」の定義例
{
"entry_id": "O00000000000001",
"administration_number": "1",
"group_id": "12345678",
"classification_of_contract": "1",
"customer_id": "123456789012345",
"apply_start_date": "20170912",
"apply_end_date": "20200912",
"free_item": { -- ここから
"free1":"100",
"free2":"テスト", |- 項目名、項目数含め任意に定義可能です
"free3":"ABC"
}, -- ここまでがオブジェクト
"free_item1": "任意項目１",
"free_item2": "任意項目２",
"free_item3": "任意項目３"
}
「free_item」の誤った定義例「配列として定義」
{
"entry_id": "O00000000000001",
"administration_number": "1",
"group_id": "12345678",
"classification_of_contract": "1",
"customer_id": "123456789012345",
"apply_start_date": "20170912",
"apply_end_date": "20200912",
"payment_classification": "1",
"free_item":[ -- オブジェクトではなく、配列として定義するのはNGです
{
"free1":"100",
"free2":"テスト",
"free3":"ABC"
}
],
"free_item1": "任意項目１",
"free_item2": "任意項目２",
"free_item3": "任意項目３"
}
「free_item」の誤った定義例「単一の項目として定義」
{
"entry_id": "O00000000000001",
"administration_number": "1",
"group_id": "12345678",
"classification_of_contract": "1",
"customer_id": "123456789012345",
"apply_start_date": "20170912",
"apply_end_date": "20200912",
"payment_classification": "1",
"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 | サービスマスタを編集する |
| 5 | カテゴリマスタを編集する |
| 6 | カテゴリ所属マスタを編集する |
フリー項目１～フリー項目１０の登録の仕方#
以下は、「基本契約を編集する」の入力パラメータです。 任意に登録可能な部分は「free_item1」～「free_item10」の中です。
「free_item1」～「free_item10」の定義例
{
"entry_id": "O00000000000001",
"administration_number": "1",
"group_id": "12345678",
"classification_of_contract": "1",
"customer_id": "123456789012345",
"apply_start_date": "20170912",
"apply_end_date": "20200912",
"free_item": {
"free1":"100",
"free2":"テスト",
"free3":"ABC"
},
"free_item1": "任意項目１", -- 「free_item」と異なりオブジェクトではなく、単一の項目として定義します
"free_item2": "任意項目２",
"free_item3": "任意項目３"
}
その他注意事項#
クレジットカード情報を登録する場合は、お客様責任で登録をお願いします。
9. 管理番号#
「基本契約を編集する」、「サービス契約を編集する」、「割引契約を編集する」、「サービスマスタを編集する」APIにて、登録時に採番される一意のＩＤに対してそれぞれ異なる「管理番号」を登録できます。 たとえば、管理番号ごとに「申請」、「承認」など異なるステータスの保持や、登録内容の変更を行うごとに異なる管理番号を付与することで変更履歴の保持ができます。
- 登録は必須です。値は「1」から「999」の間で任意に付与できます。
- 一意のＩＤに対して同じ「管理番号」の値を登録することはできません。
- 登録済みの「管理番号」の値の変更はできません。
イメージ例：異なるステータスの保持
管理番号が登録可能なAPIと、各APIで採番される一意のＩＤは以下の通りです。
| No | API名 | 採番されるＩＤ |
|---|---|---|
| 1 | 基本契約を編集する | 請求先ＩＤ、基本契約ＩＤ |
| 2 | サービス契約を編集する | サービス契約ＩＤ |
| 3 | 割引契約を編集する | 割引契約ＩＤ |
| 4 | サービスマスタを編集する | サービスコード |
リクエストヘッダー情報#
各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 |
応答エラーコード |
|
embeddedString |
string |
エラーメッセージ |
|
契約管理上の制限事項#
契約管理の各APIを利用する上での制限事項です。
特別記載のない場合、項目はすべてサービス契約の項目を指します。
| 業務 | 制限内容 |
|---|---|
| 登録 | 適用開始年月が、業務日付と比較して過去年月とならないこと。 |
| 課金開始年月が、業務日付と比較して過去年月とならないこと。 | |
| 適用開始年月日が、課金開始年月日以前であること。 | |
| 課金終了年月日が、適用終了年月日以前であること。 | |
| サービスマスタが適用開始年月日の期間で有効であること。 | |
| 料金プランマスタが適用開始年月日の期間で有効であること。 | |
| 基本契約が適用開始年月日の期間で有効であること。 | |
| 変更 | 適用中のサービス契約に対して、適用開始年月日を変更することはできない。 |
| 適用前に適用終了年月日を設定する場合、サービス契約のキャンセルとして扱われる。 | |
| 適用開始年月が、業務日付と比較して過去年月とならないこと。 | |
| 課金開始年月が、業務日付と比較して過去年月とならないこと。 | |
| 適用開始年月日が、課金開始年月日以前であること。 | |
| 課金終了年月日が、適用終了年月日以前であること。 | |
| サービスマスタが適用開始年月日の期間で有効であること。 | |
| 料金プランマスタが適用開始年月日の期間で有効であること。 | |
| 基本契約が適用開始年月日の期間で有効であること。 |