定期券払い戻し計算
/refund_commuter_pass [GET]
基本情報
概要
指定した鉄道区間の定期券払い戻し金額を計算し出力します。
対象となる定期券は通勤定期券の運賃となります。
また、往復定期券が対象です。片道定期券は対象外ですのでご注意ください。
鉄道とバスの乗継定期券の払い戻しは未対応です。
URL
https://{HOST}/{CID}/v1/refund_commuter_pass
※APIマーケットでは提供しておりません
出力形式
- JSON
対応言語
- ja
パラメータ
| パラメータ名 | 必須 | 概要 | 型名 | デフォルト値 | 上下限/選択値 | 備考 |
|---|---|---|---|---|---|---|
| section_info | ✔ | 利用路線IDと区間情報 | 定期券区間のJSON表現(配列) | 最大10区間まで | 詳細はこちらをご覧ください | |
| validity_months | ✔ | 定期券有効期間(1/3/6ヶ月) | 数値 | - 1 - 3 - 6 |
||
| purchase_date | ✔ | 定期券購入日 | 文字列 yyyy-mm-dd |
|||
| start_date | ✔ | 定期券利用開始日 | 文字列 yyyy-mm-dd |
|||
| refund_date | ✔ | 定期券払い戻し日 | 文字列 yyyy-mm-dd |
|||
| company | ✔ | 定期券を発行する鉄道会社ID | 文字列 | |||
| fare | 普通運賃(片道) | 数値 | 最小値：1 最大値：99999 |
詳細はこちらをご覧ください | ||
| commuter_pass_amount | 定期券購入額 | 数値 | 最小値：1 最大値：999999 |
詳細はこちらをご覧ください |
companyの指定に関して
定期券区間に含まれない鉄道会社をcompanyに指定することはできません。
【定期券区間が複数の鉄道会社をまたぐ（大崎〜渋谷〜表参道）場合】
companyに指定できる鉄道会社は、JR東日本（大崎〜渋谷）と東京メトロ（渋谷〜表参道）となります。
その他の鉄道会社をcompanyに指定した場合はエラーが返却されます。
リクエスト例はこちらをご覧ください。
fare, commuter_pass_amountの指定に関して
パラメータ「company」で指定された会社がバス会社の場合のみ、fare, commuter_pass_amountパラメータを指定することができます。
指定された鉄道区間にかかる普通運賃(片道)と定期券購入額を明示的に指定することができます。
主にはsection_infoパラメータで指定されている利用路線と区間情報を元に計算ができない場合にご利用ください。
定期区間の JSON 表現
| プロパティ名 | 必須 | 概要 | 型名 | デフォルト値 | 備考 |
|---|---|---|---|---|---|
| start | ✔ | 定期区間の出発駅ID | 文字列 | ||
| goal | ✔ | 定期区間の到着駅ID | 文字列 | ||
| link | ✔ | 路線ID | 文字列 | ||
| direction | ✔ | 進行方向 | 文字列 | up：上り down：下り |
section_infoに指定する区間について
往路と復路 どちらかの区間を指定することで、往復定期券の料金や払い戻し額を返却します。
定期区間のJSON表現で使用する出発/到着駅ID、路線ID、進行方向に関しては、/route_transitで得られるレスポンスの路線情報（Linkオブジェクト）をご参照ください。
対応する鉄道会社について
対応する鉄道会社の一覧はこちらからご確認いただけます。
パラメータ構成例
- 6ヶ月定期券(区間：新橋〜東京〜船橋)の払い戻し金額を検索
（購入日：2022年3月30日、利用開始日：2022年4月1日、払い戻し日：2022年6月10日)
/refund_commuter_pass?section_info=[{"start":"00004212", "goal":"00006668","link":"00000123","direction":"up"},{"start":"00006668", "goal":"00005286","link":"00000168","direction":"down"}]&validity_months=6&purchase_date=2022-03-30&start_date=2022-04-01&refund_date=2022-06-10&company=00000004
- 6ヶ月定期券(区間：大崎〜渋谷〜表参道)の払い戻し金額を検索
（購入日：2022年3月30日、利用開始日：2022年4月1日、払い戻し日：2022年6月10日)
・company=00000004を指定
/refund_commuter_pass?section_info=[{"start":"00005613","goal":"00003544","link":"00000141","direction":"up"},{"start":"00003544","goal":"00007820","link":"00000768","direction":"up"}]&validity_months=6&purchase_date=2022-03-30&start_date=2022-04-01&refund_date=2022-06-10&company=00000004
・company=00000113を指定
/refund_commuter_pass?section_info=[{"start":"00005613","goal":"00003544","link":"00000141","direction":"up"},{"start":"00003544","goal":"00007820","link":"00000768","direction":"up"}]&validity_months=6&purchase_date=2022-03-30&start_date=2022-04-01&refund_date=2022-06-10&company=00000113
JSON 表現は URL エンコードをした上でリクエストしてください
レスポンス
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 定期券払い戻し情報 | items | RefundInfoオブジェクト | ○ |
SectionInfoオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 定期区間の開始ノード | start | Nodeオブジェクト | ||
| 定期区間の終了ノード | goal | Nodeオブジェクト | ||
| 定期券区間 | sections | Sectionオブジェクト | ○ | |
| 定期券購入日 | purchase_date | 文字列 | ||
| 定期券有効期間 | validity_months | 数値 | ||
| 定期券有効開始/終了日 | validity_period | ValidityPeriodオブジェクト | ||
| 定期券料金 | commuter_pass_price | 数値 | ||
| 定期券払い戻し日 | refund_date | 文字列 | ||
| 定期券払い戻し代金 | refund_amount | 数値 | ||
| 払い戻し額の妥当性 | is_certain | 真偽値 | 鉄道/バス会社が公開している計算ルール及び手数料に基づいている場合は"true"を出力します | |
| 手数料 | charge | 数値 |
Nodeオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| ノードID | node_id | 文字列 | ||
| ノード名称 | node_name | 文字列 |
Section(type=point)オブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| タイプ | type | 文字列 | ||
| ノードID | node_id | 文字列 | ||
| ノード名称 | node_name | 文字列 |
Section(type=move)オブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| タイプ | type | 文字列 | ||
| 路線ID | line_id | 文字列 | ||
| 路線名称 | line_name | 文字列 |
ValidityPeriodオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 定期券の有効開始日 | start_date | 文字列 | ||
| 定期券の有効終了日 | end_date | 文字列 |
レスポンス例
{
"items": [
{
"start": {
"node_id": "00004212",
"node_name": "新橋"
},
"goal": {
"node_id": "00005286",
"node_name": "船橋"
},
"sections": [
{
"type": "point",
"node_id": "00004212",
"node_name": "新橋"
},
{
"type": "move",
"line_id": "00000123",
"line_name": "ＪＲ横須賀線"
},
{
"type": "point",
"node_id": "00006668",
"node_name": "東京"
},
{
"type": "move",
"line_id": "00000168",
"line_name": "ＪＲ総武本線（東京-銚子）"
},
{
"type": "point",
"node_id": "00005286",
"node_name": "船橋"
}
],
"purchase_date": "2022-03-30",
"validity_months": 6,
"validity_period": {
"start_date": "2022-04-01",
"end_date": "2022-09-30"
},
"commuter_pass_price": 67980,
"refund_date": "2022-06-01",
"refund_amount": 28120,
"is_certain": true,
"charge": 220
}
]
}
・払い戻し不可：払い戻し日が定期券の有効終了日と同じ日を指定した場合など（ステータスコード：200）
{
"message": "Refunds are not possible : Refund amount is 0 yen"
}
・払い戻し不可：払い戻し日が定期券の有効終了日を過ぎている場合
{
"status_code": 400,
"message": "Refunds are not possible : Refund date has expired"
}
エラー情報
エラーハンドリングについて
エラーメッセージは追加/変更/削除されることがあります。
エラーハンドリングされる場合はHTTPステータスコードをもとにご対応ください。
共通エラーについてはこちらをご参照ください。
| HTTPステータス | エラーメッセージ | 発生理由 |
|---|---|---|
| 405 | "This http method is invalid : POST"（等） | 許可されていないHTTPメソッドでアクセスされた場合に発生します。 |
| 400 | parameter error: section_info: "required field" | 必須パラメータである section_info が指定されていない場合に発生します。 |
| 400 | parameter error: section_info: "not json format : {value}" | section_info に空文字を指定した場合や、JSON 形式ではない値を指定した場合に発生します。 |
| 400 | "section_info must be in array format" | section_info に配列ではない JSON を指定した場合に発生します。 |
| 400 | "list size is too small" | section_info に空の配列を指定した場合に発生します。 |
| 400 | "list size is too large" | section_info に11区間以上を指定した場合に発生します。 |
| 400 | parameter error: start: "required field" | section_info の要素に start が指定されていない場合に発生します。 |
| 400 | parameter error: start: "an invalid code: {value}" | section_info の要素の start に不正な駅IDを指定した場合に発生します。 |
| 400 | parameter error: goal: "required field" | section_info の要素に goal が指定されていない場合に発生します。 |
| 400 | parameter error: goal: "an invalid code: {value}" | section_info の要素の goal に不正な駅IDを指定した場合に発生します。 |
| 400 | parameter error: link: "required field" | section_info の要素に link が指定されていない場合に発生します。 |
| 400 | parameter error: link: "an invalid code: {value}" | section_info の要素の link に不正な路線IDを指定した場合に発生します。 |
| 400 | parameter error: direction: "required field" | section_info の要素に direction が指定されていない場合に発生します。 |
| 400 | parameter error: direction: "unallowed value {value}" | section_info の要素の direction に up, down 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: validity_months: "required field" | 必須パラメータである validity_months が指定されていない場合に発生します。 |
| 400 | parameter error: validity_months: "unallowed value {value}" | validity_months に 1, 3, 6 以外の値を指定した場合に発生します。 |
| 400 | parameter error: validity_months: "unallowed value {value} field 'validity_months' cannot be coerced: invalid literal for int() with base 10: '{value}'" | validity_months に空文字を指定した場合や、数値に変換できない値を指定した場合に発生します。 |
| 400 | parameter error: purchase_date: "required field" | 必須パラメータである purchase_date が指定されていない場合に発生します。 |
| 400 | parameter error: purchase_date: "not date format : {value} an invalid date: {value}" | purchase_date に空文字を指定した場合や、yyyy-mm-dd 形式でない場合に発生します。 |
| 400 | parameter error: purchase_date: "not date format : {value}" | purchase_date に存在しない日付を指定した場合に発生します。 |
| 400 | parameter error: start_date: "required field" | 必須パラメータである start_date が指定されていない場合に発生します。 |
| 400 | parameter error: start_date: "not date format : {value} an invalid date: {value}" | start_date に空文字を指定した場合や、yyyy-mm-dd 形式でない場合に発生します。 |
| 400 | parameter error: start_date: "not date format : {value}" | start_date に存在しない日付を指定した場合に発生します。 |
| 400 | parameter error: refund_date: "required field" | 必須パラメータである refund_date が指定されていない場合に発生します。 |
| 400 | parameter error: refund_date: "not date format : {value} an invalid date: {value}" | refund_date に空文字を指定した場合や、yyyy-mm-dd 形式でない場合に発生します。 |
| 400 | parameter error: refund_date: "not date format : {value}" | refund_date に存在しない日付を指定した場合に発生します。 |
| 400 | "invalid date term" | start_date または refund_date に purchase_date よりも過去の日付を指定した場合に発生します。 |
| 400 | parameter error: company: "required field" | 必須パラメータである company が指定されていない場合に発生します。 |
| 400 | parameter error: company: "an invalid code: {value}" | company に空文字を指定した場合や、不正な鉄道会社IDを指定した場合に発生します。 |
| 400 | parameter error: fare: "field 'fare' cannot be coerced: invalid literal for int() with base 10: '{value}'" | fare に空文字を指定した場合や、数値に変換できない値を指定した場合に発生します。 |
| 400 | parameter error: fare: "min value is 1" | fare に下限値（1未満）の範囲外の値を指定した場合に発生します。 |
| 400 | parameter error: fare: "max value is 99999" | fare に上限値（99999超過）の範囲外の値を指定した場合に発生します。 |
| 400 | parameter error: commuter_pass_amount: "field 'commuter_pass_amount' cannot be coerced: invalid literal for int() with base 10: '{value}'" | commuter_pass_amount に空文字を指定した場合や、数値に変換できない値を指定した場合に発生します。 |
| 400 | parameter error: commuter_pass_amount: "min value is 1" | commuter_pass_amount に下限値（1未満）の範囲外の値を指定した場合に発生します。 |
| 400 | parameter error: commuter_pass_amount: "max value is 999999" | commuter_pass_amount に上限値（999999超過）の範囲外の値を指定した場合に発生します。 |
| 400 | "The specified route does not include the route of the company: {value}" | company に指定した鉄道会社の路線が、section_info に指定した定期区間に含まれていない場合に発生します。 |
| 400 | "The company is not covered by service: {value}" | company に払い戻し計算のサービス対象外の鉄道会社を指定した場合に発生します。 |
| 400 | "The company cannot use fare and commuter_pass_amount: {value}" | fare, commuter_pass_amount を指定できない鉄道会社を company に指定した場合に発生します。 |
| 400 | "Refunds are not possible : Refund date has expired" | refund_date に定期券の有効期間を過ぎた日付を指定した場合に発生します。 |
| 400 | "The route was not found" | section_info に指定した定期区間の経路が取得できない場合に発生します。 |
| 400 | "The commuter pass amount is not exists" | section_info に指定した定期区間の定期券運賃が取得できない場合に発生します。 |
| 400 | "bad usage on this contract : invalid company" | company に、契約上ご利用いただけない鉄道会社IDを指定した場合に発生します。 |
| 400 | "bad usage on this contract : use_company and unuse_company must be either." | 契約の交通機関会社の利用可否設定に不整合がある場合に発生します。 |