REST: crm.userfield (пользовательские поля)

Пользовательские поля (UF, userfield) расширяют стандартные сущности CRM собственными данными: номером договора, датой монтажа, ссылкой на внешнюю систему. Семейство методов crm.{entity}.userfield.* позволяет создавать и настраивать такие поля программно, что критично для воспроизводимого развёртывания интеграций.

Как устроены пользовательские поля

Пользовательские поля создаются отдельно для каждой сущности CRM, и у каждой — свой набор методов:

• crm.deal.userfield.* — поля сделок;
• crm.lead.userfield.* — поля лидов;
• crm.contact.userfield.* — поля контактов;
• crm.company.userfield.* — поля компаний.

Внутри каждого семейства доступны add, update, get, list, delete. Имя поля всегда начинается с префикса UF_CRM_, а обращаться к нему при чтении и записи сущности нужно именно по этому имени.

Типы пользовательских полей

Тип задаётся полем USER_TYPE_ID. Основные типы, которые встречаются в интеграциях:

Полный список типов, доступных на конкретном портале, вернёт метод crm.deal.userfield.fields и метаданные списочных настроек.

Создание поля: crm.deal.userfield.add

Простое строковое поле «Номер договора» для сделок создаётся так:

POST /rest/1/xxxxxxxx/crm.deal.userfield.add.json
{
  "fields": {
    "FIELD_NAME": "CONTRACT_NO",
    "USER_TYPE_ID": "string",
    "XML_ID": "contract_no",
    "MANDATORY": "N",
    "MULTIPLE": "N",
    "EDIT_FORM_LABEL": { "ru": "Номер договора" },
    "LIST_COLUMN_LABEL": { "ru": "Договор" }
  }
}

В FIELD_NAME префикс UF_CRM_ добавлять не нужно — система подставит его сама. Метод вернёт числовой ID поля, а его итоговое имя будет UF_CRM_CONTRACT_NO. Заголовки задаются массивом с языковыми ключами.

Списочные поля (enumeration)

Поле-список требует передачи вариантов в поле LIST. Каждый вариант — объект со значением и (опционально) сортировкой:

POST /rest/1/xxxxxxxx/crm.deal.userfield.add.json
{
  "fields": {
    "FIELD_NAME": "SOURCE_CHANNEL",
    "USER_TYPE_ID": "enumeration",
    "LIST": [
      { "VALUE": "Сайт",   "DEF": "Y", "SORT": 10 },
      { "VALUE": "Телефон", "SORT": 20 },
      { "VALUE": "Партнёр", "SORT": 30 }
    ]
  }
}

Чтение и запись значений в сущности

После создания поле становится доступным в обычных методах сущности под своим полным именем. Запись значения при обновлении сделки:

POST /rest/1/xxxxxxxx/crm.deal.update.json
{
  "id": 340,
  "fields": { "UF_CRM_CONTRACT_NO": "Д-2026/145" }
}

Чтобы прочитать значение, добавьте имя поля в select метода crm.deal.list или получите его через crm.deal.get. Множественное поле (MULTIPLE = Y) возвращается и записывается массивом значений.

• Одиночное поле — скалярное значение;
• Множественное поле — массив;
• Файловое поле — при записи base64-содержимое, при чтении — ссылка на скачивание.

Отдельного внимания заслуживает тип crm — привязка к другой сущности. В его настройках указывается, какие именно сущности можно выбирать (контакт, компания, сделка, лид), а значение хранится в виде префиксованного идентификатора, например C_145 для контакта или CO_77 для компании. Если поле допускает несколько типов сущностей, при записи важно передавать значение именно с корректным префиксом, иначе связь не установится. Тип employee хранит ID пользователя портала и удобен, когда нужно закрепить за сделкой не ответственного, а, например, куратора или технического специалиста из внешней системы.

Управление полями как кодом

Поскольку поля создаются через REST, их описание удобно хранить в репозитории и разворачивать одинаково на dev-, stage- и prod-порталах. Рекомендуемый подход:

1. Описать все UF-поля в конфигурационном файле (имя, тип, заголовки, списки);
2. При деплое проверять наличие поля через crm.deal.userfield.list с фильтром по XML_ID;
3. Если поля нет — создавать, если есть — при необходимости обновлять;
4. Использовать XML_ID как стабильный внешний идентификатор для сопоставления.

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

Итог

Пользовательские поля — основа гибкой CRM: через crm.{entity}.userfield.* вы создаёте их программно, задаёте тип через USER_TYPE_ID и обращаетесь по имени с префиксом UF_CRM_. Два момента требуют внимания: списочные поля работают через числовые ID вариантов, а множественные — через массивы. Хранение описаний полей в коде с ключом XML_ID делает развёртывание предсказуемым.

Мы проектируем структуру пользовательских полей под задачи бизнеса и разворачиваем её одинаково на всех окружениях, связывая поля с данными сайта и 1С. Если нужна воспроизводимая настройка CRM и обмен по кастомным полям — поможем реализовать.