> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# デジタルIDウォレット認証API

> DiditのAPIを使えば、検証ワークフローを作成せずに、自社のアプリケーションからデジタルIDウォレットで本人確認を行えます。

独自のアプリケーションから本人を認証するには、専用のウォレットエンドポイントを使用します。
ワークフローを作成または公開する必要はなく、`workflow_id`を指定する必要もありません。
バックエンドが認証を開始してその結果を取得し、インターフェースが、ウォレットで要求される認証を本人が完了できるよう案内します。

> [!NOTE]
>
> API連携であっても、本人が認証を行い、身元情報の共有を承認する必要があります。
> そのような操作なしに、個人識別子を送信するだけで本人を認証することはできません。

## 認証の仕組み

1. バックエンドで[ウォレットカタログ](https://docs.didit.me/ja/standalone-apis/digital-id-wallet-catalog.md)を確認し、アプリケーションのAPIキーを使って、利用可能なウォレットのstartエンドポイントを呼び出します。
2. Diditは認証の参照情報と、本人が行う必要のあるアクションを返します。
3. アプリケーションで認証ページを開くか、ウォレットの承認手順を表示します。
4. 本人がウォレットで認証を行います。
5. バックエンドで認証結果を取得し、完了通知を処理します。

ウォレット認証は非同期で行われます。
startリクエストが成功した場合、それは認証が開始されたことを意味し、本人確認が完了したことを意味するわけではありません。
本人を認証済みとして扱う前に、必ず最終結果を確認してください。

## バックエンド連携

[デジタルIDウォレットの一覧取得](https://docs.didit.me/ja/standalone-apis/digital-id-wallet-catalog.md)を使用して、アプリケーションで利用できる最新のエンドポイント、必須フィールド、提供状況を取得します。

`x-api-key`はバックエンドで管理してください。
ブラウザ用のバンドルやモバイルアプリケーションには含めないでください。
新しい認証の試行ごとに異なる`Idempotency-Key`を使用し、同じ開始リクエストを再試行する際にはそのキーを再利用してください。
キーを再利用しながらリクエスト内容を変更すると、新しい認証の試行ではなく競合として扱われます。

各ウォレットには固有の開始URLがあります。たとえばFinnish Trust Networkの場合は`/v3/id-verification/wallets/ftn/`です。
`request_id`は、以降の操作でスタンドアロン認証を識別するためのものです。
独自の参照情報には最大2,000 UTF-8バイトまでの`vendor_data`を使用し、任意のJSONオブジェクトには`metadata`を使用します。
どちらも結果と完了Webhookに含まれて返されます。

| 操作 | エンドポイント |
| - | - |
| ステータスと結果の取得 | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| 電話での承認のポーリング | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Digital Credentialsウォレットのレスポンスの送信 | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| 保留中の認証のキャンセル | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

これらの操作には、認証を開始したアプリケーションのAPIキーを使用します。
ポーリングと認証の利用可否は、選択したウォレットによって異なります。

キャンセルを行うと、保留中の認証は料金が発生することなく却下され、完了済みの認証は変更されずにそのまま返されます。
Smart-IDとMobile-IDでは、ポーリングが承認を確認している最中にキャンセルが届いた場合、そのポーリングの完了を数秒間待機します。
その後、認証を却下するか、本人がすでに承認していた場合は`verified`として返します。
本人がまさに完了しようとしている認証はキャンセルできません。この場合、レスポンスは`409`となり、`error: "verification_in_progress"`と`Retry-After`ヘッダーが返されます。
指定された秒数が経過してから再試行し、完了した結果を取得してください。

## 戻り先を登録する

リダイレクト型のウォレットは、認証後に本人をアプリケーションへ戻します。
認証を開始する前に、正確なホスト名を登録してください。

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

その後、開始リクエストでHTTPSの`return_url`(例: `https://app.example.com/identity/complete`)を送信します。
`allowed_return_hosts`には、スキーム、パス、ワイルドカードを含まないホスト名のみを指定してください。
使用するサブドメインはそれぞれ個別に登録し、最大20個のホスト名まで登録できます。
`allowed_return_hosts`を更新すると登録済みのリストが置き換えられるため、残したいホスト名はすべて含めてください。
`GET /v3/webhook/`は現在のリストを返します。詳しくは[Webhookの設定](https://docs.didit.me/ja/sessions-api/management-api.md#webhook設定)を参照してください。
戻り先の登録に、ワークフローやホワイトラベルのドメインは必要ありません。
戻り先はブラウザで表示される戻りページです。バックエンド向けの完了Webhookは別途設定してください。

## Finnish Trust Networkの例

戻り先のホスト名を登録したら、Finnish Trust Networkの認証を開始します。

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

返された`request_id`を保存し、`type`が`redirect`の場合は本人のブラウザを`wallet_verification.next_action.url`にリダイレクトさせます。
本人が戻ってきたら、バックエンドから結果を取得します。

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

`wallet_verification.outcome`を確認します。

| 結果 | 意味 |
| - | - |
| `pending` | 認証はまだ進行中です。 |
| `verified` | 認証が完了し、返された身元情報は認証済みです。 |
| `cancelled` | 本人またはアプリケーションが試行をキャンセルしました。 |
| `timeout` | 認証ウィンドウの有効期限が切れました。 |
| `failed` | 認証または身元情報の検証に失敗しました。 |

実際の本人確認では、結果が`verified`で、かつ`simulated`が`false`の場合にのみ身元情報を使用してください。
保留中のレスポンスには次のアクションが含まれる場合がありますが、最終状態のレスポンスには次のアクションは含まれません。

## 認証方式

**リダイレクト型ウォレット**は認証URLを返します。
そのURLを本人のブラウザで開き、ウォレットの認証プロセスを完了してもらってから、登録済みの戻り先に戻してください。
戻りURLのパラメーターを本人確認の証拠として信頼せず、結果はバックエンドから取得してください。

**Smart-IDとMobile-ID**は、本人のスマートフォンに表示される承認プロンプトを使用します。
必要な個人識別子はお客様のインターフェースで収集します。Mobile-IDでは、紐づく電話番号も必要です。
照合コードを表示し、スマートフォンに表示されたコードと一致する場合にのみ承認するよう本人に案内してください。
PINはウォレットまたはスマートフォンのプロンプトで入力するものであり、お客様のフォームやAPIリクエストで扱ってはなりません。
返された`poll_interval_seconds`の間隔で、プロンプトの応答をバックエンドからポーリングしてください。
Diditは保留中のスマートフォン承認もバックグラウンドで確認するため、本人がページを閉じた後でも完了通知がWebhookに届くことがあります。

**Google Wallet**には、リダイレクトを使わず、Digital Credentials APIを通じてお客様自身のページやアプリから要求します。詳しくは[Digital Credentialsウォレット (Google Wallet)](#digital-credentialsウォレット-google-wallet)を参照してください。

利用できる操作方法は、選択したウォレットによって異なります。
すべてのウォレットが埋め込みフォーム、QRコード、ブラウザを使わない認証に対応していると想定しないでください。

## Digital Credentialsウォレット (Google Wallet)

Google Walletには、W3C Digital Credentials APIを使用して、お客様のWebページまたはAndroidアプリから直接要求します。
リダイレクト、Diditがホストするページ、DiditのQRコードはいずれもありません。
本番環境では**近日公開**です。サンドボックスアプリケーションとステージング環境では動作し、本番環境での利用はGoogleの承認後に可能になります。
お使いのアプリケーションで現在開始できるものは、[デジタルIDウォレットの一覧](https://docs.didit.me/ja/standalone-apis/digital-id-wallet-catalog.md)で確認してください。

**1. オリジンを指定して開始する**

バックエンドから、本人の`country`（`USA`、`GBR`、`BRA`、`SGP`または`TWN`）と、ウォレットに要求を行う`origin`を指定して`POST /v3/id-verification/wallets/google-wallet/`を呼び出します。
`origin`は`https://app.example.com`のようなページのHTTPSオリジンであり、そのホストは[登録済みの戻り先ホスト名](#戻り先を登録する)またはホワイトラベルドメインのいずれかである必要があります。
Androidアプリの場合は、`android:apk-key-hash:`の後に、アプリの署名証明書のSHA-256をパディングなしのbase64で続けたものです。
ウォレットは、それ以外のオリジンからのリクエストを拒否します。
`return_url`はありません。

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. ユーザー操作の中でウォレットに要求する**

レスポンスには`wallet_verification.interaction = "digital_credentials"`と`next_action.type = "request_digital_credential"`が含まれます。
開始時に指定した`origin`でのタップまたはクリックをきっかけに、`next_action.digital_credentials.request`をブラウザまたはAndroid Credential Managerに渡します。
デスクトップでは、ウォレットが別のデバイスにある場合、ブラウザが独自のQRコードを表示します。

**3. ウォレットが返した内容を送信する**

返された`{protocol, data}`をバックエンドに送り、そこから`{"response": {...}}`として`POST /v3/id-verification/wallets/verifications/{request_id}/response/`に送信します。
リクエストを送信できるのは1回のみです。2回目の送信では、すでに判定済みの認証が返されます。

**4. 結果を取得する**

送信に対するレスポンスは判定済みの認証です。
`GET /v3/id-verification/wallets/verifications/{request_id}/`で取得するか、完了Webhookで受け取ることもできます。

ブラウザでは、クリックハンドラーからウォレットに要求します。

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

この方式は、`"DigitalCredential" in window`がtrueの場合など、ブラウザが対応している環境でのみ提供してください。
`navigator.credentials.get`はユーザー操作の中で実行する必要があるため、非同期処理の後ではなく、クリックハンドラーから呼び出してください。

Androidでは、同じリクエストでJetpack Credential Manager（`androidx.credentials` 1.5.0以降）を使用します。

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

処理すべきエラー:

| エラー | 発生箇所 | 意味 |
| - | - | - |
| `origin_invalid` | 開始、`400` | `origin`がHTTPSオリジンでもAndroidアプリのオリジンでもありません。 |
| `origin_not_allowed` | 開始、`400` | オリジンのホストがアプリケーションに登録されていません。`allowed_return_hosts`に登録してください。 |
| `not_a_digital_credentials_wallet` | 送信、`409` | この認証はウォレットのレスポンスを受け付けません。 |

検証に失敗した資格情報は、エラーレスポンスではなく、結果が`failed`の判定済み認証になります。
ウォレットから送信されるのは認証が要求するフィールドのみで、結果にはウォレットが返した本人属性が含まれます。
Google WalletのIDパスや米国州のモバイル運転免許証は、顔写真を返しません。

サンドボックスアプリケーションでは、同じステップでフローがシミュレートされ、`simulated: true`が返されます。
送信されたレスポンスはいずれも`sandbox_scenario`に従って認証を判定するため、実際の資格情報がなくてもブラウザやアプリの一連の流れを構築できます。

## 完了Webhook

[Webhook連携ガイド](https://docs.didit.me/ja/integration/webhooks.md)に従って、`status.updated`用のアプリケーションのWebhookの送信先を設定してください。
ここで説明する判定の構造を使用するには、`webhook_version: "v3"`を使用してください。
処理する前に、バックエンドでWebhookの署名を検証してください。
Webhookの`session_id`は、ウォレットAPIが返す`request_id`と一致します。
完了したウォレット本人確認は、Webhookの`decision.id_verifications`配列に`verification_method: "wallet"`として含まれます。
この識別子を使用して、ウォレット専用APIの結果を取得することもできます。

承認と却下の通知を処理してください。キャンセルされた認証や期限切れの認証も含みます。
失敗した配信は再試行されるため、Webhookハンドラーは冪等にしてください。
ブラウザでの戻りは完了Webhookではなく、そのクエリパラメーターは本人確認の証拠にはなりません。

## 返される本人情報

氏名と生年月日については、正規化された本人情報フィールドが返される場合はそれを使用してください。
ウォレット固有の属性は、選択したウォレットが共有した本人情報を表します。
利用できる属性はウォレットと国によって異なります。
本人の認証が完了しても、顔写真、住所、その他要求したすべての属性が利用できるとは限りません。

## サンドボックスでのテスト

Didit のサンドボックスモードのアプリケーションは、ウォレットプロバイダーに接続することなく、またクレジットを消費することなく、ウォレット認証をシミュレートします。
これらのリクエストは、レスポンス内の`wallet_verification.simulated: true`で識別できます。
シミュレートされた承認はサンプルデータであり、実在の人物の本人確認が完了したことを示すものではありません。

リダイレクト型ウォレットの場合は、返されたURLにアクセスして、コールバックを実行し、アプリケーションに戻ります。
Smart-IDまたはMobile-IDの場合は、ポーリングエンドポイントを使用してシミュレートされた承認を完了します。電話への通知は送信されません。
失敗時の処理をテストするには、リクエストの開始時に`sandbox_scenario`を`wallet_cancelled`、`wallet_timeout`または`wallet_provider_error`に設定します。
本番環境のアプリケーションは`sandbox_scenario`を拒否します。

Didit のサンドボックスシミュレーションは、プロバイダー独自のテスト環境でのテストとは別のものです。
シミュレーションが成功しても、本番環境でプロバイダーにアクセスできることや、本番環境で利用できることが確認されたわけではありません。

### ConnectIDプロバイダーのサンドボックス

ConnectIDのプロバイダーサンドボックスはテスト用の銀行を使用し、Didit のサンドボックスシミュレーションとは別のものです。
連携に対してプロバイダーサンドボックスへのアクセスが設定されている場合は、選択した銀行の`authorisation_server_id`を[ConnectID開始エンドポイント](https://docs.didit.me/ja/api-reference/digital-id-wallets/connectid.md)に渡します。
ConnectIDの銀行選択画面から返されたIDを使用してください。銀行のURLや任意の発行者を送信しないでください。
このフィールドを省略すると、デフォルトのテスト用銀行が選択されます。
このフィールドはConnectID固有のものであり、要求する本人情報の属性は変わりません。

初期のバンドルでは、名、姓、生年月日を要求します。
返された`next_action`に従って認証を行い、その後に認証結果を取得またはポーリングします。
認証の成功を確定できるのは、ステータスが承認済みである完了した結果のみです。アプリケーションに戻ったことは認証の成功を意味しません。
ConnectIDは、オンボーディングと認定が完了するまで、本番環境では引き続き**Coming soon**となります。

## 提供状況と料金

エンドポイントの対応範囲と、本番環境でのウォレットの有効化は別のものです。
APIリファレンスのページがあるウォレットでも、本番環境の認証にはまだ利用できない場合があります。
本番環境のフローを実装する前に、ウォレットの対応国と本番環境での提供状況を確認してください。

公開されている料金と提供状況については、[デジタルIDウォレットの料金](https://docs.didit.me/ja/getting-started/pricing.md#デジタルidウォレットの料金)を参照してください。
ウォレット認証は、書類の撮影とは別に請求されます。

## 連携方法の選択

周辺のインターフェースとアプリケーションのロジックを自社で管理したい場合は、これらのAPIを使用します。
Didit のホスト型の認証フロー、ワークフローのルール、設定済みのフォールバックステップを利用したい場合は、[Sessions API](https://docs.didit.me/ja/sessions-api/create-session.md)を使用します。
どちらの方法でも、ウォレットの認証と同意のプロセスは必要です。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.