Ошибка 401 Unauthorized при первом же запросе к Pyrus API из Python-скрипта почти всегда означает одно: токен доступа либо не получен, либо передаётся не в том заголовке, либо уже истёк. API корпоративной системы управления задачами Pyrus работает по классической схеме REST: сначала вы обмениваете логин и секретный ключ на токен, затем передаёте его в заголовке Authorization каждого запроса. Если скрипт отвечает отказом — начинайте диагностику именно с этапа авторизации, а не с переписывания всего кода.
В этой статье разберём, как настроить интеграцию с Pyrus API на Python с нуля: получение учётных данных, отправку запросов через библиотеку requests, создание задач, работу с формами и обработку типичных ошибок. Материал подойдёт разработчикам, которые автоматизируют бизнес-процессы: выгрузку заявок, синхронизацию с CRM или уведомления о новых задачах.
Что представляет собой Pyrus API
Pyrus — облачная платформа для постановки задач, согласования документов и работы с формами (заявками). Её публичный API позволяет программно выполнять большинство действий, доступных в веб-интерфейсе: создавать и комментировать задачи, получать списки форм и их полей, читать историю согласований, скачивать вложения.
Архитектурно это REST API с обменом данными в формате JSON. Все запросы идут по HTTPS на базовый адрес вида https://api.pyrus.com/v4/. Актуальную версию адреса и перечень методов стоит сверять с официальной документацией Pyrus, так как эндпоинты могут дополняться.
- 🔑 Авторизация — обмен логина и секретного ключа на временный токен доступа.
- 📋 Задачи (tasks) — создание, чтение, комментирование, изменение статуса.
- 📝 Формы (forms) — работа со структурированными заявками и их полями.
- 📎 Файлы — загрузка вложений и скачивание прикреплённых документов.
- 🔔 Боты и уведомления — автоматические реакции на события в задачах.
Получение доступа: логин и секретный ключ
Прежде чем писать код, вам нужно создать бота в настройках Pyrus — именно от его имени будет работать скрипт. Бот получает логин (обычно это email-адрес специального вида) и security key — секретный ключ, который показывается один раз при создании. Сохраните его сразу в надёжном месте: восстановить ключ нельзя, только сгенерировать новый.
Хранить учётные данные прямо в коде — плохая практика. Используйте переменные окружения или файл конфигурации, исключённый из системы контроля версий через .gitignore.
import os
LOGIN = os.environ.get("PYRUS_LOGIN")
SECURITY_KEY = os.environ.get("PYRUS_SECURITY_KEY")
⚠️ Внимание: секретный ключ бота даёт доступ к данным вашей организации в Pyrus. Публикация ключа в открытом репозитории или пересылка в мессенджерах означает компрометацию — в этом случае немедленно сгенерируйте новый ключ в настройках бота.
Авторизация и получение токена
Первый запрос любой интеграции — получение токена. Для этого отправляется POST-запрос на эндпоинт авторизации с логином и секретным ключом в теле запроса. В ответ сервер возвращает JSON с полем access_token, который затем подставляется в заголовок всех последующих запросов.
import requests
AUTH_URL = "https://api.pyrus.com/v4/auth"
def get_token(login: str, security_key: str) -> str:
response = requests.post(AUTH_URL, json={
"login": login,
"security_key": security_key
})
response.raise_for_status()
return response.json()["access_token"]
Важный нюанс: токен имеет ограниченный срок жизни. Если скрипт работает долго или запускается по расписанию, логично получать свежий токен при каждом запуске, а не кэшировать его надолго. При истёкшем токене API вернёт ошибку авторизации — это сигнал запросить токен заново.
Создание задачи через API
Создание задачи — самый частый сценарий автоматизации. Запрос отправляется методом POST на эндпоинт задач, а в теле передаётся JSON с текстом задачи, ответственным и другими параметрами. Минимальный рабочий пример выглядит так:
def create_task(token: str, text: str, responsible_id: int):
headers = {"Authorization": f"Bearer {token}"}
payload = {
"text": text,
"responsible": {"id": responsible_id}
}
r = requests.post(
"https://api.pyrus.com/v4/tasks",
json=payload,
headers=headers
)
r.raise_for_status()
return r.json()
Идентификаторы пользователей (responsible id) можно получить через метод списка контактов организации. Обратите внимание: передавать нужно именно числовой ID, а не email — это частая причина ошибок валидации.
☑️ Перед созданием задачи проверьте
Работа с формами и заявками
Формы в Pyrus — это структурированные шаблоны заявок: заказ пропуска, заявка на закупку, обращение в поддержку. Через API можно получить реестр форм, структуру полей конкретной формы и список заполненных заявок с фильтрацией по статусу или дате.
Каждое поле формы имеет числовой идентификатор (field id), и при создании задачи по форме значения привязываются именно к этим ID, а не к названиям полей. Поэтому первым шагом всегда запросите описание формы и сохраните соответствие «название поля → ID».
| Метод | Назначение | Тип запроса |
|---|---|---|
/auth | Получение токена доступа | POST |
/tasks | Создание и чтение задач | GET / POST |
/forms | Список форм и их структура | GET |
/forms/{id}/register | Реестр заявок по форме | GET |
/files/upload | Загрузка вложения | POST |
Точные URL и набор параметров зависят от текущей версии API — сверяйтесь с официальной документацией перед внедрением в продакшн. Структура ответов тоже может расширяться, поэтому код должен терпимо относиться к неизвестным полям в JSON.
Обработка ошибок и ограничения
При работе с API вы неизбежно столкнётесь с ошибками. Разберём основные категории и порядок диагностики.
- 🚫 401 Unauthorized — токен отсутствует, истёк или передан без префикса
Bearer. Запросите токен заново. - ⛔ 403 Forbidden — у бота нет прав на объект: добавьте его участником задачи или формы.
- ❓ 404 Not Found — неверный ID задачи/формы или опечатка в URL эндпоинта.
- 📝 400 Bad Request — ошибка валидации тела запроса: проверьте обязательные поля и типы данных.
Тело ответа с ошибкой обычно содержит текстовое описание причины — обязательно логируйте его. Конструкция response.raise_for_status() выбрасывает исключение, но не показывает детали, поэтому на этапе отладки выводите response.text полностью.
⚠️ Внимание: у API могут действовать лимиты на частоту запросов. Если скрипт массово выгружает данные и начинает получать отказы, добавьте паузы между запросами (time.sleep) и повторные попытки с экспоненциальной задержкой вместо агрессивного цикла.
Ещё одна тонкость — бот видит только те задачи и формы, к которым у него есть доступ. Если API возвращает пустые списки, хотя в веб-интерфейсе данные есть, проверьте права бота: его нужно добавить в соответствующие формы или задачи вручную через интерфейс Pyrus.
Как отладить запрос без кода
Используйте инструмент вроде curl или Postman: отправьте тот же запрос вне Python. Если и там ошибка — проблема в данных или правах, а не в коде. Если запрос проходит — сравните заголовки и тело с тем, что формирует ваш скрипт, напечатав их перед отправкой.
Готовые библиотеки и асинхронность
Писать всё на «голом» requests необязательно: существуют обёртки над Pyrus API на Python, которые инкапсулируют авторизацию и типовые методы. Перед выбором такой библиотеки проверьте дату последнего обновления и поддержку актуальной версии API — заброшенный пакет может не знать о новых эндпоинтах.
Для высоконагруженных интеграций (например, бот, обрабатывающий сотни событий) рассмотрите асинхронный клиент на базе httpx или aiohttp. Это позволит выполнять параллельные запросы без блокировок, что заметно ускоряет массовую выгрузку заявок.
Практический сценарий: бот-наблюдатель за заявками
Типовая задача — периодически опрашивать реестр формы и реагировать на новые заявки. Общая логика такого скрипта: получить токен, запросить реестр с фильтром по дате последнего запуска, обработать новые записи, сохранить метку времени. Запуск настраивается через cron на Linux или планировщик задач Windows.
Храните идентификатор последней обработанной заявки в файле или базе данных — это надёжнее, чем фильтровать только по времени, так как исключает пропуски при сбоях и повторную обработку одних и тех же записей.
Частые вопросы о Pyrus API и Python
Можно ли использовать Pyrus API без создания бота?
Нет, для программного доступа требуется бот с логином и секретным ключом. Он создаётся в настройках организации и работает как отдельная учётная запись с ограниченными правами.
Как узнать ID пользователя или поля формы?
Через соответствующие GET-методы API: список контактов возвращает пользователей с их ID, а описание формы — перечень полей с идентификаторами. Использовать email или названия вместо ID в большинстве методов нельзя.
Сколько живёт токен доступа?
Токен имеет ограниченный срок действия, точное значение указано в документации. Практичное решение — получать новый токен при каждом запуске скрипта или обновлять его при получении ошибки 401.
Что делать, если API возвращает пустой список задач?
Проверьте права бота: он видит только те задачи и формы, где состоит участником. Добавьте бота в нужную форму через веб-интерфейс и повторите запрос.
Подходит ли requests или нужна специальная библиотека?
Стандартной библиотеки requests достаточно для большинства сценариев: авторизации, создания задач, выгрузки реестров. Сторонние обёртки экономят время, но требуют проверки актуальности и поддержки нужных методов.