Входящее подключение

Подключение принимает JSON внешней системы и выполняет заранее настроенное действие. Например, внешний subject становится полем темы заявки.

Где настроить

Суперпользователь открывает Настройки платформы → Настройка системы → Интеграции → Приём данных. Выберите входящее подключение и настройте действие и сопоставление полей. Права управления интеграциями на сервере и доступ к этому экрану — не одно и то же; запуск через API требует scope integrations:execute и прав владельца ключа на саму команду.

Выберите действие

• object.create — создать запись выбранного типа.
• object.update — изменить существующую запись этого типа.
• comment.add — добавить комментарий; видимость задаётся настройкой подключения.

Порядок настройки

1. Укажите понятное название подключения и выберите действие.
2. Для записи выберите тип и сопоставьте входящие названия с кодами полей.
3. Проверьте все обязательные поля создания; при обновлении передавайте только то, что намеренно меняете.
4. Включите подготовленное подключение в интерфейсе.
5. Отправьте учебный запрос и проверьте получившуюся запись.

В списке можно искать название, описание или код, а также отбирать включённые/выключенные подключения. «Добавить интеграцию» создаёт выключенную настройку. В редакторе «Добавить поле» / «Убрать» меняют сопоставление, не данные объектов. Если список полей не загрузился, используйте «Повторить загрузку полей» — введённое остаётся в форме. Код в «Дополнительных сведениях» можно оставить системе; после создания он не меняется.

В карточке нажмите «Проверить настройки» и разберите ошибки и предупреждения. Это проверка заполнения, не отправка запроса внешней программы и не доказательство её прав. «Как подключить другую программу» содержит адрес POST и нужные параметры выбранного действия. «История настроек» отделена от результатов обмена; показывает записи из последних 100 изменений настроек.

«Выключить» прекращает обработку новых запросов, сохраняя созданные записи. «В архив» сохраняет настройки и историю; восстановление выполняется во вкладке архива и не включает обмен автоматически. «Сохранить изменения» действующей настройки само по себе не переключает её состояние: изменение включённого подключения сразу меняет будущую обработку, поэтому согласуйте его с владельцем программы.

Для создания пример тела зависит от вашего сопоставления:

POST /api/v1/inbound/INTEGRATION_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: inbound-example-001

{"subject":"Учебное обращение"}

Для обновления нужны objectId, положительная expectedRevision и хотя бы одно сопоставленное поле. При HTTP 409 прочитайте текущую запись. Подключение не обновит объект другого типа.

Пример сопоставления: внешняя тема → тема заявки

Начните в учебном контуре с одной понятной команды. Создание, изменение и комментарий — разные действия подключения, не режимы одного запроса.

1. Во вкладке «Приём данных» нажмите «Добавить интеграцию». Назовите её, например «Учебный приём обращений», и опишите назначение без паролей и токенов.
2. Выберите «Создавать запись», затем в «Что создавать» — нужный тип заявки.
3. Нажмите «Добавить поле». Слева впишите subject — именно это имя пришлёт внешняя программа. Справа выберите «Тема». Здесь важно направление: входное имя слева, поле NGENSIA справа.
4. Добавьте остальные нужные сопоставления. Метка «обязательное» помогает не пропустить поле при создании, но проверку всей конфигурации всё равно выполните отдельно. Значения ссылок передаются в формате поля API, а не произвольными названиями сотрудников и услуг.
5. Нажмите «Добавить выключенной». Откройте «Проверить настройки» и исправьте замечания. Если после выбора другого типа список сопоставлений сбросился, настройте его заново: поля прежнего типа не подходят автоматически.
6. В «Как подключить другую программу» возьмите адрес POST выбранного подключения. На вкладке «Ключи доступа» подготовьте ключ с областью integrations:execute и владельцем, которому разрешено создание этого типа и заполнение полей.
7. Включите подключение только в учебном контуре и отправьте один запрос со всеми обязательными данными. Проверьте не только успешный HTTP-ответ, но и ID, тип и значения созданной записи. Затем проверьте отказ при некорректном поле без создания лишних записей.

Сопоставление читает поля верхнего уровня JSON. Запись customer.name слева не означает автоматический обход вложенного объекта customer: согласуйте плоский формат с разработчиком отправляющей программы. Смена действия уже сохранённого подключения недоступна в обычном редакторе — для другой команды создайте отдельное подключение.

Изменение записи: не потерять чужую правку

Для «Изменять запись» отправитель сначала читает объект через API и получает его текущую revision. Затем передаёт objectId, эту expectedRevision и только намеренно изменяемые поля из сопоставления. Отсутствующее поле сохраняет старое значение; null — явная попытка очистить его, разрешённая только если поле допускает пустоту.

При 409 Conflict не подставляйте новый номер ревизии вслепую. Прочитайте объект снова, сравните чужую правку со своей и решите, что действительно нужно отправить. Объект другого типа выбранное подключение не обновит.

Для «Добавлять комментарий» сопоставления полей не нужны: отправляются objectId и body. Публичность задаётся в «Кто увидит комментарий» при настройке подключения. Перед включением убедитесь, что внутренний текст не будет опубликован для контрагента.

Что важно знать

Настроенный executionPrincipalId не предоставляет повышенные права отправителю: входящая команда выполняется с правами владельца предъявленного ключа. Выключенное или архивированное подключение не принимает события.

Ответ создающего или изменяющего подключения возвращается в обычном API envelope. Не определяйте успех только по тому, что запрос отправлен: проверьте HTTP status и ID результата.

Проверить историю подключения

Откройте карточку подключения и различайте два блока:

• «История настроек» — кто создал, изменил, включил или архивировал настройку. Это не доказательство успешного обмена.
• «Результаты входящих запросов» — выполнение или причина отказа: права, данные, отсутствующая запись, конфликт версии.

Оба блока берут записи из последних 100 событий соответствующего общего журнала интеграций, затем отбирают это подключение. Это не полная история именно одного подключения. Запрос, отклонённый ещё до проверки ключа или его области доступа, здесь может отсутствовать. Содержимое запроса и секрет ключа не показываются. Для разбора сообщите сопровождающему время и идентификатор подключения, а не сам ключ.

Связанные статьи

• Справочник интеграций
• Ошибки и повторы
• Создать объект напрямую