Общие положения

API приложений предназначен для прямого мгновенного обмена событиями и командами между десктопным Win-приложением 1С-Коннект для ПК (далее по тексту "ДП") и другим приложением ОС (далее по тексту "внешнее приложение"), с минимальными затратами CPU → Интеграция между клиентскими приложениями 2-х систем.

Бизнес-логика

На рабочем месте сотрудника организации, как правило, установлена мульти-оконная ОС, в которой часто одновременно работают несколько различных приложений для обслуживания клиентов. Причём одного и того же клиента в определенный момент времени. В таких случаях есть потребность в прямом быстром взаимодействии между этими приложениями - это позволяет уменьшить количество действий пользователя.

Известные сценарии интеграции:

ДП используют как средство связи с клиентом, в т.ч. телефонной, но номера телефонов хранятся и отображаются в интерфейсе учетной информационной системы организации (далее УИС). Полезно иметь возможность "одним кликом" в УИС начать звонок в ДП на целевой номер.
ДП используют как средство рассылок типовых уведомлений (текст, файл) клиентам, но индивидуальная для клиента информация хранится в УИС. Полезно иметь возможность из УИС отправить сообщения/файлы заранее известным адресатам.
Логика назначения специалиста зависит от информации, хранящейся в УИС. В этом случае полезно иметь возможность из УИС автоматически/действием пользователя забрать обращение на себя или перевести его на указанную линию/указанному адресату.

Использование API приложений возможно только при подключении тарифного плана, в котором доступно API.

Протокол активен только после авторизации в ДП до момента окончания сеанса пользователя, и только при наличии разрешения на использование API для организации, в которой числится данный абонент.

Технология

Используется технология ОС Named Pipe. ДП выступает в ОС Windows в качестве Named Pipe-сервера, т.е. Pipe-канал присутствует в ОС пока работает процесс ДП и пользователь авторизован.

Характер (подход) взаимодействия по этому протоколу: ведомым является ДП, а внешнее приложение управляет им.

Тип и формат единицы обмена: пакет-сообщение в формате XML. С каждым XML-сообщением передается служебная информация, состоящая из 2 байтов данных (длина строки) и разрыва строки.

Разработчик внешнего приложения самостоятельно контролирует оперативность считывания событий из именованного канала, а также своевременность его очистки.

Роль и место в архитектуре 1С-Коннект

Является второй составной частью протокола 1C-Connect API, зависящей от API серверов:

манипулирование любым объектом данных 1С-Коннект и его идентификация производится путём указанием идентификатора-ссылки на него (формат GUID). Предполагается, что стороннее приложение уже знает идентификаторы объектов (оно может получить их заранее путём синхронизации по протоколу API серверов).
все команды определяются, как идущие от лица текущего аккаунта 1С-Коннект (внутри протокола API приложений дополнительная авторизация не предусмотрена).

Технические ограничения

ДП должно иметь доступ в Интернет.

В текущем поколении API приложений не рассчитан:

на одновременную работу с несколькими другими приложениями Windows.
на одновременный запуск нескольких экземпляров ДП от одного и того же пользователя ОС.
на взаимодействие с другими экземплярами приложения 1С-Коннект, запущенными от лица того же аккаунта (то есть получение событий от твоих же действий, но с других устройств, не гарантируется).
на события и команды касаемо вкладки "Линии поддержки", т.е. где текущий аккаунт выступает как потребитель, а не как сотрудник обслуживающей компании. API приложений позиционируется как инструмент для интеграции инструментов автоматизации работы обслуживающей компании.
на взаимодействие с внешним приложением, являющимся "web app in a sandbox/browser", т.к. в таком случае внешнее приложение не имеет доступа к большинству возможностей Desktop OS.

Реализация

Взаимодействие происходит в NamedPipe-канале BuhphoneAgentAPI2_<Логин агента>

API приложений состоит из 2 направлений взаимодействия:

Трансляция событий 1С-Коннект для данного абонента из ДП внешнему приложению. Массовые категории событий транслируются только после соответствующей команды от внешнего приложения (подписаться на события).
Инициирование действий в ДП путём передачи соответствующей команды из внешнего приложения.