Дополнительные поля – это основной механизм в laxo для хранения данных, которые не входят в базовую структуру объектов. С их помощью можно расширять список хранимых данных для контактов и сделок без изменения основной модели API: добавлять телефоны, адреса эл. почты, организации, комментарии, даты, суммы, списки значений и другие параметры.
С подробной информацией о дополнительных полях с точки зрения бизнеса можно познакомиться в базе знаний.
Дополнительное поле имеет несколько важных свойств: системное имя, отображаемое имя, тип, область видимости, ограничения по одновременно хранимому количеству значений, порядок отображения и другие параметры.
Само значение поля хранится отдельно и привязывается к конкретному объекту: контакту или сделке.
Область видимости определяет, к каким объектам относится поле и где оно используется. Например, область contact используется для полей контактов, а область order – для полей любых сделок. Также область видимости может быть связана с отделом (группой) пользователей, что позволяет разделять наборы полей для сделок.
Часть областей видимости и полей создается по умолчанию. Например, для контактов могут быть предустановлены поля телефона, рабочего телефона, эл. почты, адреса, должности, организации, дня рождения, заметки и аватара. Для сделок по умолчанию может использоваться поле Причина отмены. Такие системные поля могут иметь ограничения на изменение или удаление.
Каждое поле имеет свой тип. От типа зависит, как значение сохраняется, возвращается в ответах API и обрабатывается при изменении. Например, для телефонных полей автоматически выполняется нормализация номера. API поддерживает возможность создания кастомных типов полей.
Поля типа SET используются для выбора значения из заранее заданного набора вариантов. В laxo есть статические и динамические SET-поля. Такое поле хранит не произвольное значение напрямую, а ссылку на один из вариантов набора, поэтому работа с ним отличается от других типов.
// Добавление номера телефона для контакта (обычный тип поля)
[
{
"class": "contact",
"method": "add_field",
"sid": "<<SID>>",
"param": {
"contact_id": 10,
"field_id": 3,
"value": "79999999999"
]
}
}
]// Добавление существующей организации для контакта (поле SET-типа)
[
{
"class": "contact",
"method": "add_field",
"sid": "<<SID>>",
"param": {
"contact_id": 10,
"field_id": 2,
"value": {
"field_value_id": 25 // Указывается ID значения поля, которое нужно предварительно получить через field_value_set.get_values
}
]
}
}
]// Добавление нового значения для контакта (поле SET-типа)
[
{
"class": "contact",
"method": "add_field",
"sid": "<<SID>>",
"param": {
"contact_id": 10,
"field": [
{
"field_id": 2,
"value": {
"value": "ООО Ромашка" // Если такого варианта еще нет, то API добавит его и свяжет с объектом
}
}
]
}
}
]// Получить список значений поля (поле SET-типа)
[
{
"class": "field_value_set",
"method": "get_values",
"sid": "<<SID>>",
"param": {
"field_id": 2
}
}
]| ПРЕДУСТАНОВЛЕННЫЕ ТИПЫ ДОПОЛНИТЕЛЬНЫХ ПОЛЕЙ | |
|---|---|
| Номер | Примечание |
Int | Целое число. |
Char | Строковое значение. Многие другие типы полей базируются на данном типе. |
Decimal | Дробное число. |
File | Файл. Используется для хранения идентификатора файла, прикрепленного к объекту. |
Object/File | Объект или файл. Используется для хранения набора файлов, например галереи. |
Photo | Фото. Специализированный тип на базе типа File. |
List | Список значений. Используется для хранения нескольких вложенных значений внутри одного поля. |
StaticSet | Статический набор значений. Используется для выбора одного или нескольких вариантов из заранее заданного списка. Варианты набора задаются заранее и используются как справочник значений для поля. |
DynamicSet | Динамический набор значений. Используется для выбора значения из набора, который может пополняться в процессе работы. Если передано новое значение, API может создать новый вариант набора и привязать его к объекту. |
Date | Дата. Тип на базе Int. Используется для хранения даты или даты и времени в формате timestamp. |
Colour | Цвет. Тип на базе Char. |
Email | Email-адрес. Тип на базе Char. |
Phone | Телефон. Тип на базе Char. |
Money | Денежное значение. Тип на базе Decimal. |
Boolean | Логическое значение. Тип на базе Int. |
Textarea | Текстовая область. Тип на базе Char. Формат отображения полей такого типа адаптирован для длинного текста. |
Service | Список услуг. Тип на базе StaticSet, содержащий JSON-объект со свойствами услуги. |
Методы этого раздела относятся к нескольким категориям API: field_scope, field_type, field, field_value и field_value_set. Методы field_scope используются для управления областями видимости. Методы field_type позволяют получить или создать типы полей. Методы field описывают структуру дополнительных полей. Методы field_value используются для получения, изменения и удаления значений полей у объектов. Методы field_value_set используются для работы с вариантами значений SET-полей.