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

# Інструкція з інтеграції Short URL API

> Short link generation 集成指南 - XHuoAPI

У цьому документі буде представлено інструкцію з інтеграції Short URL API, яка дозволяє перетворювати довгі URL на короткі.

## Процес подачі заявки

Щоб використовувати API, спочатку потрібно перейти на відповідну сторінку [Short URL API](https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9) для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку:

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

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку.

При першій подачі заявки буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

## Основне використання

Спочатку потрібно ознайомитися з основним способом використання, а саме, ввести довгий URL, який потрібно перетворити, і ви отримаєте оброблений результат. Спочатку потрібно просто передати поле `content`. Далі ми можемо заповнити відповідний вміст на інтерфейсі, як показано на малюнку:

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

Ми бачимо, що тут ми налаштували заголовки запиту, включаючи:

* `accept`: вкажіть, у якому форматі ви хочете отримати відповідь, тут вказано `application/json`, тобто формат JSON.
* `authorization`: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.

Також налаштовано тіло запиту, яке включає:

* `content`: вміст URL, який потрібно скоротити.

Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

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

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат:

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://surl.id/1uHCs01xa5"
  }
}
```

У повернутому результаті є кілька полів, описаних нижче:

* `success`: статус успішності виконання завдання.
* `data`: містить перетворений URL.

Можна побачити, що спочатку довгий URL `https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9` успішно перетворено на короткий URL `https://surl.id/1uHCs01xa5`.

Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/shorturl' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "content": "https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9"
}'
```

Код інтеграції на Python виглядає так:

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/shorturl"

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

payload = {
    "content": "https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9"
}

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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Висновок

Завдяки цьому документу ви дізналися, як використовувати Short URL API для перетворення довгих URL на короткі. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.