> ## 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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.