> ## 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.

# 電話番号認証の警告とリスクコード

> Didit電話番号認証の全リスクコードのリファレンス：HIGH_RISK_PHONE_NUMBER、VOIP_NUMBER_DETECTED、DISPOSABLE_NUMBER_DETECTED、ブロックリスト、OTP試行回数の上限。

電話番号検証機能は、OTPフローまたは電話番号自体でリスクシグナルが発生するたびに**警告**を出力します。対象となるのは、既知の不正な番号、VoIP回線や使い捨て回線、OTP試行回数の上限、他のユーザーのセッションとの一致などです。このページでは、すべてのコード、その発生条件、ワークフローでの対応の設定方法を説明します。

## 概要

警告には機能`PHONE`のタグが付けられます。警告は`GET /v3/session/{sessionId}/decision/`の`phone_verifications[].warnings[]`に含まれ、標準の[警告オブジェクト](https://docs.didit.me/ja/reference/data-models.md#警告オブジェクト)の形式（`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`）に従います。各警告はセッションごとのログにも記録されるため、Business Consoleの電話番号セクションにも表示されます。

一部の警告は**無条件の自動却下**のトリガーであり、常に機能のステータスを`Declined`に設定します。それ以外の警告は、ワークフロー設定で定義する**設定可能なアクション**（設定に応じて`DECLINE`、`REVIEW`、`NO_ACTION`）に対応します。そのため、同じリスクコードでも、あるワークフローでは却下となり、別のワークフローではフラグが付くだけ、ということがあります。

## 自動却下の条件

以下の警告は、設定にかかわらず常に電話番号検証ステップを却下し、常に`log_type: "error"`が付きます。

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`：ユーザーがOTPの試行回数上限に達しました。デフォルトでは、誤ったコードの送信が2回（`phone_max_check_attempts`）、またはOTPの送信が2回を超えた場合（`phone_max_retries`）で、いずれもワークフローノードごとに調整できます。スタンドアロンの電話番号APIでは、コードを3回まで試行できます。
* `PHONE_NUMBER_IN_BLOCKLIST`：番号が[Lists API](https://docs.didit.me/ja/management-api/lists/overview.md)で管理するブロックリストに含まれているか、ブロックリストに登録されたセッションと一致しています。

`HIGH_RISK_PHONE_NUMBER`（配信プロバイダーの不正防止レイヤーによりOTPの送信が拒否され、送信が`Blocked`となった場合）は、デフォルトでは却下となりますが、**現在は無条件ではありません**。後述の[`high_risk_phone_action`](#ブロックされた送信)を参照してください。

## 設定可能なリスク

以下の各リスクは、`DECLINE`、`REVIEW`、`NO_ACTION`（デフォルト。警告は記録されますが、ステータスには影響しません）のいずれかに設定できるワークフロー設定に対応しています。設定したアクションによって、警告の`log_type`も決まります：`DECLINE` → `error`、`REVIEW` → `warning`、`NO_ACTION` → `information`。

| 設定 | リスクコード | 発生条件 |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | キャリア情報から、回線種別が`voip`、`isp`、`vpn`のいずれかと判定された場合。 |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | ルックアップにより、その番号が一時的な番号または使い捨て番号のプロバイダーのものと判定された場合。 |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | 番号が、別のエンドユーザーに属する他のセッション（ステータスを問わない）と一致した場合。番号が許可リストに登録されている場合はスキップされます。 |

重複検出は、アプリケーション内のKYC、KYB、スタンドアロンAPIによる電話番号検証を横断して実行され、セッションを`vendor_data`でグループ化します。同じ`vendor_data`を共有するセッションは同一のエンドユーザーとして扱われ、一致結果から除外されます。`vendor_data`を空のままにすると、すべてのセッションがそれぞれ別のユーザーとして扱われます。

### ブロックされた送信

`HIGH_RISK_PHONE_NUMBER`も同じパターンに従いますが、プロバイダーが拒否した送信は承認できないため、選択肢がより限られます。

| 設定 | リスクコード | 発生条件 |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | 配信プロバイダーの不正防止レイヤーがOTPの送信を拒否した場合（`Blocked`送信）。`DECLINE`または`REVIEW`のみ指定でき、デフォルトは`DECLINE`です。 |

この設定は、**そのステップのすべての高リスクブロックの`additional_data.risk_factors`が厳密に`["device_attribute"]`である場合にのみ**適用されます。これはプロバイダーの「このデバイスは疑わしい」というシグナルで、通常のモバイル回線で発生するものです。それ以外のリスク要因、`device_attribute`を含むだけの組み合わせ、またはリスク要因がまったくないブロックの場合は、設定にかかわらず却下されます。ブロック理由（`repeated_attempts`、`suspicious`、`spam`）は別のフィールドで、`additional_data.blocked_reason`で返されます。

この設定とは関係なく、[Lists API](https://docs.didit.me/ja/management-api/lists/overview.md)で作成した電話番号の許可リストに含まれる番号は、ブロックされた送信を理由に自動却下されることはありません。その場合、ステップは**レビュー中**になり、警告には`log_type: "warning"`が付き、`additional_data.phone_number_in_allowlist`は`true`になります。

## 認証試行回数の上限

電話番号検証機能では、不正利用を防ぐためにOTPの試行回数に厳格な上限を設けています。

* **コード入力の試行回数**：デフォルトでは誤った入力が**2**回（`phone_max_check_attempts`）に達すると、ステップは`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`とともに`Declined`として確定します。スタンドアロンの電話番号APIでは、認証1件あたり**3**回までコードを入力できます。
* **送信回数**：デフォルトでは合計**2**回（`phone_max_retries`）で、初回送信と1回の再送信です。それ以上の送信リクエストがあるとステップが確定し、`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`が発生します。
* **OTPの有効期間**：保留中のOTPは**初回送信から5分間**有効です。再試行しても有効期間は延長されません。

どちらの上限もワークフローのノードごとに調整できます。これらの上限とは別に、配信プロバイダーの不正防止レイヤーが送信そのものをブロックすることがあります（理由は`repeated_attempts`、`suspicious`、`spam`のいずれか）。その場合に発生するのは`HIGH_RISK_PHONE_NUMBER`であり、試行回数の警告ではありません。

## 生成される警告

| タグ | `log_type` | 説明 |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error`（常時） | ユーザーがOTPのコード入力または送信の上限を超えました。自動的に却下されます。 |
| `HIGH_RISK_PHONE_NUMBER` | `high_risk_phone_action`に従う（許可リストに登録済みの場合は`warning`） | 配信プロバイダーがOTPの送信をブロックしました。デフォルトでは却下されます。デバイスシグナルのみによるブロックを代わりにレビュー中に回すには、`high_risk_phone_action`を`REVIEW`に設定します（[ブロックされた送信](#ブロックされた送信)を参照）。電話番号の許可リストに登録された番号もレビュー中になります。`additional_data`：`{ blocked_reason, risk_factors, phone_number_in_allowlist? }`。 |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error`（常時） | 番号が[Lists API](https://docs.didit.me/ja/management-api/lists/overview.md)で作成したブロックリストに含まれているか、ブロックリストに登録されたセッションと一致しています。自動的に却下されます。`additional_data`：`{ blocklisted_session_id, blocklisted_session_number, api_service }`（リストへの一致のみの場合はすべて`null`）。 |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | 番号が他のセッションと一致しましたが、[Lists API](https://docs.didit.me/ja/management-api/lists/overview.md)で作成した許可リストに含まれているため、重複電話番号のアクションはスキップされます。`additional_data`：`{ phone_number }`。 |
| `DISPOSABLE_NUMBER_DETECTED` | `disposable_number_action`に従う | 番号が、追跡を回避する目的でよく使われる一時的な使い捨て番号のプロバイダーのものです。 |
| `VOIP_NUMBER_DETECTED` | `voip_number_action`に従う | 番号が標準的な携帯電話回線や固定回線ではなく、`voip`、`isp`、`vpn`のいずれかの回線と判定されました。 |
| `DUPLICATED_PHONE_NUMBER` | `duplicated_phone_number_action`に従う | 番号が、別のエンドユーザー（`vendor_data`でグループ化）に属する他のセッション（ステータスを問わない）と一致しています。`additional_data`：`{ duplicated_session_id, duplicated_session_number, api_service }`。 |

## セッション間の一致

番号が他のセッションまたはブロックリストで検出された場合、それらの一致は`phone_verifications[].matches[]`にも表示されます（最大5件）。各一致には`session_id`、`session_number`、`vendor_data`、`verification_date`、`phone_number`、`status`、`is_blocklisted`、`api_service`に加えて、`session`（同じ番号を持つ他のセッション、ステータスは問わない）または`list_entry`（配列の先頭に追加される合成のブロックリスト一致）のいずれかを値とする`source`が含まれます。現在の番号が電話番号の許可リストに登録されている場合、Diditは一致の証跡を保持しますが、重複電話番号のアクションを適用する代わりに`PHONE_NUMBER_IN_ALLOWLIST`を返します。一致の完全なスキーマについては、[電話番号検証レポート](https://docs.didit.me/ja/core-technology/phone-verification/report-phone-verification.md#セッション間の一致)を参照してください。

## 例

`voip_number_action`を`REVIEW`に設定した状態で、VoIP番号への送信がブロックされる（`HIGH_RISK_PHONE_NUMBER`）例です。

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## 警告の種類

各リスクには、アプリケーションの設定に基づいて重大度が割り当てられます。重大度は次の3つのカテゴリに分類されます。

## 関連ページ

* [電話番号検証の概要](https://docs.didit.me/ja/core-technology/phone-verification/overview.md)：機能の動作、料金、対応チャネル。
* [電話番号検証レポート](https://docs.didit.me/ja/core-technology/phone-verification/report-phone-verification.md)：`lifecycle[]`と`matches[]`を含むレスポンスの完全な構造。
* [データモデル：電話番号検証](https://docs.didit.me/ja/reference/data-models.md#電話番号検証)：フィールドごとの正規スキーマ。
* [Management API：Lists](https://docs.didit.me/ja/management-api/lists/overview.md)：`PHONE_NUMBER_IN_BLOCKLIST`で使用される電話番号のブロックリストを管理します。


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