定期券の払い戻し計算
払い戻し計算のもととなる定期券の組み合わせを複数取得します。
GET /v1/{format}/course/repayment
parameters
※ Requiredの「△」は、特定の条件においてそのパラメータが必須になることを示します。詳しくはパラメータのDescriptionを参照してください。
Name | Type | Required | Description |
---|---|---|---|
format | string | ◯ | レスポンスのデータ形式の指定。必須。 指定できる値: - xml: xml形式のデータ - json: json形式のデータ ※クエリパラメータではなくパスに値を指定します。 |
key | string | ◯ | アクセスキー。必須 |
serializeData | string | ◯ | 経路シリアライズデータ。必須 |
checkEngineVersion | string | --- | 完全な経路シリアライズデータの再現を行う場合は、シリアライズデータ作成時のエンジンバージョンと再現時のエンジンバージョンが同一かのチェックを有効にします。エンジンバージョンが異なる場合は、エラーを返します。省略可。 指定できる値: - true: チェックする - false: チェックしない Default: true |
startDate | int | --- | 定期券の有効開始日付。省略可。 Format: YYYYMMDD Default: 現在日付 |
buyDate | int | --- | 定期券の購入日付。運賃改定により購入日と有効開始日で定期券の金額が異なる場合、購入日時点の定期券金額から払戻金額を算出できます。省略可。 Format: YYYYMMDD Default: 有効開始日付と同日の扱い |
repaymentDate | int | --- | 定期券の払い戻し日付。省略可。 Format: YYYYMMDD Default: 現在日付 |
validityPeriod | int | --- | 定期券の有効期間。省略可。 指定できる値: - 1: 1ヶ月 - 3: 3ヶ月 - 6: 6ヶ月 - 12: 12ヶ月 Default: 6 ※ 詳しくはこちら |
changeSection | string | --- | 定期券の払い戻し時に区間変更として計算するかの指定。同一鉄道会社内で別の区間の定期券を買い直すときtrueを設定します。なお区間変更の可否については、鉄道会社ごとに条件が定められています。詳しくは鉄道会社へお問い合わせください。省略可。 指定できる値: - true: 計算する - false: 計算しない Default: false ※ レスポンスに区間変更時の払い戻し金額と解約時の払い戻し金額のどちらが返却されたかについては、定期券の払い戻し額を調べるをご確認ください。 |
separator | string | --- | 定期券が複数の鉄道会社をまたがるとき、1枚の定期券として払い戻す場合と複数枚の定期券として払い戻す場合の選択ができます。複数指定可。省略可。省略時は分割しない 詳しくはこちらを参照。 |
validityPeriod
払い戻す定期の有効期間を、1ヶ月/3ヶ月/6ヶ月/12ヶ月から指定します。
GET /v1/xml/course/repayment?key=アクセスキーを入力してください&validityPeriod=3&serializeData={{「東京--JR中央線快速--新宿」のシリアライズデータ}}
<ResultSet apiVersion="1.27.0.0" engineVersion="201811_02a">
:
<RepaymentList validityPeriod="3" ...>
<!-- リクエストパラメータのvalidityPeriodに3を指定した場合、結果には有効期間が3ヶ月の定期券の払い戻し金額が返されます -->
<RepaymentTicket repayPriceValue="15960" validityPeriod="3".../>
</RepaymentList>
</ResultSet>
validityPeriodパラメータに、指定可能な値(1
: 1ヶ月、3
: 3ヶ月、6
: 6ヶ月、12
: 12ヶ月)のいずれでもない値が指定された場合は、エラーにはならず、未指定時のデフォルト値である6
(6ヶ月)として扱います。
なお、指定した有効期間の定期券が経路に存在しない場合は、エラーにはならず、その区間の「定期券の最大有効期間」で払い戻し計算を行います。
■例 「定期券の最大有効期間」が3ヶ月の「JR東海道新幹線」の定期区間に対して、
- validityPeriodパラメータに
3
が指定された場合、3ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータに
6
が指定された場合、3ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータに
想定外の9
が指定された場合、3ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータが
未指定
の場合、3ヶ月の払い戻し金額がレスポンスに返されます。
■例 「定期券の最大有効期間」が12ヶ月の「東急田園都市線」の定期区間に対して、
- validityPeriodパラメータに
3
が指定された場合、3ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータに
12
が指定された場合、12ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータに
想定外の9
が指定された場合、6ヶ月の払い戻し金額がレスポンスに返されます。 - validityPeriodパラメータが
未指定
の場合、6ヶ月の払い戻し金額がレスポンスに返されます。
note
指定した有効期間が存在しないことをチェックしたい場合は、validityPeriodパラメータに指定した値と、レスポンスの
ResultSet / RepaymentList / RepaymentTicket / validityPeriod
の値が異なっていることで判定可能です。
separator
区間分割は、レスポンスのSectionSeparatorのindexResultSet / TeikiRoute / SectionSeparator / index
を指定して以下のフォーマットで指定します。
[SectionSeparatorのindex],[分割する場合はtrue分割しない場合はfalseを指定]
indexが1のSectionSeparatorの部分で分割する場合
separator=1,true
response
Name | Description |
---|---|
ResultSet | レスポンスの最下部を表す要素 |
ResultSet / apiVersion | WebAPIバージョン |
ResultSet / engineVersion | エンジンバージョン |
ResultSet / RepaymentList | 定期券の払い戻し情報の一覧を表す要素 |
ResultSet / RepaymentList / buyDate | 定期券の購入日付 |
ResultSet / RepaymentList / repaymentDate | 定期券払い戻し日 |
ResultSet / RepaymentList / startDate | 定期券の有効開始日 |
ResultSet / RepaymentList / validityPeriod | 有効期間 単位: month |
ResultSet / RepaymentList / RepaymentTicket | 定期券の払い戻し情報を表す要素 |
ResultSet / RepaymentList / RepaymentTicket / calculateTarget | 計算対象かどうか - True: 計算対象 - False: 計算対象外 |
ResultSet / RepaymentList / RepaymentTicket / feePriceValue | 手数料 |
ResultSet / RepaymentList / RepaymentTicket / fromTeikiRouteSectionIndex | 開始区間インデックス |
ResultSet / RepaymentList / RepaymentTicket / index | インデックス ※ jsonデータ形式のレスポンスにインデックスは含まれません。JSON形式のレスポンスデータを利用する際の注意事項 |
ResultSet / RepaymentList / RepaymentTicket / payPriceValue | 購入金額 |
ResultSet / RepaymentList / RepaymentTicket / repayPriceValue | 払い戻し金額 |
ResultSet / RepaymentList / RepaymentTicket / state | 定期券の状態 - 0x0001: パラメータエラー - 0x0002: 計算されていない状態 - 0x8000: 未対応の会社が含まれている - 0x4000: 計算する対象ではない |
ResultSet / RepaymentList / RepaymentTicket / toTeikiRouteSectionIndex | 終了区間インデックス |
ResultSet / RepaymentList / RepaymentTicket / usedPriceValue | 使用済金額 |
ResultSet / RepaymentList / RepaymentTicket / validityPeriod | 有効期間 単位: month |
ResultSet / RepaymentList / RepaymentTicket / changeableSection | 「駅すぱあと」で定期券の払い戻し時に区間変更として計算できるか。 - true: できる。 - false: できない。 詳しくは定期券の払い戻し額を調べるをご参照ください。 |
ResultSet / TeikiRoute | 定期券の払い戻し用経路を表す要素 |
ResultSet / TeikiRoute / SectionSeparator | 定期券経路区間の区切りの状態を表す要素 |
ResultSet / TeikiRoute / SectionSeparator / changeable | - true: dividedの状態を変更可能 - false: 変更不可能 |
ResultSet / TeikiRoute / SectionSeparator / divided | - true: この区切りで定期券が分割されている - false: 分割されていない |
ResultSet / TeikiRoute / SectionSeparator / index | インデックス ※ jsonデータ形式のレスポンスにインデックスは含まれません。JSON形式のレスポンスデータを利用する際の注意事項 |
ResultSet / TeikiRoute / TeikiRouteSection | 定期券の払い戻し用経路の一区間を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection / index | インデックス ※ jsonデータ形式のレスポンスにインデックスは含まれません。JSON形式のレスポンスデータを利用する際の注意事項 |
ResultSet / TeikiRoute / TeikiRouteSection / repaymentTicketIndex | 払い戻しインデックス |
ResultSet / TeikiRoute / TeikiRouteSection /Point | 地点 を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / index | インデックス ※ jsonデータ形式のレスポンスにインデックスは含まれません。JSON形式のレスポンスデータを利用する際の注意事項 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Prefecture | 都道府県を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Prefecture / code | 都道府県コード |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Prefecture / Name | 都道府県の名称を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Station | 駅を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Station / code | 駅コード |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Station / Name | 駅の名称を表す要素 |
ResultSet / TeikiRoute / TeikiRouteSection /Point / Station / Type | 交通種別を表す要素 |
example
GET /v1/xml/course/repayment?key=アクセスキーを入力してください&separator=1,true&serializeData=VkV4QaECp9nIAsMCpgEz76YDpgEz76UEkcIBQwAAAAKmATPvpQPKAQECAQMBBAEHAQgBCgIPQv9_EKX_9xSRpVjVBZfBAqVYj8ECpVjVwQKlWXvBAqVZLMECpVkPwQKlWvHBAqVXwAaSwwEBAgEDxwGlWFoCDQMPBQMGRDk0NlQHBAgDwwEBAgEDxgGmAAIwMwIVAxYFAwcGCAUHksUBpgEz76gDpQJfBKUCZgUACADGAaYBM||oAgEDpQJwBKUCcQUACAAIksQEAQUBB6RtCAHGAgEEAgUBBgEHpQEvCAIJksEDAcMBAQIBAwEPkcUBkwABAgKSwwEAAgADAMMBAQIBAwEDksMBAAIAAwDDAQECAQMBBJIAAQWSAAA*--T3221233232319:F332112212000:A23121141:--88eed71f6168dfe5ab30b8cc5e938621dd3806a7--0--0--0--284
<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
<TeikiRoute>
<TeikiRouteSection repaymentTicketIndex="1" index="1">
<Point index="1">
<Station code="22671">
<Name>高円寺</Name>
<Type>train</Type>
</Station>
<Prefecture code="13">
<Name>東京都</Name>
</Prefecture>
</Point>
<Point index="2">
<Station code="22741">
<Name>新宿</Name>
<Type>train</Type>
</Station>
<Prefecture code="13">
<Name>東京都</Name>
</Prefecture>
</Point>
</TeikiRouteSection>
<SectionSeparator index="1" divided="true" changeable="true" />
<TeikiRouteSection repaymentTicketIndex="2" index="2">
<Point index="3">
<Station code="22741">
<Name>新宿</Name>
<Type>train</Type>
</Station>
<Prefecture code="13">
<Name>東京都</Name>
</Prefecture>
</Point>
<Point index="4">
<Station code="22907">
<Name>初台</Name>
<Type>train</Type>
</Station>
<Prefecture code="13">
<Name>東京都</Name>
</Prefecture>
</Point>
</TeikiRouteSection>
</TeikiRoute>
<RepaymentList repaymentDate="2018-09-04" validityPeriod="6" startDate="2018-09-04" buyDate="2018-09-04">
<RepaymentTicket feePriceValue="220" repayPriceValue="22720" state="0" usedPriceValue="320" calculateTarget="True" toTeikiRouteSectionIndex="1" fromTeikiRouteSectionIndex="1" index="1" validityPeriod="6" payPriceValue="23260" changeableSection="true"/>
<RepaymentTicket feePriceValue="220" repayPriceValue="24420" state="0" usedPriceValue="260" calculateTarget="True" toTeikiRouteSectionIndex="2" fromTeikiRouteSectionIndex="2" index="2" validityPeriod="6" payPriceValue="24900" changeableSection="true"/>
</RepaymentList>
</ResultSet>
GET /v1/json/course/repayment?key=アクセスキーを入力してください&separator=1,true&serializeData=VkV4QaECp9nIAsMCpgEz76YDpgEz76UEkcIBQwAAAAKmATPvpQPKAQECAQMBBAEHAQgBCgIPQv9_EKX_9xSRpVjVBZfBAqVYj8ECpVjVwQKlWXvBAqVZLMECpVkPwQKlWvHBAqVXwAaSwwEBAgEDxwGlWFoCDQMPBQMGRDk0NlQHBAgDwwEBAgEDxgGmAAIwMwIVAxYFAwcGCAUHksUBpgEz76gDpQJfBKUCZgUACADGAaYBM||oAgEDpQJwBKUCcQUACAAIksQEAQUBB6RtCAHGAgEEAgUBBgEHpQEvCAIJksEDAcMBAQIBAwEPkcUBkwABAgKSwwEAAgADAMMBAQIBAwEDksMBAAIAAwDDAQECAQMBBJIAAQWSAAA*--T3221233232319:F332112212000:A23121141:--88eed71f6168dfe5ab30b8cc5e938621dd3806a7--0--0--0--284
{
"ResultSet": {
"apiVersion": "1.27.0.0",
"engineVersion": "201809_02a",
"RepaymentList": {
"repaymentDate": "2018-09-04",
"validityPeriod": "6",
"startDate": "2018-09-04",
"buyDate": "2018-09-04",
"RepaymentTicket": [
{
"feePriceValue": "220",
"repayPriceValue": "22720",
"state": "0",
"usedPriceValue": "320",
"calculateTarget": "True",
"toTeikiRouteSectionIndex": "1",
"fromTeikiRouteSectionIndex": "1",
"validityPeriod": "6",
"payPriceValue": "23260",
"changeableSection": "true"
},
{
"feePriceValue": "220",
"repayPriceValue": "24420",
"state": "0",
"usedPriceValue": "260",
"calculateTarget": "True",
"toTeikiRouteSectionIndex": "2",
"fromTeikiRouteSectionIndex": "2",
"validityPeriod": "6",
"payPriceValue": "24900",
"changeableSection": "true"
}
]
},
"TeikiRoute": {
"SectionSeparator": {
"divided": "true",
"changeable": "true"
},
"TeikiRouteSection": [
{
"repaymentTicketIndex": "1",
"Point": [
{
"Station": {
"code": "22671",
"Name": "高円寺",
"Type": "train"
},
"Prefecture": {
"code": "13",
"Name": "東京都"
}
},
{
"Station": {
"code": "22741",
"Name": "新宿",
"Type": "train"
},
"Prefecture": {
"code": "13",
"Name": "東京都"
}
}
]
},
{
"repaymentTicketIndex": "2",
"Point": [
{
"Station": {
"code": "22741",
"Name": "新宿",
"Type": "train"
},
"Prefecture": {
"code": "13",
"Name": "東京都"
}
},
{
"Station": {
"code": "22907",
"Name": "初台",
"Type": "train"
},
"Prefecture": {
"code": "13",
"Name": "東京都"
}
}
]
}
]
}
}
}