Авторизация, тарифы и разрешения подключения

Домен организации и авторизация токеном

Направляйте запросы на https://<домен-организации>/api/v1/.... Адрес определяет организацию, с данными которой работает подключение. Записи другой организации недоступны. Вложенные ресурсы дополнительно проверяются на принадлежность родительской записи.

Передавайте токен в заголовке Authorization: Bearer <SERVICEAPP_TOKEN>. Вход в панель через браузер не заменяет авторизацию API. Если запрос также содержит данные сессии панели, он всё равно выполняется от имени владельца токена. Передача токена в адресе запроса, базовая HTTP-авторизация, токен интеграции с 1С и переопределение HTTP-метода для этого API не поддерживаются.

Создайте подключение в панели «Настройки → Каналы связи и интеграции → API». Для этого нужно право «Системные настройки → Информация о компании». Выберите разрешения, доступные мастерские и срок действия. Подключение выполняет команды от имени создавшего его сотрудника. Сохраните токен: он показывается один раз. Выдача, обновление и замена токена через публичные методы API не поддерживаются.

При замене токена идентификатор подключения сохраняется, а прежние токены отзываются. Сохранённые операции и занятые ключи Idempotency-Key остаются связаны с тем же подключением. Отзыв подключения, истечение срока токена, удаление или отключение сотрудника возвращают 401. Актуальные права и мастерские проверяются также при повторе запроса, просмотре журнала, скачивании файлов и доставке событий.

Тариф и доступ

Бизнес-операции доступны на тарифах «Энтерпрайз», «Энтерпрайз Про» и при действующем пробном периоде, когда API включено для организации. «Энтерпрайз Лайт» доступа к API не включает. Наличие модуля в панели само по себе доступа к API не даёт.

Доступ зависит одновременно от тарифа и модулей, разрешений подключения и токена, прав сотрудника, выбранных мастерских и доступа к конкретным записям. Разрешение подключения не заменяет право сотрудника. Владелец организации имеет полный набор прав сотрудника, но ограничения подключения и доступа к API действуют и для него.

GET /context остаётся доступен действующему токену для диагностики недоступности данных. access.status принимает active, trial, subscription_inactive, api_disabled, plan_unavailable. Сроки пробного периода и подписки могут быть null. При недоступном плане features.public_api=false, действующие разрешения подключения отсутствуют. Контекст не выдаёт секретов или доступа к данным закрытых модулей.

context.workshop_ids содержит пересечение мастерских роли и подключения. context.features сообщает доступность public_api, maintenance, installation, service_contracts, custom_fields, visit_routes. Возможности операций дополнительно зависят от контекста записи.

Выбор разрешений подключения

Разрешения подключения (scopes) задаются точными строками. Например, maintenance_schedules:write и maintenance_plans:write — разные разрешения. Сокращённое имя maintenance:write и шаблоны не поддерживаются. Разрешение :write не включает :read: для получения результата через GET нужно отдельно выбрать разрешение на чтение. Дополнительные требования составных команд перечислены в справочнике ресурса.

Полный словарь приведён в таблице разрешений подключения. В справочнике каждой операции указаны её базовые разрешения подключения и права сотрудника. Дополнительные условия зависят от переданных полей, типа акта и затрагиваемых связей.

Права сотрудника:

• Реквизиты и внутренняя заметка клиента: «Клиенты и поставщики → Просмотр» для чтения и «Клиенты и поставщики → Изменение» для записи.
• Закупочная цена товара: «Товары → Просмотр» для чтения и «Товары → Изменение» для записи.
• Заметки и результат акта: обычные права просмотра и изменения актов. Ручная цена, скидка и отметки выезда требуют обычного права изменения акта.
• Стоимость простоя требует финансовых прав; техническое чтение оборудования их не подразумевает.
• Журнал ограничен текущим подключением; одного api_operations:read недостаточно для выдачи ранее сохранённого результата, если текущий доступ к его ресурсам утрачен.

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