> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/ja/d1-transit-api-wosuru/api-no.md).

# API の概要

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

#### API設計 <a href="#api-design" id="api-design"></a>

**データ形式**

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

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

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

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

**エラー管理**

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

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

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

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

| ステータスコード | 説明                                             | 該当API                                                               |
| -------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| 0        | OK                                             | すべて                                                                 |
| 111      | 必須パラメータが欠落しています                                | すべて                                                                 |
| 112      | パラメータの形式が不正です                                  | すべて                                                                 |
| 113      | 不明なイシュア                                        | すべて                                                                 |
| 116      | 不明なカード口座                                       | <p>cancelCardAccount<br>manageDigitalCard<br>getCardAccountInfo</p> |
| 117      | 不明なデバイス                                        |                                                                     |
| 118      | 不明なセッション                                       |                                                                     |
| 119      | 不明なデジタルカード                                     | <p>manageDigitalCard<br>getDigitalCardBundleData</p>                |
| 120      | 不明な購入                                          |                                                                     |
| 158      | カードが期限切れです                                     | <p>purchaseProducts<br>getDigitalCardBundleCommands</p>             |
| 159      | カードが停止／無効／ブラックリストされています                        | <p>purchaseProducts<br>getDigitalCardBundleCommands</p>             |
| 160      | カードは削除されています                                   |                                                                     |
| 162      | カードの残高が不足しています                                 | <p>purchaseProducts<br>getDigitalCardBundleCommands</p>             |
| 163      | カード口座は適格ではありません                                | <p>getDigitalCardBundleData<br>getDigitalCardBundleCommands</p>     |
| 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メソッドにおいてベストエフォートで記載されています。

#### 下位互換性ルール <a href="#backward-compatibility-rules" id="backward-compatibility-rules"></a>

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

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

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

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

#### APIパラメータ／操作の廃止（End of Life） <a href="#api-parameteroperation-end-of-life" id="api-parameteroperation-end-of-life"></a>

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

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

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

#### バックエンド統合 <a href="#backend-integration" id="backend-integration"></a>

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

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

#### Transit API <a href="#transit-apis" id="transit-apis"></a>

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

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

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

#### データ準備 <a href="#data-preparation" id="data-preparation"></a>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/transit-digitization/ja/d1-transit-api-wosuru/api-no.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.