Базовый адрес
Все запросы идут на один адрес с номером версии в пути:
https://pcdesk.ru/api/v1
Версия в пути обязательна. Она меняется только при несовместимых изменениях, а новые поля в ответах добавляются без смены версии - разбирайте ответ так, чтобы незнакомое поле не ломало ваш код.
Данные принимаются и отдаются в формате JSON. Для запросов с телом указывайте заголовок Content-Type: application/json.
Авторизация
Ключ создаётся в кабинете: API-Ключи → «Создать токен». Полное значение ключа показывается один раз при выпуске, потом его нельзя посмотреть - только выпустить новый.
Ключ передаётся в заголовке X-API-Key:
curl -H "X-API-Key: ВАШ_КЛЮЧ" \
https://pcdesk.ru/api/v1/devices
Ключ всегда работает внутри своей организации. Обратиться к данным другой организации им нельзя, отдельного параметра для этого нет.
Права и роль
У ключа две независимые границы, и запрос проходит, только если обе разрешают действие.
- Отмеченные права. При выпуске вы отмечаете, что ключу разрешено: чтение устройств, изменение устройств, чтение сессий, чтение записей, изменение записей, чтение журнала аудита, чтение пользователей, изменение пользователей. Ключ получает ровно отмеченное и ничего больше.
- Роль ключа. Ключ выпускается под роль - «Наблюдатель», «Техник» или «Администратор». Часть операций доступна только техникам и администраторам: удаление и переименование устройства, блокировка и разблокировка, работа со списком пользователей, удаление записей.
Отсюда типичная ошибка: у ключа отмечено «Изменение устройств», но роль «Наблюдатель», и удаление устройства всё равно отклоняется. Права отвечают на вопрос «к каким разделам ключ допущен», роль - «что в этих разделах разрешено делать».
Опирайтесь на методы из этого справочника: остальные ручки служебные, их состав и формат меняются без предупреждения, а часть из них ключом недоступна в принципе - они требуют входа пользователя и вернут явный отказ.
Коды ответов
| Код | Когда возвращается |
|---|---|
| 200 | Запрос выполнен |
| 201 | Объект создан |
| 204 | Выполнено, тела в ответе нет |
| 400 | Ошибка в параметрах или теле запроса |
| 401 | Заголовок X-API-Key отсутствует, ключ неверный или отозван |
| 403 | Ключу не хватает права или роли для этой операции |
| 404 | Объект не найден в вашей организации |
| 429 | Превышена частота запросов |
Тело ошибки - JSON с полями statusCode, message и error. Например, при отсутствующем заголовке возвращается сообщение о том, что требуется X-API-Key, а при отозванном ключе - что ключ неверный или отозван. Эти два случая различаются только текстом, код в обоих 401.
Ограничение частоты
Действует общий предел: 120 запросов в минуту. При его превышении приходит 429. Если нужно выгрузить много данных, используйте фильтры и параметр limit вместо частых мелких запросов, а между страницами делайте паузу.
Отзыв ключа
Ключ отзывается в том же разделе кабинета. Отзыв действует сразу: следующий запрос с этим ключом получит 401. Выпуск и отзыв ключей попадают в журнал аудита, поэтому видно, кто и когда выдал доступ.