定期券の払い戻し計算

払い戻し計算のもととなる定期券の組み合わせを複数取得します。

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": "東京都"
          }
        }
        ]
      }
      ]
    }
  }
}
ページ上部へ