Данные ПАРУС 8 в чате через сервис интеграции с WEB API
Подключите ПАРУС 8 к ИИ-агенту через сервис интеграции с WEB API: агент вызовет объявленные функции обмена, разберёт коды отказов и сведёт данные.
Как агент работает с ПАРУС 8
Агент ходит в ПАРУС 8 через сервер приложений «Сервис интеграции с WEB API» — тот самый Node-сервис, который ставится рядом с базой. В подключении два поля: адрес сервера приложений и корень сервиса обмена, и путь функции агент считает уже относительно корня. Живость проверяется запросом к самому корню: он отвечает HTML с версией сервера приложений и именем сервиса на любой метод, поэтому доработок на стороне заказчика для подключения не требуется.
Состав функций у каждой инсталляции свой, и это главное отличие от облачных сервисов. Маршрутов у сервера приложений нет собственных: при старте он читает справочники самой базы — «Сервисы обмена» задают корень URL, «Функции сервиса» задают адрес, HTTP-метод и обработчики «до» и «после». Наружу этот перечень не публикуется, поэтому агент не подбирает пути наугад, а просит у вас выгрузку из настроек Паруса и работает по ней.
Отказы сервер приложений отдаёт одинаковым способом: HTTP 500 и текст вида ERR_КОД с сообщением, то есть статус не несёт смысла вообще. Агент разбирает префикс и различает то, что различить обязан: ERR_UNAUTH — отказ PL/SQL-обработчика в правах, который не лечится сменой логина, ERR_DB_SERVER — ошибка обработчика в базе, ERR_APP_SERVER_BEFORE и ERR_OBJECT_BAD_INTERFACE — неверная форма запроса. Повтор после них бессмысленен, и агент его не делает.
Форму ответа задаёт обработчик на стороне заказчика, а не вендор: одна функция вернёт JSON, соседняя — XML или произвольный текст, и агент не считает ответ JSON'ом заранее. Свои потолки он тоже держит: пул подключений сервера приложений к базе — десять по умолчанию, входящее сообщение — до десяти мегабайт, поэтому тяжёлые обработчики упираются в базу, а не в HTTP. Функции, чей адрес начинается с собаки, — раздача статики, и в перечне они пропускаются.
Сценарии интеграции
Выборка по объявленной функции
Агент вызовет функцию сервиса обмена — остатки, контрагентов, лицевые счета — и разложит ответ в таблицу, не заставляя администратора выгружать её руками.
Опись функций сервиса обмена
Агент соберёт с ваших слов перечень функций (код, адрес, метод) и будет держать его в диалоге, чтобы не подбирать пути наугад и не ловить 404.
Проверка живости сервера приложений
Агент дёрнет корень сервиса обмена и по ответу скажет, жив ли сервер приложений и его ли это 404 — до того, как вы начнёте искать ошибку в правах.
Разбор отказов PL/SQL-обработчика
Агент прочитает код ERR_ из тела ответа и назовёт причину: отказ в правах, ошибка обработчика в базе или неверная форма запроса.
Регистрация документа из чата
Если у сервиса объявлена пишущая функция, агент покажет тело будущего запроса и отправит его только после вашего подтверждения.
Связка Паруса с остальными системами
Агент сведёт выборку из Паруса с данными банка, маркетплейса или почты и покажет расхождения одной картиной, без промежуточных выгрузок.
Примеры: ПАРУС 8
Разобрал 24 функции: 17 читающих и 7 пишущих.
- 3 строки пропустил — адрес начинается с @, это раздача статики, а не функция обмена
- У 5 строк метод не проставлен, читаю их как GET
Дальше зову функцию её кодом. Каталога путей у сервиса обмена нет: состав функций задаётся в самой базе Паруса и у каждой инсталляции свой, поэтому адрес я не угадываю — 404 здесь означает «такой функции не объявлено», а не опечатку.
По функции DEBTS_BY_AGENT — 8,42 млн ₽ долга по 63 контрагентам.
- Свыше 90 дней висит 2,13 млн ₽, и это 14 контрагентов
- Ответ пришёл XML, а не JSON: форму ответа задаёт обработчик функции, поэтому я разбираю все три и не жду одну
Пустой таблицей отказ не покажу: строк не пришло — это ошибка разбора, а не «долгов нет». Регистрировать документы этой же функцией не буду — пишущий вызов сначала показывает тело будущего запроса и уходит только после вашего «да».
Как подключить
Перед подключением
- Развёрнутый сервер приложений «Сервис интеграции с WEB API»
- Заведённый сервис обмена с корнем URL в справочниках Паруса
- Объявленные функции сервиса: адрес, метод, обработчик в базе
- Сетевой доступ до сервера приложений с нашей стороны
- 1
Разверните сервис интеграции с WEB API
Сервер приложений «Сервис интеграции с WEB API» ставится рядом с базой ПАРУС 8 и держит весь обмен: без него запрос до базы не дойдёт вовсе.
- 2
Заведите сервис обмена и его корень
В справочнике «Сервисы обмена» создайте сервис и задайте его корень URL — этот корень вы укажете вторым полем при подключении.
- 3
Объявите функции сервиса
В справочнике «Функции сервиса» задайте для каждой операции адрес, HTTP-метод и обработчик в базе. Не объявленного адреса для сервера не существует — он ответит 404.
- 4
Проверьте корень сервиса в браузере
Откройте адрес сервера приложений вместе с корнем сервиса: живой обмен отвечает страницей с версией сервера приложений и именем сервиса.
Частые вопросы
Двумя полями: адресом сервера приложений «Сервис интеграции с WEB API» и корнем сервиса обмена из справочника «Сервисы обмена». Логин и пароль здесь не нужны — входящие запросы сервер приложений не аутентифицирует.
Потому что взять его больше неоткуда: перечень лежит в самой базе Паруса и наружу не отдаётся. Ответ 404 означает «такой функции не объявлено», а не опечатку в пути, поэтому угадывание здесь бесполезно.
Только через те функции сервиса обмена, которые ваш администратор объявил на запись. Тело будущего запроса агент показывает заранее и отправляет его после явного подтверждения.
Обратиться к администратору Паруса: права проверяет PL/SQL-обработчик конкретной функции обмена, а не сервер приложений. Смена логина и пароля в карточке подключения на этот отказ не влияет.