API の概要

このセクションでは、D1 Transit API、トランジットイシュアが実装する必要のあるもの、およびバックエンド間の統合のためのさまざまなセクションについて詳述します。

API設計

データ形式

D1 Transitとトランジットイシュアのサーバー間で交換されるデータは、JSONデータ構造としてフォーマットされます。

文字列のエンコーディングは特に指定がない限りUTF-8です。

トランスポートプロトコル

すべてのインターフェースで使用される通信プロトコルはHTTPSとします。

エラー管理

すべてのAPIレスポンスはHTTP 200ステータスコードと適用可能なアプリケーションステータスコード（下表参照）で返すべきです。

予期しないサーバーエラー（例：捕捉されない例外）が発生した場合は、HTTP 500ステータスコードを返すべきです。この場合、エラーは再試行不可と見なされます。

サーバーが利用できない場合は、HTTP 503ステータスコードを返すべきです。この場合、エラーは再試行可能と見なされます。

下表は使用可能なすべてのステータスコードを一覧にしています。

ステータスコード	説明	該当API
0	OK	すべて
111	必須パラメータが欠落しています	すべて
112	パラメータの形式が不正です	すべて
113	不明なイシュア	すべて
116	不明なカード口座	cancelCardAccount manageDigitalCard getCardAccountInfo
117	不明なデバイス
118	不明なセッション
119	不明なデジタルカード	manageDigitalCard getDigitalCardBundleData
120	不明な購入
158	カードが期限切れです	purchaseProducts getDigitalCardBundleCommands
159	カードが停止／無効／ブラックリストされています	purchaseProducts getDigitalCardBundleCommands
160	カードは削除されています
162	カードの残高が不足しています	purchaseProducts getDigitalCardBundleCommands
163	カード口座は適格ではありません	getDigitalCardBundleData getDigitalCardBundleCommands
164	プロビジョニング回数を超過しました	getDigitalCardBundleData
166	カード情報が無効です
167	カードは既にプロビジョニングされています	getDigitalCardBundleCommands
169	購入注文が拒否されました	purchaseProducts
170	プロビジョニング要求が拒否されました	getDigitalCardBundleData
171	ウォレットアカウントの不一致。ウォレットアカウントは別の顧客名義のカードに既に紐付いています	getDigitalCardBundleData
172	サポートされていないシステムコード	getDigitalCardBundleCommands
173	サポートされていないサービス	getDigitalCardBundleCommands
177	無効なエリアデータ	getDigitalCardBundleCommands
178	カードのステータスが駅内です	getDigitalCardBundleCommands
192	リーダーモードの試行が許容閾値を超えました	getDigitalCardBundleCommands
221	デバイスまたはウォレットサーバーにアクセスできません
231	デバイスの予期しないエラー
232	デバイスのメモリ不足エラー
321	このデバイスで既に進行中の操作があります	manageDigitalCard
322	操作の有効期間が切れました
419	PINが必要です	purchaseProducts
420	PINが不正です	purchaseProducts
421	PINがロックされています	purchaseProducts
431	無効な個人化データ
432	現在のカード状態では操作は許可されていません	manageDigitalCard
911	操作に失敗しました	すべて
921	予期しないサーバーエラー	すべて

適用されるステータスコードは各APIメソッドにおいてベストエフォートで記載されています。

下位互換性ルール

このセクションでは、APIの進化に伴う互換性を確保するためにThalesが適用する下位互換性ルールを定義します。

• ThalesはAPIリクエストおよび／またはレスポンスにオプションのパラメータ（HTTPヘッダー、URL、ボディ）を追加する場合があります。トランジットイシュアは厳密な検証を行ってはなりません。

「厳密な検証」は、ある時点のAPI仕様に定義されていない望ましくないパラメータによるAPI呼び出しを制限または制約する設定です。

• APIエラーメッセージ文字列は、新しいリリースで影響なく進化する可能性があります。これらのエラーメッセージはトラブルシューティング目的のものであり、イシュアは事前定義された固定フォーマットを期待してはなりません。
• D1 Transitソリューションからトランジットイシュアシステムに送信されるHTTPリクエストまたはレスポンスのパラメータは、オプションから必須に変更される可能性があります。
• トランジットイシュアシステムからD1 Transitソリューションに送信されるHTTPリクエストまたはレスポンスのパラメータは、必須からオプションに変更される可能性があります。
• APIパラメータの順序は固定されていません。
• Thalesは既存の列挙型パラメータに新しい値を追加する場合があります。
• Thalesは新しい操作（HTTPメソッド、URL、リソース）を追加してAPIを拡張する場合があります。
• Thalesは新しいHTTPステータスレスポンスコードを追加してレスポンスを拡張する場合があります。

APIパラメータ／操作の廃止（End of Life）

Thalesは、いかなるAPIパラメータまたはAPI操作（HTTPメソッド、URL、リソース）の廃止期間（デprecation期間）について、遅くとも廃止の9か月前までにトランジットイシュアに通知します。

明確にするために、廃止期間後は、廃止されたAPIパラメータおよびAPI操作は、本番環境および非本番環境のいかなるトランジットイシュアシステムでも使用してはなりません。

Thalesは、以下の条件に限定されることなく廃止期間を短縮する場合があります：(i) 重大なセキュリティリスク；(ii) 実質的な経済的または技術的影響；(iii) 適用法またはデジタルウォレットにより要求される場合。

バックエンド統合

D1 Transit APIを呼び出すには、次の設定が必要です：

1. 接続性
2. データ暗号化

Transit API

以下に利用可能なAPIの一覧を示します

• インバウンドAPI
• 通知インバウンドAPI
• アウトバウンドAPI

トランジットAPIに対して行われるすべての更新および進化は、以下に反映されます リリースノート

データ準備

以下のデータ準備セクションは、デジタルカードバンドルを準備するためにトランジットイシュアがD1 Transitに提供する必要があるデータに関する情報を提供します。