# Интеграция со сторонними 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"** .
Пример запроса показан на иллюстрации ниже.
### Как сохранять значения из переменных
С первого раза это может быть не совсем понятно — здесь действительно нужно попробовать самостоятельно.
Сначала в поле "Answer" введите #{custom\_answer}. (Переменная #{custom\_answer} содержит ответ, полученный от сервера, указанного в поле "Response URL".)
Запустите блок запроса, чтобы отправить запрос и получить ответ. Полученный ответ нужно проанализировать, и нужно настроить, какие переменные извлекать из него. Для этого используйте поле "Saved Values".
Разберём пример, описанный выше.
Лучше всего понять, как обращаться к данным в JSON, на примере. В результате нашего запроса ответ, полученный в #{custom\_answer}, выглядит так:
`{
"suggestions": [
{
"value": "US Dollar",
"unrestricted_value": "US Dollar",
"data": {
"code": "840",
"strcode": "USD",
"name": "US Dollar",
"country": "United States"
}
}
]
}`
В поле "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, параметры можно передавать только в теле запроса. Для параметров JSON POST появится дополнительное поле.
**Важно!** Параметры должны быть записаны только в формате 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/ru/rabota-s-api/integraciya-so-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.