Як працювати з додатковими полями в API

Розповідаємо, як отримувати додаткові поля, а також передавати та змінювати їх значення через API

Написано Юлія Бакум

Оновлено 3 дні тому

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

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

Отримання та використання додаткових полів

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

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

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

Щоб отримати опції для спискових полів, використовуйте параметр: include=options.

Отримання значень полів

Щоб отримати значення додаткових полів разом із сутністю, потрібно додати параметр: include=custom_fields.

Приклад Request 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, апі

Чи була наша стаття корисною?