# ПАРУС 8 (Сервис интеграции)

Данные ПАРУС 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_ из тела ответа и назовёт причину: отказ в правах, ошибка обработчика в базе или неверная форма запроса.

### Регистрация документа из чата
Если у сервиса объявлена пишущая функция, агент покажет тело будущего запроса и отправит его только после вашего подтверждения.

### Связка Паруса с остальными системами
Агент сведёт выборку из Паруса с данными банка, маркетплейса или почты и покажет расхождения одной картиной, без промежуточных выгрузок.

## Как подключить

**Перед подключением**

- Развёрнутый сервер приложений «Сервис интеграции с WEB API»
- Заведённый сервис обмена с корнем URL в справочниках Паруса
- Объявленные функции сервиса: адрес, метод, обработчик в базе
- Сетевой доступ до сервера приложений с нашей стороны

### Разверните сервис интеграции с WEB API
Сервер приложений «Сервис интеграции с WEB API» ставится рядом с базой ПАРУС 8 и держит весь обмен: без него запрос до базы не дойдёт вовсе.

### Заведите сервис обмена и его корень
В справочнике «Сервисы обмена» создайте сервис и задайте его корень URL — этот корень вы укажете вторым полем при подключении.

### Объявите функции сервиса
В справочнике «Функции сервиса» задайте для каждой операции адрес, HTTP-метод и обработчик в базе. Не объявленного адреса для сервера не существует — он ответит 404.

### Проверьте корень сервиса в браузере
Откройте адрес сервера приложений вместе с корнем сервиса: живой обмен отвечает страницей с версией сервера приложений и именем сервиса.

## Частые вопросы

### Как подключить ПАРУС 8?
Двумя полями: адресом сервера приложений «Сервис интеграции с WEB API» и корнем сервиса обмена из справочника «Сервисы обмена». Логин и пароль здесь не нужны — входящие запросы сервер приложений не аутентифицирует.

### Почему агент спрашивает список функций?
Потому что взять его больше неоткуда: перечень лежит в самой базе Паруса и наружу не отдаётся. Ответ 404 означает «такой функции не объявлено», а не опечатку в пути, поэтому угадывание здесь бесполезно.

### Пишет ли агент в Парус?
Только через те функции сервиса обмена, которые ваш администратор объявил на запись. Тело будущего запроса агент показывает заранее и отправляет его после явного подтверждения.

### Что делать при ошибке ERR_UNAUTH?
Обратиться к администратору Паруса: права проверяет PL/SQL-обработчик конкретной функции обмена, а не сервер приложений. Смена логина и пароля в карточке подключения на этот отказ не влияет.

[Открыть ПАРУС 8 (Сервис интеграции)](https://git.citpb.ru/CITKParus/P8-ExchangeService)