Настройки позволяют создать более гибкую интеграцию с аккаунтом пользователя. Каждый пользователь сможет настроить приложение под свои нужды.
Пример. Ваше приложение это виджет погоды. Чтобы показывать погоду пользователь должен указать желаемый населенный пункт. Этот населенный пункт и есть пример настройки.
Еще один пример. Например, ваше приложение генерирует красивое меню для предстоящих выездных мероприятий. Чтобы сгенерировать этот документ вам нужно знать какое поле в системе пользователя соответствует цене, а какое описанию продукта. Настройки позволят пользователю самостоятельно сделать сопоставление полей.
Создание настроек становится доступным после создания приложения. В общем списке ваших приложений появится новая иконка в колонке действий "Действия и настройки".
Название. Название настройки для пользователя.
Описание. Более подробное описание настройки для пользователя. Пользователь увидит этот текст в форме настроек под формой ввода.
Категория. Когда настроек становится слишком много, то визуально удобнее будет их группировать
по какому-то смыслу. Например, категории Данные Roistat, Поля сделок и Поля заявок.
Ключ. Системное имя настройки. Будет доступно в current_token в атрибуте options.
Имя ключа должно соответствовать regex /^[a-z]{1}[a-z0-9_]{0,63}/. Должно начинаться с буквы,
разрешены латинские символы с a по z, цифры и _; не длиннее 64 символов.
Тип объекта. Доступно только для типа данных "Системное поле S2". Указывает с объектом какого типа в CRM необходимо будет делать соответствие полей.
Текст. Обычное текстовое поле. Значение, введенное пользователем, будет храниться как строка.
Число. Числовое поле. Пользователь может вводить только цифры. ВАЖНО! Значение будет храниться как строка.
Чекбокс. Булево поле. В интерфейсе будет отображаться checkbox. Хранимые значения true либо false.
По умолчанию всегда false.
Системное поле S2. Поле сопоставления. В интерфейсе будет отображаться как селект со списком
всех доступных полей объекта. Хранимое значение - имя атрибута в JSON API (например, created-at
или custom-1421).
Если предоставленных возможностей для создания настроек вам недостаточно, то вы можете создать свою форму настроек, которую мы загрузим в iframe.
Настройки через iframe имеют приоритет над настройками созданными через обычную форму.
Укажите адрес в поле URL для Iframe настроек. Именно этот адрес будет использован
как src для iframe.
При использовании iframe вы можете самостоятельно решить где и как хранить пользовательские настройки. Вы можете хранить их в своей базе. В таком случае ответственность за целостность настроек полностью лежит на вашем сервисе.
Так же вы можете хранить эти настройки и на серверах S2. Для этого используйте API для управления токеном.
Пример обновления настроек
curl "https://app.salesap.ru/api/v1/current-token" \
-X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer api_token" \
-d @- << EOF
{
"data":{
"id":1,
"type":"oauth-token",
"attributes":{
"options":{
"key_1":"test",
"key_2":"salesap"
}
}
}
}
EOF
см. проблемы iframe
Текущие настройки вы можете получить из API ресурса current-token.
curl "https://app.salesap.ru/api/v1/current-token" \
-H "Authorization: Bearer api_token"
В ответе вы получите примерно следующее:
{
"data":{
"id":"1",
"type":"oauth-token",
"attributes":{
"options":{
"city":"Moscow",
"product_name":"custom-1421"
},
"token":"api_token",
"scopes":[]
}
}
}
P.S. Это неполный ответ API. Оставлены только важные для текущего контекста ключи. Посмотреть полный формат ответа можно в документации API.
Настройки доступны в data.attributes.options. Если мы опять же говорим о приложении из примера
выше (виджет погоды), то видно что пользователь желает знать прогноз погоды в Москве "city":"Moscow".
А в контексте приложения по генерации меню мы видим что имя продукта у пользователя хранится
в своем поле custom-1421.