Как Pyrus взаимодействует с сервисом расширения

Взаимодействие Pyrus с сервисом расширений основано на механизме вебхуков (запросов от Pyrus к сервису расширения) и методов Extensions API (запросов то сервиса расширения к Pyrus).

Доступ к Extensions API

Методы Extensions API доступны по адресу https://extensions.pyrus.com/v1/. Для авторизации запросов необходимо получить токен доступа, выполнив запрос POST token. Полученный токен необходимо указывать в HTTP-заголовке Authorization при каждом запросе к API:

Authorization: Bearer gAAAAA15vmSeoj*******

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

срок жизни токена истек;
секретный ключ вашего расширения был отозван администратором или службой безопасности Pyrus. В таком случае все выданные токены будут отозваны.

Общие требования

Параметры POST-запросов передаются в теле запроса в формате JSON. Параметры GET-запросов передаются в URL и при наличии специальных символов должны быть экранированы с помощью urlencode. Все ответы передаются в теле ответа в формате JSON. При передаче чисел в качестве разделителя целой и дробной части используется точка. Даты передаются в формате ISO 8601. Ответ от сервера всегда приходит с нулевой временной зоной. Пустые поля в ответе не возвращаются. В случае возникновения ошибки в теле ответа должны быть указаны поля:

error — сообщение об ошибке;
error_code — строковый код ошибки.

При ошибочном вызове возвращается наиболее подходящий HTTP Status Code.

Доступность вашего сервиса

После публикации новой версии расширения (или во время ее тестирования) Pyrus начнет отправлять запросы о действиях пользователя на адрес, указанный на странице основных настроек в личном кабинете разработчика (ЛК). Также Pyrus периодически отправляет запрос pulse для проверки доступности вашего сервиса. Ваш веб-сервис должен отвечать статусом 2xx на все запросы в течение 10 секунд после вызова. Если ваш сервис недоступен или отвечает статусом, отличным от 2хх, Pyrus отправит второй запрос через 11 секунд, а затем третий — через 22 секунды. Номер попытки содержится в заголовке X-Pyrus-Retry. Значение — одно из трех: «1/3», «2/3» или «3/3». В числителе номер попытки, начиная с единицы, а в знаменателе — количество попыток (три попытки). Для первого вызова, который не является повтором, ставится значение «1/3». Если за три попытки связаться не удалось, Pyrus обновит статус опубликованной версии расширения на Технический сбой, что приведет к невозможности ее использования. Об этом вы получите уведомление по электронной почте, указанной в общих настройках расширения. Pyrus будет продолжать отправлять на ваш сервис heartbeat-запрос pulse. Как только ваш сервис станет доступен, Pyrus обновит статус версии расширения на Опубликована.

Проверка подписи

Чтобы убедиться в том, что запрос был отправлен Pyrus, а не кем-то другим, в запросах присутствует заголовок X-Pyrus-Sig, в значении которого указывается подпись запроса. Для проверки подписи необходимо к телу запроса добавить секретный ключ расширения, вычислить для получившейся строки HMAC-дайджест с использованием алгоритма SHA1 и сравнить его со значением в заголовке X-Pyrus-Sig. Примеры реализации проверки подписи на различных языках программирования можно посмотреть здесь.

Авторизация в системе расширения

При установке расширения в форму пользователю Pyrus необходимо пройти авторизацию во внешней системе. Pyrus поддерживает два способа авторизации.

Авторизация по ключам доступа

При авторизации во внешней системе по ключам доступа пользователю предлагается ввести параметры для авторизации на странице основных настроек расширения в блоке Авторизация по параметрам в ЛК Pyrus отправляет на ваш сервис запрос authorize, в теле которого содержатся введенные пользователем данные. О результатах авторизации Pyrus узнает из ответа.

Авторизация по протоколу OAuth 2.0

При авторизации по протоколу OAuth 2.0 у пользователя в браузере открывается новая вкладка со ссылкой для авторизации во внешней системе, указанной на странице основных настроек ЛК в блоке Авторизация по OAuth 2.0. При этом в конец ссылки добавляется дополнительный текстовый параметр state. Этот параметр необходим для дальнейшей авторизации в Pyrus. После успешной авторизации вам необходимо перенаправить пользователя на адрес https://pyrus.com/integrations/oauthorization?state=<state_string>&code=<token>, где state_string — строка, переданная Pyrus при открытии ссылки для авторизации, а token — код авторизации. Далее Pyrus отправляет на ваш сервис запрос authorize с полученным кодом авторизации. Помимо этого, в теле запроса будут указаны дополнительные поля client_id, client_secret, scope, если они заполнены, параметр redirect_uri со значением https://pyrus.com/integrations/oauthorization и параметр grant_type со значением access_token при авторизации или refresh_token при восстановлении доступа. В теле ответа должен содержаться авторизационный токен, который Pyrus будет отправлять в запросах к вашему сервису и refresh-токен для обновления авторизационного токена. Pyrus обновляет авторизационный токен, если в поле error_code возникает ошибка expired_token в ответе любого из веб-хуков для расширений.

Включение/отключение расширения

Пользователь может приостановить работу аккаунта расширения, чтобы не получать уведомления о новых событиях. При этом Pyrus отправляет на ваш сервис запрос POST toggle. Если работа аккаунта приостановлена, Pyrus будет игнорировать все уведомления о новых событиях для данного аккаунта, поэтому стоит прекратить отправку уведомлений о новых событиях для отключенных аккаунтов, чтобы избежать блокировки из-за исчерпания лимита запросов.