Как работать с дополнительными полями в API

Рассказываем, как получать дополнительные поля, а также передавать и изменять их значения через API

Автор Анастасія Останіна

Обновлено 2 недели назад

Дополнительные (пользовательские) поля позволяют расширить стандартный набор полей сущностей и хранить данные в соответствии с потребностями вашего бизнеса.

Поля создаются в настройках CRM и могут использоваться в API для передачи и получения значений при работе с сущностями.

Получение и использование дополнительных полей

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

Перед началом работы с полями в API рекомендуется получить их список, поскольку для передачи значений требуются параметры:

«uuid» — внешний идентификатор поля (системное название);
«type» — тип поля;
«is_multiple» — мультисписок (да/нет).

Чтобы получить опции для списковых полей, используйте параметр: include=options.

Получение значений полей

Чтобы получить значения дополнительных полей вместе с сущностью, необходимо добавить параметр: include=custom_fields.

Пример URL-запроса для получения списка заказов с дополнительными полями:

https://openapi.keycrm.app/v1/order?include=custom_fields.

Передача значений полей

При создании или обновлении сущности дополнительные поля передаются в массиве «custom_fields», где

«uuid» — внешний идентификатор поля (системное название);
«value» — значение, которое записывается в поле.

Пример передачи значения в одно поле:

"custom_fields": [
  {
    "uuid": "LD_1021",
    "value": "Значение в поле"
  }
]

Пример для нескольких полей:

"custom_fields": [
  {
    "uuid": "LD_1021",
    "value": "Значение в поле"
  },
  {
    "uuid": "LD_1022",
    "value": "Другое значение в другом поле"
  }
]

Типы полей и формат значений

От типа дополнительного поля ("type") зависит формат значения ("value").

Пример значения для каждого типа:

Строка (text) — "Текстовое значение";
Текст (textarea) — "Длинный текст...";
Ссылка (link) — "https://example.com";
Целое число (number) — 10;
Число (float) — число с двумя знаками после запятой: 10,55;
Дата (date) — в формате YYYY-MM-DD: "2026-04-24";
Дата и время (datetime) — в формате ISO 8601 (UTC): "2026-04-29T07:00:00.000000Z";

Обратите внимание! Во всех сущностях используется время UTC (GMT+0).

Переключатель (switcher) — логическое значение: true или false;
Список / мультисписок (select) — массив значений: ["Опция 1", "Опция 2"].

Особенности работы с полями

При работе с дополнительными полями в API следует учитывать:

Значения для полей типа «список» / «мультисписок» (select) должны точно совпадать с опциями, созданными в CRM. Если переданное значение отсутствует среди опций — оно не будет применено;
При обновлении значение поля полностью перезаписывается новым значением, которое было передано;
Очистка значения поля через API не предусмотрена, для текстовых полей в качестве обходного варианта можно передать «.» или «-»;
Дополнительные поля создаются и настраиваются только в интерфейсе CRM.

Теги: дополнительные поля, настраиваемые поля, пользовательские поля, custom_fields, custom fields, API, API

Оцените эту статью