# Інтеграція зі сторонніми API
Ви можете створювати ботів, які взаємодіють з іншими сервісами через API. Наприклад, боти можуть надсилати запити, щоб перевірити доступність на певну дату або знайти товар в інтернет-магазині.
## Як взаємодіяти зі сторонніми API на прикладі Dadata
Візьмімо як приклад API підказок адреси: **ссылка будет другая**
{% hint style="info" %}
Уважно читайте документацію сторонніх API.
{% endhint %}
{% hint style="warning" %}
Зверніть увагу! Сторонні API вимагають IP-адреси, з яких надсилатимуться запити: 158.160.49.208 – сайт.
{% endhint %}
У полі «Request URL» введіть `https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address`.
У **«Request header»** у полі введіть заголовок у форматі JSON: `{"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}`.
У **«JSON parameters»** у полі введіть сам запит: `{"query": "#{CurrencyType}"}`.
Щоб отримати результат запиту, заповніть **«Saved values»** .
Приклад запиту показано на ілюстрації нижче.
### Як зберігати значення з змінних
З першого разу може бути не зовсім зрозуміло — тут справді потрібно спробувати самому.
Спочатку введіть #{custom\_answer} у полі «Answer». (Змінна #{custom\_answer} містить відповідь, отриману із сервера, вказаного в полі «Response URL».)
Запустіть блок запиту, щоб надіслати запит і отримати відповідь. Отриману відповідь потрібно проаналізувати, і слід налаштувати, які змінні з неї витягнути. Для цього використовуйте поле «Saved Values».
Розберімо описаний вище приклад.
Найкраще зрозуміти, як звертатися до даних у JSON, можна на прикладі. У результаті нашого запиту відповідь, отримана в #{custom\_answer}, виглядає так:
`{\r"suggestions": [\r{\r"value": "US Dollar",\r"unrestricted_value": "US Dollar",\r"data": {\r"code": "840",\r"strcode": "USD",\r"name": "US Dollar",\r"country": "United States"\r}\r}\r]\r}`
У полі «Saved values» введіть VALUE -> VARIABLE:
`suggestions|0|value->CurrencyType;` \
`suggestions|0|data|code->CurrencyDigCode;` \
`suggestions|0|data|strcode->CurrencyStrCode;` \
`suggestions|0|data|country->CurrencyCountry`
**suggestions -** ключ для масиву \[{"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]
**suggestions|0** - ключ для першого елемента масиву {"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}
**suggestions|0|value** - ключ для значення "US Dollar"
Найдовший ключ у цьому JSON:
**suggestions|0|data|strcode** - ключ для значення "USD"
{% hint style="success" %}
Ключі розділяються вертикальною рискою (|). Якщо елемент JSON є масивом, доступ до його елементів здійснюється за індексом, починаючи з 0, і це також записується через вертикальну риску.
{% endhint %}
{% hint style="info" %}
Потрібно повторити всю вкладеність. Для зручності ви можете візуалізувати JSON за допомогою застосунку JSON viewer.
{% endhint %}
Рівень вкладеності розділяється вертикальною рискою. Тобто потрібно перелічити всі ключі, щоб дійти до значення, розділяючи їх вертикальною рискою.
{% hint style="info" %}
Якщо JSON містить масив, замість ключа використовуйте індекс елемента, починаючи з нуля.
{% endhint %}
Вирази для отримання наших змінних розділяються крапкою з комою ;.
Кожен вираз складається зі шляху до даних у відповіді та назви змінної, у яку їх потрібно зберегти, розділених ->.
Пошуковий запит являє собою шлях у JSON до потрібного значення.
### Розробка API для ботів
Бот підтримує GET- і POST-запити, які є основними типами, що використовуються в більшості публічних API.
**GET** — це запит, який відбувається, коли ви натискаєте на посилання або відкриваєте URL у браузері. Параметри в цьому запиті передаються в URL.
Синтаксис передавання параметрів: після URL поставте знак питання ?, потім розділіть кожен параметр амперсандом &. Кожен параметр складається з назви, за якою йде = та його значення.
Приклад URL із параметром:
Тут передається один параметр q зі значенням «good music». %20 означає пробіл.
Під час роботи з конструктором ви можете просто використовувати пробіл — бот автоматично його замінить.
**POST** — це запит, який найчастіше надсилається під час заповнення форми на сайті. Параметри надсилаються в тілі запиту. Хоча їх також можна передавати в URL, як у GET-запитах, це трапляється рідко. Параметри в тілі можуть бути у форматі JSON або у вигляді пар ключ-значення. Форми зазвичай надсилають пари ключ-значення, тоді як API найчастіше використовують JSON.
**Заголовок запиту** — можна додати заголовок до кожного запиту. Найчастіше він визначає формат даних і ключі доступу. Зазвичай це поле лишають порожнім, але в рідкісних випадках потрібно вказати API-токен або тип запиту, наприклад: "Content-Type": "application/json".
**JSON** (JavaScript Object Notation, зазвичай вимовляється /ˈdʒeɪsən/ JAY-sən) — це текстовий формат обміну даними, заснований на JavaScript. Як і багато інших текстових форматів, JSON легко читається людиною. Для роботи з API в боті потрібно розуміти цей формат, оскільки саме він лежить в основі всієї взаємодії.
Перш ніж продовжити, прочитайте такі статті:
\
Також спробуйте створити власний JSON-файл на цьому сайті:
**Практика**
Запити можуть виконуватися блоками та умовами. Умовні запити призначені для перевірки того, чи може діалог піти певною гілкою на сайті. У цьому випадку запит надсилається щоразу, коли перевіряється умова гілки. Запити в блоках, навпаки, виконуються лише тоді, коли діалог переходить у цей стан.
Перед створенням запиту потрібно обрати його тип:
POST-data і POST-JSON відрізняються способом передавання параметрів, як згадувалося раніше (або у форматі JSON, або у вигляді пар ключ-значення). Якщо ви обираєте JSON, параметри можна надсилати лише в тілі запиту. Для параметрів POST у форматі JSON з'явиться додаткове поле.
**Важливо!** Параметри потрібно писати лише у форматі JSON, оскільки бот працює виключно з ним. Ви вже практикувалися у написанні JSON.
Відповідь від сервера можна розібрати та зберегти у змінні.
{% hint style="info" %}
Розбирати відповідь можна лише якщо вона у форматі JSON.
{% endhint %}
Збережені змінні записуються в останній незаповненій формі. Якщо форма відправляється через червоний блок, змінні скидаються. Тому, якщо вам потрібно зберегти ці дані, передайте змінні до CRM-системи через жовтий блок.
Також ви можете побачити, що бот записав у змінні, у розділі «Leads».
### Передавання змінних не як рядка
За замовчуванням значення змінних мають бути рядками у форматі "#{}", але в цьому випадку змінна надсилається як рядок. Щоб передати змінну як число, потрібно вимкнути перевірку формату параметрів у налаштуваннях проєкту:
Тоді ви можете просто використовувати ім'я змінної, наприклад: `{"key": #{variable_name}}`, де variable\_name — це сама змінна, без лапок навколо.
{% hint style="warning" %}
Після налаштування параметрів рекомендується знову увімкнути перевірку формату.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mavibot.ai/doc/uk/robota-z-api/integraciya-zi-storonnimi-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.