# Інтеграція зі сторонніми API Ви можете створювати ботів, які взаємодіють з іншими ресурсами через API. Наприклад, боти можуть обробляти запити з можливістю перевірити, чи можна створити запис на певну дату, або знайти товар в інтернет-магазині. ## Як обробляти стороннє API на прикладі DaData Давайте візьмемо поради щодо API з [https://dadata.ru/api/suggest/address ](https://dadata.ru/api/suggest/address)як приклад {% hint style="info" %} Уважно прочитайте документацію сторонніх API {% endhint %} Відкрийте свій проєкт у Salebot і відкрийте розширені налаштування в налаштуваннях блоку; там потрібно змінити тип запиту на POST-json. У полі “**URL запиту**” введіть таку URL-адресу: h У полі “**Заголовок запиту**” введіть заголовок у JSON-форматі: { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token } У полі «**JSON-параметри**” вставте сам запит - { "query": "#{CurrencyType}" } Щоб отримати результати, вам також потрібно заповнити вкладку “**Збережені значення**”. Нижче наведено приклад запиту: ![](https://lh3.googleusercontent.com/QV4ldVY9n1AFFCr2jn1NQU_hZe7Iug-Xh5d4KLWtAZNQEyQ9WPLu1mV7mPcFjfjAKaPGO2Wi148J4AAF3kmU0wmhLYwBy6LgDXbFRgteh0Nrtu29LhqSgTg6d14Ts8pvanwWUJQAVTUThYp6Lg) ### Як зберігати значення з змінних Не всі розуміють це одразу, доки не спробують зробити це самі. Спочатку введіть #{custom\_answer} у полі відповіді. (Змінна #{custom\_answer} містить відповідь, отриману від сервера, про який згадувалося в полі “URL для відповіді від сервера”) Запустіть блок із запитом, щоб надіслати запит і отримати на нього відповідь. Вам потрібно проаналізувати відповідь і налаштувати доступ до змінних у ній. Для цього потрібно працювати з вкладкою “Збережені значення”. Давайте розглянемо приклад, щоб краще зрозуміти процес. У результаті нашого запиту #{custom\_answer} надійшла відповідь у такому форматі: `{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}` Тепер запишемо в полі “Збережені значення” наш VALUE->VARIABLE `suggestions|0|value->CurrencyType;` \ `suggestions|0|data|code->CurrencyDigCode;` \ `suggestions|0|data|strcode->CurrencyStrCode;` \ `suggestions|0|data|country->CurrencyCountry` **suggestions** - ключ масиву \[{"value": "British pound", "unrestricted\_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}] **suggestions|0** - ключ першого елемента в масиві {"value": "British pound", "unrestricted\_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}} **suggestions|0|value** - ключ до значення “British pound” Найдовший ключ у цьому JSON: **suggestions|0|data|strcode** - ключ до значення “GBP” {% hint style="success" %} Ключі розділяються вертикальною рискою (|). Якщо в JSON є масив, то доступ до його елемента нумерується, починаючи з 0, і також записується через вертикальну риску. {% endhint %} {% hint style="info" %} Потрібно повторити всю вкладеність. Для зручності можна візуалізувати JSON у застосунку JSON-viewer. {% endhint %} Рівні вкладеності розділяються вертикальними рисками. Тож вам потрібно перелічити всі ключі, розділені рискою, щоб дістатися до значення. {% hint style="info" %} Якщо в JSON є масив, то замість ключа потрібно вказати номер елемента, починаючи з 0. {% endhint %} Окремі фрази отримання змінних відокремлюються символом крапки з комою (;). Фрази складаються з посилання на дані у відповіді та назви змінної, у яку їх зберегти, які розділяються символами -> (тире + кутова дужка). Пошуковий запит — це, певною мірою, шлях у JSON до потрібного значення. ### Розробка API для ботів Щоб розробити API, вам знадобиться хостинг, на якому він буде базуватися. Якщо у вас його немає або ви не сильні в програмуванні, то можете звернутися до нас, і ми розробимо API для вашого бота та розмістимо його на нашому хостингу. Сам хостинг безкоштовний, ви платитимете лише за розробку. #### Але поки що трохи теорії. Бот підтримує **GET** та **POST** запити, це основні типи, які використовуються в більшості публічних API. **GET** — це запит, який відбувається під час натискання на посилання або при відкритті посилання в браузері. Параметри в такому запиті передаються в URL-запитах. Синтаксис переданих параметрів: після URL іде знак питання (?) , потім кожен параметр відокремлюється амперсандом (&). Параметр складається з назви та його значення після знака дорівнює (=). Приклад URL з параметром: ![](https://lh6.googleusercontent.com/c4xJMMuFKVsFJW_3nDTzUmhvejIUtIKsg-kEA8_PT05vlmmAfDgritAtxwh_5sq3-YwOuy8dw4LVYbesWa4Yy-QjUx3gIbF-54_omadX1SFFaa8K6HirvD-qycd4D6tjSBpkRLAB) Тут ви бачите, що передається один параметр з назвою “search\_query”, а його значення — “queen live aid”. Знак ‘+’ тут означає пробіл між словами; під час роботи в редакторі ви можете просто залишати пробіли — бот сам їх замінить. **POST** — це тип запиту, який найчастіше надсилається під час заповнення форми на сайті. Запит передає параметри в тілі; звісно, їх можна передавати так само, як і в GET, але так роблять рідко. Параметр у тілі може бути у JSON-форматі або як ключ-значення. У форматі ключ-значення параметри передаються у формах, а JSON-формат найчастіше використовується для API. **Заголовок запиту.** Кожен запит може мати доданий заголовок/титул. Найчастіше в ньому записуються формат переданих даних і ключі доступу. Зазвичай ми залишаємо цю вкладку порожньою, але іноді потрібно вказати API Token або тип запиту “Content-type”: “application/json”. **JSON** — (JavaScript Object Notation) — це відкритий стандартний формат файлів і формат обміну даними, який використовує зрозумілий людині текст для зберігання й передачі об’єктів даних, що складаються з пар атрибут–значення та масивів. Щоб працювати з API в ботах, вам потрібно знати цей формат, усе на ньому базується. Перш ніж продовжити, прочитайте такі статті: [https://www.json.org/json-en.html ]()\ А також спробуйте створити власний JSON-файл на цьому сайті: #### Практика Блоки та умови можуть обробляти запити. Запити умов створюються для того, щоб зрозуміти на сайті, чи може діалог піти певним шляхом, чи ні. Запит у цьому випадку відбувається щоразу, коли перевіряється умова шляху. На відміну від цього, запити блоків запускаються лише тоді, коли відбувається перехід у блок. Перш ніж створювати запит, потрібно вибрати його тип: ![](https://lh5.googleusercontent.com/jDLVxBLwNSrmSb9t6LTuwuuifA3X-U9PNhLi7YvCrLj36uyDjiP-FymTpUXg1fhSewb63UslJbHhndLsefusieLdYSe4oNWMBGWuceHWWNg5VrRddIHXbGVwqhDMFFUR5Xk4YZLYXfM2hcNP9w) POST-data і POST-json відрізняються способом передачі параметрів, як зазначено вище (JSON-формат або як ключ-значення). Якщо ви обираєте JSON, то параметри можуть передаватися лише в запиті. Для post відкривається додаткове поле: JSON POST-параметри. **Важливо!** Параметри мають бути записані лише у JSON-форматі, бот працює тільки так. Відповідь від сервера можна розібрати та зберегти у змінні. {% hint style="info" %} Розібрати відповідь можна лише якщо вона у JSON-форматі. {% endhint %} Збережені змінні записуються в останнє незаповнене надсилання; якщо надсилання передається через червоний блок, змінні скидаються. Тож якщо вам потрібно зберегти дані, потрібно передавати змінні через жовтий блок. До речі, ви можете подивитися, що бот записав у змінні, у розділі Leads: ![](https://lh3.googleusercontent.com/e6mzwKUgxl22YqWNmN3HI0afQKM8gcU2OR_E_7Q3NSEzx0n45QLGXI4_UsaWaK52z7-QnULWmfSqCeZhfStALhung9LpFoK2i9EGhNccUcgo-E-7ONrkb7Aj2GEzd0DMDTxLsviV) ### Передача даних не у вигляді рядка За замовчуванням значення змінної надходить у форматі #{} , але потім воно приходить як рядок. Щоб змінна передавалася як число, потрібно вимкнути перевірку формату параметрів post-json. ![](https://lh4.googleusercontent.com/KDDSAYd7NeXu0c7jL45ktnPPeWy7G_YJS-xrf1jvAXf1aKYKGh781E1oGmnS8fw0PbpynqG0lXyqZwK_RfuCC3ezal4-Iu0lo7y5zsNQUT6i21J4C2hb9xw6DF30wReKLorcLliS) Тоді ви можете просто вказати назву змінної, наприклад {"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/integrations/api/request.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.