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

# 携帯番号三要素確認 API 接続説明

> Identity Authentication 集成指南 - XHuoAPI

本文では、携帯番号三要素確認 API 接続説明について紹介します。これは、携帯番号、氏名、及び身分証明書番号の真実性と一貫性を確認するために使用できます。

## 申請プロセス

API を使用するには、まず [携帯番号三要素確認 API](https://api.xhuoapi.ai/documents/b4c50108-dda5-4ddb-ba84-776060fb0151) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

![](https://cdn.xhuoapi.ai/q6ytrc.png)

まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料の利用枠が付与され、この API を無料で使用できます。

## 基本使用

まず、基本的な使用方法を理解します。携帯番号を入力することで、処理された結果を得ることができます。最初に `phone` フィールドを簡単に渡す必要があります。次に、画面上に対応する内容を記入できます。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/3xbffj.png" width="500" className="m-auto" />
</p>

ここでは、リクエストヘッダーを設定しました。内容は以下の通りです：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

また、リクエストボディを設定しました。内容は以下の通りです：

* `name`：処理するユーザーの氏名。必須パラメータです。
* `phone`：処理する携帯番号。必須パラメータです。
* `id_card`：処理するユーザーの身分証明書番号。必須パラメータです。
* `verify_mode`：確認モード（長版/短版）。
* `encrypt_list`/`ciphertext_blob`/`iv`：必要に応じて機密フィールドを暗号化するためのオプションの暗号化パラメータ。

選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/0cp9z1.png" width="500" className="m-auto" />
</p>

「Try」ボタンをクリックするとテストが行えます。上の図のように、以下の結果が得られました：

```json theme={null}
{
  "result": "0",
  "description": "認証通過",
  "isp": "移動",
  "result_detail": null
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `result`、認証結果コード。料金の状況は以下の通りです。
  * 有料結果コード：
    * 0: 検証結果一致
    * 1: 検証結果不一致
  * 無料結果コード：
    * -1: 記録なし
    * -2: エンジン未知のエラー
    * -3: エンジンサービス異常
    * -4: 氏名確認不通過
    * -5: 携帯番号不合法
    * -6: 認証回数が当日の制限を超えました。翌日再試行してください。
* `description`、業務結果の説明。

携帯番号、氏名、及び身分証明書番号の真実性と一貫性の情報がすでに照会されていることがわかります。

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/identity/phone/check-3e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "name": "***",
  "phone": "***",
  "id_card": "***"
}'
```

Python の接続コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/identity/phone/check-3e"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "name": "***",
    "phone": "***",
    "id_card": "***"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 token_mismatched`：不正なリクエスト、パラメータが欠落または無効な可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが欠落または無効な可能性があります。
* `401 invalid_token`：未承認、無効または欠落した認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、携帯番号三要素確認 API を使用して携帯番号、氏名、及び身分証明書番号の真実性と一貫性を確認する方法を理解しました。この文書が、API の接続と使用をより良くする手助けとなることを願っています。何か問題があれば、いつでも技術サポートチームにお問い合わせください。