xRM позволяет использовать системный API во внешних приложениях.

1. Ключ

Начиная с версии 2.0.4, авторизацию в API состоит из 2х этапов:

  1. Авторизация приложения 
  2. Авторизация пользователя

Есть сущность «приложение», которой присваивается уникальный ключ APP_KEY. Приложения, не предоставившие правильный ключ, не допускаются к использованию API. Если ключ передан и валиден, то его достаточно, чтобы увидеть описание доступных приложению методов в API панели. Набор доступных приложению методов регулируется ролью на видимость. 

Но ключа приложения не достаточно чтобы вызвать метод, для этого нужна уже пользовательская авторизация. Пройдя ее и получив session_key можно вызывать методы, доступные одновременно пользователю и приложению.

Старое поведение

До версии 2.0.4 не было этапа авторизации приложения и соответственно никаких ключей. В API просто были видны те методы, которые доступны авторизованному в данный момент пользователю. Пока пользователь не авторизован, доступны только методы open_session/close_session.

С этим были связаны проблемы:

  1. Если приложением воспользуется пользователь с очень мощными правами, то приложению становится доступно то, что мы не хотели бы, чтобы ему было доступно.
  2. Невозможно понять какие API методы реально использует то или иное приложение.
  3. Разработчики приложения не могут получить описание методов пока они не авторизуются пользователем в системе.

1.1. Проверка ключа

APP_KEY необходимо передавать при каждом запросе к API.

Ключ проверяется только в том случае, если системная переменная CHECK_APP_KEY (ID: 100030000000000248382) имеет значение 1. Переменная отключена по умолчанию на инсталляциях до версии 2.0.4.*. При обновлении старой инсталляции она также останется отключенной (если не включить вручную) для обратной совместимости. В случае установки xRM 2.0.4.* (и старше) на «чистый» сервер переменная по умолчанию включена.

Важно

  • Мы рекомендуем по возможности переходить на проверку ключа после обновления на версию >= 2.0.4.01. Примерный план миграции предложен ниже.
  • Более подробное описание работы с API можно найти здесь.

1.1.1. Возможные ошибки проверки ключа

При попытке авторизоваться без ключа app_key (при включенном параметре CHECK_APP_KEY) система выдаст ошибку: [366] Ключ приложения отсутствует или некорректен.

При попытке использовать API-метод без передачи ключа app_key вы получите ошибку: Authentication parameter APP_KEY is invalid or missing.

1.1.2. Проверка текущего значения переменной CHECK_APP_KEY

В поле поиска введите идентификатор 100030000000000248382.

Перейдите по ссылке на найденный объект. Откройте вкладку Значения в БД.

Найдите текущее значение переменной.

1.2. План миграции после обновления версии ниже 2.0.4

Если у вас стояла версия < 2.0.4 и после обновления вы хотите перейти на полноценную проверку ключей, то примерная последовательность действий выглядит так:

  1. Проверить, что CHECK_APP_KEY = 0
  2. Завести в системе все приложения, которые используют API, получить для каждого APP_KEY
  3. Создать роли на видимость для каждого приложения или оставить их пустыми для старого поведения.
  4. Доработать каждое приложение, чтобы оно передавало APP_KEY
  5. Проверить работу этих приложений
  6. Поменять системный параметр CHECK_APP_KEY = 1

Важно

Не переключайте CHECK_APP_KEY = 1, пока есть хоть одно приложение, которое не передает APP_KEY. Оно сломается.

2. Создание нового приложения

Перейдите в раздел Разделение полномочий | Приложения.

Нажмите кнопку Добавить. Заполните поля в карточке нового ключа.


Укажите Наименование.

В поле Тип выберите Ключ.

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

Как обычно, выберите группу.

Нажмите Добавить. После нажатия кнопки Добавить система создаст новый ключ:


2.1. Роль на видимость

Указывается для приложения и содержит просто перечень доступных приложению методов. Даже если этим приложением воспользуется пользователь с очень мощными правами, то приложение сможет звать только тот перечень методов, который ему определили в "Роли на видимость". Рассмотрим на примере:

МетодПрава у "Роли на видимость"Права у пользователяВидно описание в WSDLМожно вызывать
A++++
B+-+-
C-+--

Есть 3 метода: 

  • Метод А. Есть доступ у приложения и у пользователя. Его описание будет видно в wsdl, т.к. для этого достаточно полномочий приложения, и позвать его можно будет, потому что у пользователя также есть на него разрешение.
  • Метод B. Есть доступ у приложения, но не у пользователя. Его описание будет видно в wsdl, т.к. для этого достаточно полномочий приложения, а вот позвать его не получится, т.к. пользователю он не доступен.
  • Метод C. Нет доступа у приложения, но есть у пользователя. Его описание не будет видно в wsdl, т.к. полномочий у приложения нет, и позвать его поэтому не получится, даже если пользователю он доступен.

Если коротко, то для вызова доступны методы являющиеся результатом пересечения прав пользователя и прав приложения.

Роль на видимость не обязательное поле на данный момент у приложения. Это сделано для облегчения миграции приложений, которые до этого не использовали APP_KEY и неизвестно какие методы им вообще нужны. Если поле не заполнено, то фактически приложение работает наполовину в старом режиме: после авторизации приложения не видно никаких методов в API панели, кроме open_session/close_session, а после авторизации пользователя доступны все методы которые доступны пользователю. Таким образом уже происходит 2х этапная авторизация и можно включать проверку CHECK_APP_KEY, но приложение никак не ограничено тем, какие методы может использовать.

2.2. Экземпляры приложения

Открыв карточку приложения, вы увидите, что в ней появилась вторая вкладка: Установленные экземпляры. Если приложение, использующее этот ключ, установлено на одно или несколько мобильных устройств, во вкладке будет выведен список экземпляров приложения: