Довідник JSON: поля клієнта (`custom_fields_json`)

Короткий опис властивостей об’єкта одного поля у налаштуваннях Поля клієнтів (/settings-page/client-fields). Збережена конфігурація містить обгортку з ключем custom_fields_json; усередині — об’єкт, де ключ — технічна назва поля (латиницею), значення — опис поля.

Покрокове налаштування: Як налаштувати поля клієнтів. Видимість можна змінити там само (одна кнопка «Зберегти» в заголовку) або на сторінці op-settings — той самий блок, інше збереження.

Структура збережених даних

Після збереження в налаштуваннях інстансу використовується параметр client_fields_json; усередині — об’єкт з полем custom_fields_json:

{
  "custom_fields_json": {
    "department": {
      "type": "STRING",
      "label": "Відділ"
    }
  }
}

Значення, які оператори вводять у картці клієнта, потрапляють у extra_data клієнта за ключами полів.

Базові властивості поля

Властивість	Обов’язковість	Опис
`type`	Фактично обов’язкове	Тип даних поля. Див. таблицю типів нижче.
`label`	Рекомендовано	Підпис поля в інтерфейсі (картка клієнта, таблиці).

Дозволені значення `type`

Значення	Призначення
`STRING`	Короткий текст
`TEXT`	Багаторядковий текст
`SELECT`	Вибір з фіксованого списку
`SELECTAPI`	Вибір з джерела через API
`FILE`	Файл
`INTEGER`	Ціле число
`BIGINT`	Велике ціле
`FLOAT`	Дробове число
`DATE`	Дата
`BOOLEAN`	Логічне так/ні

Додаткові властивості (форма та JSON)

На сторінці Поля клієнтів частину параметрів можна задати в картці поля (розділи форми); усі вони також можуть бути внесені або виправлені в JSON. У збереженому JSON багато перемикачів зберігаються як рядок "true"; якщо опція вимкнена — ключ зазвичай відсутній.

Загальні та редагування

Ключ	Тип у JSON	Що робить
`default`	рядок	Початкове значення при створенні / за замовчуванням (якщо підтримується сценарієм відображення).
`unique`	`"true"`	Заборона дублікатів значення по полю (логіка перевірки залежить від сценаріїв використання).
`non_editable`	`"true"`	Поле лише для перегляду: оператори не змінюють значення в інтерфейсі.

Відображення в таблиці

Ключ	Тип у JSON	Що робить
`sortable`	`"true"`	Увімкнути сортування за колонкою в таблиці клієнтів.
`width`	рядок	Ширина колонки в пікселях, наприклад `"120"`.
`align`	`""` / `"start"` / `"center"` / `"end"`	Вирівнювання заголовка колонки. Порожнє — поведінка за замовчуванням.
`display_in_table`	`""` / `"image"`	Режим відображення в комірці: зокрема `image` — показ зображення (за наявності відповідних даних).
`display_type`	`"link"`	Для рядкових полів: значення трактується як посилання, відкривається в новій вкладці.
`click_action`	`"open"`	Для рядкових полів: по кліку відкривається модальне вікно редагування. Не комбінуйте з `display_type: "link"` — у формі вибір «дії при кліку» взаємовиключний.

Видимість

Ключ	Тип у JSON	Що робить
`hidden_all`	`"true"`	Приховати поле скрізь у картці та пов’язаних формах (як у перемикача в інтерфейсі).
`hidden_in_table`	`"true"`	Не показувати колонку у списку вибору колонок таблиці.
`hide_in_filter`	`"true"`	Приховати поле у фільтрах.
`hidden_in_create_popup`	`"true"` або `true`	Приховати поле у вікні швидкого створення (якщо використовується такий сценарій).
`portal_registration`	`"true"` або `true`	Показувати поле на формі self-registration Client Portal (`/register`). Значення зберігаються в `OpClients.extra_data`. У UI Constructor — перемикач «Показувати при реєстрації в Client Portal» на `/settings-page/client-fields`. Не впливає на видимість у картці оператора.

Client Portal (registration)

Прапорець portal_registration працює разом із instance settings:

portal_registration_enabled — увімкнути/вимкнути реєстрацію
portal_registration_role_id — роль нових portal-користувачів

Типи SELECTAPI і FILE не потрапляють у форму реєстрації навіть з увімкненим прапорцем. Детальніше про налаштування інстансу та ролей — Налаштування інстансу, Ролі.

Валідація: `rules`

Масив рядків — імена правил. Доступні значення в інтерфейсі підбору:

Значення	Призначення
`required`	Обов’язкове заповнення
`email`	Формат email
`digits`	Лише цифри
`latin`	Лише латинські символи
`latinDigits`	Латиниця та цифри
`stringMaxLength`	Обмеження довжини рядка (потрібні додаткові параметри в конфігурації — у складних випадках правте JSON за зразками)
`json`	Перевірка формату JSON

Складні перехресні перевірки та умовна логіка можуть описуватися окремим об’єктом validate у JSON. Для таких сценаріїв використовуйте Приклади JSON на сторінці налаштувань або резервну копію перед змінами.

Приклад:

"email_field": {
  "type": "STRING",
  "label": "Email",
  "rules": ["required", "email"]
}

Приклади JSON на сторінці

У нижній частині редактора — блок «Приклади JSON»: п’ять готових фрагментів тієї ж структури, що й у інструкції (розділ Приклади JSON). У документації до кожного сценарію додано розгорнутий опис призначення; у продукті залишаються лише короткі назви перемикача.

Обмеження та поради

Невалідний JSON не зберігається: перевірте коми, лапки та дужки.
Перед масовими змінами збережіть копію конфігурації.
Видалення поля з конфігурації не видаляє автоматично ключ з налаштувань видимості картки; за потреби оновіть редактор полів у картці клієнта.

Довідник JSON: поля клієнта (custom_fields_json)