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

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

Покрокове налаштування: [Як налаштувати поля клієнтів](/uk/settings/how-to/configure-client-fields.md). Видимість можна змінити там само (одна кнопка «Зберегти» в заголовку) або на [сторінці op-settings](/uk/settings/how-to/configure-client-card-fields.md) — той самий блок, інше збереження.

---

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

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

```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` **не** потрапляють у форму реєстрації навіть з увімкненим прапорцем. Детальніше про налаштування інстансу та ролей — [Налаштування інстансу](/uk/settings/how-to/configure-instance.md), [Ролі](/uk/settings/how-to/configure-roles.md).

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

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

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

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

Приклад:

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

---

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

У нижній частині редактора — блок **«Приклади JSON»**: п’ять готових фрагментів тієї ж структури, що й у [інструкції](/uk/settings/how-to/configure-client-fields.md) (розділ **Приклади JSON**). У документації до кожного сценарію додано розгорнутий опис призначення; у продукті залишаються лише короткі назви перемикача.

---

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

- Невалідний JSON не зберігається: перевірте коми, лапки та дужки.
- Перед масовими змінами збережіть копію конфігурації.
- Видалення поля з конфігурації не видаляє автоматично ключ з налаштувань видимості картки; за потреби оновіть [редактор полів у картці клієнта](/uk/settings/how-to/configure-client-card-fields.md).