CRM API: дополнительные поля
Дополнительные поля
entityType принимает contact, company или deal. Поддерживаются типы text, textarea, number,
money, boolean, date, datetime, select, multiselect, phone, email и url.
| Метод | Путь | Scope | Назначение |
|---|---|---|---|
GET | /custom-fields/definitions | crm_custom_fields_read | Список определений |
GET | /custom-fields/definitions/:definitionUuid | crm_custom_fields_read | Определение по UUID |
POST | /custom-fields/definitions | crm_custom_fields_manage | Создать определение |
PATCH | /custom-fields/definitions/:definitionUuid | crm_custom_fields_manage | Обновить определение с CAS |
POST | /custom-fields/definitions/:definitionUuid/archive | crm_custom_fields_manage | Архивировать определение с CAS |
POST | /custom-fields/definitions/:definitionUuid/restore | crm_custom_fields_manage | Восстановить определение с CAS |
POST | /custom-fields/definitions/:definitionUuid/options | crm_custom_fields_manage | Создать вариант с CAS определения |
PATCH | /custom-fields/definitions/:definitionUuid/options/:optionUuid | crm_custom_fields_manage | Обновить вариант с CAS варианта и определения |
POST | /custom-fields/definitions/:definitionUuid/options/:optionUuid/archive | crm_custom_fields_manage | Архивировать вариант с CAS |
POST | /custom-fields/definitions/:definitionUuid/options/:optionUuid/restore | crm_custom_fields_manage | Восстановить вариант с CAS |
GET | /custom-fields/assignments/:entityType | crm_custom_fields_read + scope чтения сущности | Явные значения полей сущности |
PATCH | /custom-fields/assignments/:entityType | crm_custom_fields_manage + scope записи сущности | Явно назначить или очистить значения с CAS |
Все mutation-маршруты требуют Idempotency-Key. Для списка definitions обязателен entityType;
доступны includeArchived, externalId, cursor и limit. includeArchived не снимает hard cap:
страница содержит не более 100 записей.
Definitions могут получить externalId при создании. В assignments сущность и поле задаются ровно
одной ссылкой — { "id": "..." } или { "externalId": "..." }. Варианты select/multiselect в
v1 адресуются только UUID. PATCH assignments принимает от 1 до 100 явных назначений; null очищает
значение, а expectedVersion сравнивается с customFieldsVersion всей сущности.
Поле сделки можно ограничить воронками: pipelineIds принимается при создании и в PATCH,
возвращается в ответе и пустой список означает «во всех воронках». В списке определений фильтр
pipelineUuid оставляет поля этой воронки вместе с полями без привязки. Для полей клиента
непустой pipelineIds отклоняется.
Объект settings определения свободный, но три ключа понимает интерфейс: required — поле
обязательно при заполнении карточки оператором (API, импорт и интеграции такую проверку не
делают), showInList — поле доступно как колонка в списках, showInChat — поле показывается в
панели клиента в чате. Все три булевы; showInList и showInChat по умолчанию включены.
Остальные ключи сохраняются как есть.
Для phone и email нужен crm_contact_data_write, для money — crm_amounts_write. Это правило
распространяется и на defaultValue определения. Без соответствующего read-scope чувствительное
defaultValue и назначенное значение не выдаются; в audit snapshot исходное значение также не
раскрывается.