Обработчик (handler)

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

На примере интеграции с 1С это работает так: есть определенное приложение Битрикс24, которое дает токен и там же есть определенная страничка обработчика. Из 1С регистрируется событие на офлайн событие onOfflineEvent и когда появляется новая запись, это обрабатывает handler и он стучится в 1С. 1С понимает, что появились новые данные и выполняет event.offline.get, получает записи и обрабатывает их.

Пример вызова:

https://myportal.bitrix24.com/rest/event.bind
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36 // ключ авторизации
  &event=onOfflineEvent // добавление офлайн события
  &handler==http%3A%2F%2Fwww.my-domain.com%2Fhandler%2F // адрес обработчика

Минус такого способа: внешняя система (например, 1С) должна быть доступна снаружи, иначе обработчик не сможет до неё достучаться.

Push&Pull сервер

В случаях, когда безопасность критична - есть другой способ, через Push&Pull сервер.

Реализацию способа рассмотрим на примере интеграции с 1С, т.к. он разработан специально для неё.

Для получения информации о новых офлайн событиях используется открытый канал Push&Pull сервера, который всегда есть в каждом приложении Битрикс24. В таком варианте внешняя система сама подключается к Битрикс24 и ждёт от него сообщений. Как только приходит сообщение о новой записи, внешняя система забирает данные из очереди.

Для того, чтобы 1С могла подключиться, сначала она отправляет запрос методом pull.application.config.get. В результате получается ответ, из которого ей нужны: адрес до Push сервера, clientId (уникальный идентификатор портала на облачном push-сервере) и id открытого канала.

Пример ответа:

https://my.bitrix24.ru/rest/pull.application.config.get

{
    "result":{
        "server":{
            "version": 4,
            "long_polling": "http://rt.bitrix24.com/sub/",
            "long_polling_secure": "https://rt.bitrix24.com/sub/",
            "clientId": "43253464643",
            ...........
        },
        "channels":{
            "shared":{
            "id":"0d875ab13a17a97fc2f5",
            "start":"2017-06-28T12:04:00+02:00",
            "end":"2017-06-29T00:04:00+02:00",
            ...........
        }
        "private":{
            ...........
        }
    }
}

И после 1C подключается с этими данными и ожидает сообщения от push сервера:

https://rt.bitrix24.com/sub/ // адрес подключения к push серверу
    ?CHANNEL_ID=0d875ab13a17a97fc2f5 // идентификатор канала
    &clientId=43253464643 // идентификатор портала на облачном push сервере

Когда срабатывает какое-то офлайн событие и попадает в очередь, в push передается сообщение в формате json с указанием, что это офлайн событие и параметром connector_id, в котором указано для какой внешней системы предназначено сообщение.

#!NGINXNMS#{
    ......
    "text":{
        "module_id":"rest",
        "command":"event_offline",
        "params":[
            {
                "connector_id":"OneC",
                "count":1
            }
        ],
        ......
    }
}