定期券払い戻し計算
/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"
}