Вкладені дані

Телефони, email, посилання й месенджери. Є у контактів, контрагентів і лідів.

"channels": [
  { "type": "phone",  "value": "+380671112233", "label": "Мобільний", "is_primary": true },
  { "type": "email",  "value": "olena@example.com", "label": "Робочий" },
  { "type": "social", "category": "telegram", "value": "@olena", "label": "Telegram" },
  { "type": "link",   "value": "https://acme.ua", "label": "Сайт" }
]

• ●Телефон нормалізується: +38 (067) 111-22-33 збережеться як +380671112233.
• ●label обов’язковий для контактів (інакше 422 channels[0].label); передавайте його завжди.
• ●Значення type сервер не обмежує, але фільтр filter[channels.phone;like] і дзвінки працюють лише зі стандартними phone, email, link, social.
• ●Окремі поля phone та email запису не є каналами: вони не синхронізуються з channels.
• ●Для читання потрібен ?expand=Channels (у картці й у списку), без нього channels: null.

Є в контактів, контрагентів, лідів, угод, завдань, товарів, замовлень і рахунків. Передаються при створенні й оновленні.

"tags": [ { "id": 3 }, { "name": "Опт" }, { "name": "VIP", "color": "#e11d48" } ]

• ●{"id": 3} означає наявний тег. {"name": "…"} означає тег з такою назвою в цій сутності; якщо його немає, він створюється.
• ●Переданий масив замінює всі теги запису. tags: [] знімає всі.
• ●Читання: у картці (GET /contact/42) приходить масив tags з {"id", "name", "color"}. У списку tags порожнє, тому додайте ?expand=EntityTags.Tag, теги будуть у entity_tags[].tag.
• ●Фільтр: filter[tags;eq;or]=3,7, без тегу: filter[tags;neq]=3.

Поля, які компанія налаштувала сама. Масив називається за сутністю:

"contact_extra_fields": [
  { "field_id": 1101, "value": "Київ" },
  { "field_id": 1102, "value": "2814" },
  { "field_id": 1103, "value": "|2816|,|2818|" }
]

Які поля є і їхні id

GET /api/v1/extra-fields?entity=contact
→ { "items": [ { "id": 1102, "label": "Регіон", "field_type": "list", "is_required": false,
                 "options": [ { "id": 2813, "name": "Київ" }, ... ] }, ... ] }

Формат value за типом поля

• ●Значення передається рядком до 512 символів. Довший рядок дає 422.
• ●Платежі: у POST і PUT той самий масив extra_fields.
• ●Для списків передається id варіанта, а не назва: "Київ" або "2816,2818" дають 422 «некоректний формат значення»; id чужого поля дає 422 «опція не належить полю».
• ●Варіанти полів з пошуком (тисячі значень) у визначенні поля не приходять, їх треба шукати: GET /extra-fields/option?field_id=1102&q=Київ або &ids=2813,2814.
• ●Очистити поле: {"field_id": 1101, "value": ""}.
• ●field_id чужої сутності або такого, якого не існує, дає 422 «не належить цій сутності».
• ●Обов’язкове поле (is_required) при створенні без значення дає 422 з ключем f_<id>. При оновленні перевіряються лише передані поля.
• ●Поля, приховані від ролі користувача токена, не видно в /extra-fields.

Фільтр за доп. полем: filter[f_1102;eq]=2814.

Адреси контактів, контрагентів і лідів. Читати й змінювати може той, хто бачить / змінює власника.

POST /api/v1/address
{ "entity_type": "account", "entity_id": 12, "type": "legal",
  "country": "Україна", "region": "Київська", "city": "Київ",
  "address": "вул. Хрещатик, 1, оф. 5", "index": "01001" }

Фільтр записів за адресою: GET /account?filter[address.city;eq]=Львів.

Банківські й податкові реквізити контрагентів, контактів і лідів для рахунків і актів. Права успадковуються від власника.

Що обов’язкове залежно від contractor_type

• ●«Банк» = currency (3 великі літери: UAH, USD, EUR) і iban (український: UA + 27 цифр; пробіли прибираються).
• ●Платник ПДВ (vat_payer: true) потребує vat_number, 10 або 12 цифр.
• ●Помилки повертаються як 422 з переліком полів у error.details.

POST /api/v1/payment-detail
{
  "account_id": 12,
  "contractor_type": "legal_entity",
  "country": "Україна",
  "legal_name": "ТОВ «Ромашка»",
  "tax_number": "12345678",
  "address": "м. Київ, вул. Хрещатик, 1",
  "vat_payer": true,
  "vat_number": "123456789012",
  "currency": "UAH",
  "iban": "UA213223130000026007233566001",
  "bank_name": "АТ «Приватбанк»"
}