定期券の払い戻し額を調べる

定期券の払い戻しを行います。

定期券は、払い戻しの場合と区間変更の場合とで、払い戻し金額が異なる場合があります。

note

定期券の情報を長期保存する際は、駅コードや平均路線を保存いただき、払い戻し計算を行う際に再探索を行った結果の経路シリアライズデータをご利用ください。経路シリアライズデータを長期保存することは推奨しておりません。定期割り当て用の定期券情報の作成については、定期情報の取得をご確認ください。

手順

1. 経路探索を行う

経路探索 /search/coruse/extreme などで経路探索を行い、対象定期券の経路シリアライズデータを取得します。
リクエスト例では経路探索を利用していますが、ダイヤによる探索か平均待ち時間による探索かは問わないので、経路簡易探索や平均待ち時間探索も利用可能です。

ここでは高円寺駅から新宿駅までの経路を例とします。

GET /v1/xml/search/course/extreme?viaList=22671:22741

<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
  <Course searchType="departure" dataType="onTimetable">
    <SerializeData>
    経路シリアライズデータ
    </SerializeData>
      :
  </Course>
    :
</ResultSet>

2. 定期券の払い戻し計算を行う

定期券の払い戻し計算 /course/repaymentを利用して、定期券の払い戻し額の計算を行います。 serializeDataパラメータには、1のレスポンスで取得した経路シリアライズデータ ResultSet/Course/SerializeDataを指定します。

区間変更時の払い戻し額を取得したい場合は、払い戻しを区間変更として計算するかを設定するchangeSectionパラメータに、trueを指定します。必要に応じてその他のパラメータも指定してください。

レスポンスのうちResultSet / RepaymentList / RepaymentTicket / repayPriceValueが払い戻し金額を表しています。

note

buyDateパラメータは、定期券の購入日が有効開始日と異なる場合に設定します。購入日は省略することができ、その場合は有効開始日の値が採用されます。ただし、払戻対象の定期の購入金額は購入日を元に算出されるため、実際の購入日を省略せずに指定しないと、正しい払戻金額が算出できない場合があります。

例：値上げ実施当日から利用開始となる定期券を、数日前に値上げ実施前の金額で購入していた場合

Attention!

定期券の払い戻しは、払い戻しと区間変更の2種類がありますが、区間変更ができない区間もあります。changeSectionパラメータにtrueを指定しても、区間変更ができない払い戻し区間がある場合はResultSet/RepaymentList/RepaymentTicket/repayPriceValueには、区間変更時の払い戻し額ではなく、全解約時の払い戻し額が返されます。ご注意ください。

なお、changeSectionパラメータにtrueを指定した結果、区間変更と払い戻しのどちらの払い戻し額が返却されたかは、レスポンスのResultSet/RepaymentList/RepaymentTicket/changeableSectionの値で確認ができます。この値がtrueの時は区間変更の金額が、falseの時は払い戻しの金額が返されています。

また、区間変更ができる区間とできない区間が組み合わさっている場合、全区間が区間変更できないと判定されます。その場合、区間の分割機能（separatorパラメータ）を利用することで、区間変更できる区間にのみ、区間変更の計算を適用することができます。分割機能については鉄道会社ごとの定期券払い戻し額を調べるをご確認ください。

<払い戻しの場合>

GET /v1/xml/course/repayment?changeSection=false&repaymentDate=20181031&serializeData=1で取得した経路シリアライズデータ

<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
    :
  <RepaymentList ...>
    <!-- リクエストパラメータのchangeSectionにfalseを指定しているため、repayPriceValueには区間変更の払い戻し額ではなく、解約時の払い戻し額が返っています。 -->
    <RepaymentTicket ... repayPriceValue="13340" changeableSection="true"/>
  </RepaymentList>
</ResultSet>

<区間変更の場合>

GET /v1/xml/course/repayment?changeSection=true&repaymentDate=20181031&serializeData=1で取得した経路シリアライズデータ

<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
    :
  <RepaymentList ...>
    <!-- リクエストパラメータのchangeSectionにtrueを指定しており、レスポンスのchangeableSectionがtrueになっていることから、repayPriceValueには解約時の払い戻し額ではなく区間変更の払い戻し額が返っていることがわかります。 -->
    <RepaymentTicket ... repayPriceValue="17840" changeableSection="true"/>
  </RepaymentList>
</ResultSet>

<区間変更として計算すると指定したが、区間変更ができない場合>

ここでは神宮前駅(24999)から名鉄名古屋駅(24990)を例とします。

GET /v1/xml/course/repayment?changeSection=true&serializeData=経路探索で取得できる経路シリアライズデータ

<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
    :
  <RepaymentList ...>
    <!-- リクエストパラメータのchangeSectionにtrueを指定していますが、レスポンスのchangeableSectionがfalseになっているため、repayPriceValueには区間変更の払い戻し額ではなく、解約時の払い戻し額が返っていることがわかります。 -->
    <RepaymentTicket ... repayPriceValue="42180" changeableSection="false"/>
  </RepaymentList>
</ResultSet>

定期券の払い戻し額を調べる

関連URL

手順

1. 経路探索を行う

2. 定期券の払い戻し計算を行う