Интеграции

Заявки, файлы и перенос

Обновлено 25 октября 2026

Создание заявки

requests_create_request требует form_id и объект fields. Для файлов используется отдельный аргумент files. Перед записью получите структуру формы через requests_get_form.

Создание проходит полный конвейер приложения: обязательные поля проверяются, контакт подбирается по правилам формы, вызываются хуки. Уведомления зависят от настройки плагина. Подключённые плагины приложения «Заявки» могут создать связанные сделки, тикеты или заказы.

Аргумент MCP	Назначение
`contact_id`	Явная привязка к контакту; требуется доступ пользователя к контактам
`no_contact`	`true` — не искать и не создавать контакт; по умолчанию `false`
`created`	Дата заявки в формате `YYYY-MM-DD HH:MM:SS`; без неё используется текущий момент
`status_id`	Статус при создании; неизвестный идентификатор приводит к начальному статусу и предупреждению
`allow_closed_form`	`true` разрешает создание в выключенной форме или вне периода приёма; по умолчанию `false`. Для посетителей форма от этого не открывается

contact_id и no_contact: true нельзя использовать вместе. Если оба режима не заданы, контакт подбирается по email и телефону согласно настройкам формы. Пользователь токена автоматически контактом заявки не становится. При несуществующем явном contact_id заявка создаётся без контакта, а ответ содержит предупреждение.

Обычное создание не защищено от повторов: повторный вызов создаёт ещё одну заявку. Для переноса используйте импорт с external_id.

Изменение существующей заявки

requests_update_request принимает request_id и только то, что нужно изменить: fields, status_id, created, contact_id или files. Непереданные значения сохраняются. contact_id: null отвязывает контакт; смена привязки не переписывает значения полей.

Правка проверяет затронутые поля и вызывает хуки обновления и смены статуса. Уведомления при правке не отправляются. requests_update_status использует тот же путь обновления для одного статуса. При этом значения полей сохраняются заново целиком, хотя сами значения при смене статуса не меняются.

Открой указанную заявку и покажи её текущие значения.
Исправь только согласованный мной телефон и переведи в выбранный статус.
После изменения покажи карточку повторно.

Вложения

Вложение передаётся объектом с ровно одним источником:

Источник	Условия
`url`	Публичная ссылка HTTP(S); скачивание выполняется через защиту приложения MCP от запросов в локальные и частные сети. До 20 МиБ на файл
`content_base64`	Содержимое в base64, до 500 КиБ после декодирования; обязателен `name` с расширением
`file_path`	Существующий файл на сервере внутри каталога загрузок MCP `wa-data/protected/mcp/upload-staging`; до 20 МиБ. Это не путь на компьютере пользователя

Для ссылки и серверного пути имя можно передать в name; иначе оно определяется по адресу или пути. Имя должно содержать расширение. Пути из /tmp и остальных каталогов wa-data не принимаются.

Общий предел плагина — 20 файлов на заявку за вызов. Дополнительно приложение проверяет расширение, размер и количество по правилам конкретного поля. Они могут быть строже общих пределов.

При создании и импорте files содержит пары «поле — список объектов файлов», даже если файл один. Ключом служит идентификатор либо однозначное имя поля.

При правке формат другой: files.add содержит добавляемые файлы, files.remove — списки удаляемых path по полям. Путь берите из requests_get_request. Снятие удаляет файл с сайта и требует confirm: true; неизвестный путь возвращает not_found. Количество файлов проверяется с учётом уже имеющихся.

Файлы заявки получают публичные ссылки, которые доступны агенту в карточке. Учитывайте это при выборе вложений.

Перенос заявок пачками

requests_import_requests принимает одну форму form_id и массив requests из 1–50 записей. Каждая запись требует external_id и fields; также поддерживает дату, статус, контакт и файлы.

Используйте стабильный идентификатор с обозначением источника, например old-crm:12345. Повтор с тем же external_id в той же форме возвращает существующую заявку со статусом exists, а не обновляет её. В другой форме это другая пара идентификаторов.

Перенеси подготовленные записи в выбранную форму пачками не больше 50.
Используй исходные идентификаторы с префиксом источника как external_id.
Контакты не создавай. Покажи результат по каждой записи и все предупреждения.

Верхний no_contact: true действует на записи без своего contact_id. Значения no_contact: false и null в записи не отменяют этот общий режим. Если нужно включить автоподбор для отдельных записей, отправьте их отдельным вызовом без общего запрета.

При импорте уведомления всегда отключены, но хуки приложения срабатывают. Ошибка одной записи не останавливает остальные. Проверяйте results, created_count, exists_count, failed_count, а также предупреждения:

Результат записи	Что делать
`created`	Запись создана; сохраните `request_id` и проверьте `warning`
`exists`	Уже перенесена раньше; существующая заявка не переписана
`failed`	Изучите `error_code` и `error_message`
Ошибка `busy`	Запись переносится другим вызовом; повторите позже
`created` с `created_with_error`	Заявка есть, но после создания возникла ошибка; откройте её по `request_id`
`external_id_saved: false` и предупреждение о несохранённом идентификаторе	Заявка есть; эту запись не повторяйте, иначе возможен дубль

Плагин принимает подготовленные записи. Самостоятельных инструментов чтения отзывов из 2ГИС, Авито или Яндекс.Карт в нём нет. Публикация перенесённых отзывов зависит от отдельного расширения для отзывов и не входит в эти 34 инструмента.

Статистика и CSV

requests_get_stats принимает фильтр формы и период. Первый статус по порядку считается «новым», остальные — «обработанными». Доля обработанных — отношение числа заявок в остальных статусах к общему числу, а не проверка фактической работы сотрудника.

Особенности текущего расчёта:

today_new считает заявки за сегодня, заменяя переданный период сегодняшней датой;
total_forms и active_forms относятся ко всему списку форм;
by_form содержит до десяти форм; в текущем коде эта разбивка перебирает все формы даже при заданном form_id;
by_day содержит дни с заявками, без дополнения пустых дней;
requests_get_stats_by_hour возвращает все 24 часа за день. Без date используется сегодня. Даты и часы строятся серверными функциями времени приложения.

requests_export_requests возвращает текст в csv, количество строк rows и признак truncated, а при непустой выборке также total. Фильтры: форма, статус, начало и конец периода.

Схема инструмента допускает limit до 1000, но текущий код выборки ограничивает результат 100 заявками за вызов. Всегда проверяйте rows и truncated. У CSV нет аргумента offset; для выгрузки большего объёма сужайте период или другие фильтры и проверяйте полноту каждого фрагмента. Если фильтров недостаточно, список заявок можно читать постранично через requests_list_requests.

Какие данные передаются

В MCP-клиент поступают разрешённые токеном результаты: формы, значения заявок, параметры, комментарии, ссылки на файлы, статистика и CSV. Отдельный поиск контактов раскрывает данные из общей базы при наличии прав. Эти ответы могут попадать в контекст ИИ-сервиса, выбранного вами для клиента.

При передаче url сервер сайта скачивает файл с указанного внешнего адреса. Проверка уведомлений отправляет сообщение получателям формы по выбранному каналу. Обычное создание и импорт вызывают хуки, поэтому дальнейшая передача данных в CRM, Helpdesk или магазин зависит от установленных расширений и их настроек.

У плагина нет собственных заданий cron, CLI-команд, внешних API-ключей или вебхуков для отдельного подключения. Каналы уведомлений и связанные системы настраиваются средствами приложения «Заявки» и его расширений.