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

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

Доступ к Pyrus API

Для доступа к Pyrus API необходимо получить токен доступа и в дальнейшем указывать его в HTTP-заголовке Authorization в каждом запросе. Токен доступа можно получить, выполнив запрос auth. Срок действия токена ограничен, поэтому ваше приложение должно уметь повторно проходить процедуру авторизации в случае отзыва токена.

Токен авторизации может быть отозван в следующих случаях:

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

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

Все методы Pyrus API доступны только по защищенному https-каналу, расположены по адресу https://api.pyrus.com. В каждом запросе к Pyrus API должен быть указан HTTP-заголовок Authorization со значением Bearer access_token, где access_token — токен доступа, полученный при выполнении запроса auth. К методам Pyrus API можно обращаться не чаще 5000 раз в 10 минут. В HTTP-заголовках ответа содержится дополнительная информация по ограничениям:

X-RateLimit-Limit — максимальное количество запросов, разрешенное в данном временном интервале;
X-RateLimit-Remaining — количество запросов до превышения ограничения в данном временном интервале;
X-RateLimit-Reset — количество секунд до начала следующего временного интервала.

Параметры запросов POST и PUT передаются в 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, в формате state={string}. Этот параметр необходим для дальнейшей авторизации в Pyrus. После успешной авторизации вам необходимо перенаправить пользователя на адрес pyrus.com/integrations/oauthorization**?state={string}&code=token**, где state — объект, переданный 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 отправляет на ваш сервис запрос toggle. Если работа аккаунта приостановлена, Pyrus будет игнорировать все уведомления о новых событиях для данного аккаунта, поэтому стоит прекратить отправку уведомлений о новых событиях для отключенных аккаунтов, чтобы избежать блокировки из-за исчерпания лимита запросов.