Документація API/CRM/Контакти

Контакти

Фізичні особи: клієнти, контактні особи контрагентів. Право ролі: contact.

Маршрути

GET/contact

Список контактів з пагінацією, фільтрами й total.

право: contact.view2 очк.

GET/contact/{id}

Одна картка.

право: contact.view1 очк.

GET/contact/count

Лише кількість за тими самими фільтрами (голе число).

право: contact.view2 очк.

POST/contact

Створити.

право: contact.create5 очк.

PUT/contact/{id}

Оновити.

право: contact.update5 очк.

DELETE/contact/{id}

Видалити.

право: contact.delete5 очк.

GET/contact/deleted?since=...

Видалені з моменту since, див. Синхронізація.

право: contact.view2 очк.

Усі поля

Обов’язкове лише first_name. Канали, теги й доп. поля описані в розділі Вкладені дані, там само окремі маршрути для адрес і реквізитів.

Поле	Тип	Обмеження	Опис
`first_name`обов.	рядок	≤ 50 симв.	Ім’я.
`external_id`	рядок	≤ 64 симв.	Ключ запису у вашій системі. Унікальний; пошук: filter[external_id;eq]. Див. «Синхронізація».
`last_name`	рядок	≤ 50 симв.	Прізвище.
`middle_name`	рядок	≤ 50 симв.	По батькові.
`phone`	рядок	≤ 20 симв.	Основний телефон (окреме поле; телефони для пошуку й дзвінків зберігаються в channels).
`email`	рядок	≤ 255 симв.	Основний email (окреме поле; адреси для розсилок зберігаються в channels).
`position`	рядок	≤ 120 симв.	Посада.
`description`	рядок	≤ 1024 симв.	Опис / коментар.
`personal_discount`	число	≤ 100	Персональна знижка, % (0–100). Підставляється в позиції документів клієнта.
`credit_limit`	ціле, копійки		Кредитний ліміт, копійки.
`utm_source`	рядок	≤ 255 симв.	UTM-мітка джерела.
`birthdate`	дата-час		Дата народження. Не може бути в майбутньому.
`type_id`	id		Тип контакту (/lookup?type=ct_type). Якщо не передано, ставиться тип за замовчуванням.
`owner_id`	id		Відповідальний користувач (/user). Якщо не передано, це користувач токена.
`is_archived`	bool		В архіві. Архівні записи приховує параметр is_archived=true.
`account_id`	id		Контрагент (/account).
`price_book_id`	id		Прайс-лист (/price-book).
`lead_contact_id`	id		Лід, з якого створено контакт.
`tags`	масив Tag		Теги: [{"id": 3}] або [{"name": "VIP"}]. Передані замінюють усі теги запису. Див. «Вкладені дані».
`id`лише читання	ціле		Ідентифікатор запису.
`name`лише читання	рядок	≤ 152 симв.	ПІБ одним рядком, його збирає сервер з прізвища, імені й по батькові.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`deleted_at`лише читання	дата-час		Час видалення (у звичайних відповідях завжди null).
`created_by_id`лише читання	id		Хто створив запис.
`shop_id`лише читання	id		Магазин (філія), ставиться з профілю користувача.
`tasks`лише читання	масив Task		Завдання запису (лише у відповіді).
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`import_id`лише читання	id		Id імпорту, яким створено запис.
`opportunities`лише читання	масив Opportunity		Угоди контакту (лише у відповіді).
`version`лише читання	ціле		Службовий лічильник змін запису.

Вкладені масиви

channels: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.
entity_tags: звʼязки з тегами приходять лише у відповіді (з expand=EntityTags.Tag), а пишуться полем tags.
contact_extra_fields: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.
team: лише у відповіді (expand=Team).

Повʼязані обʼєкти для ?expand= (7)

Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.

Type → LookupOwner → UserCreatedBy → UserShop → ShopAccount → AccountPriceBook → PriceBookLead → Lead

Службові поля у відповіді, ігноруйте: OldContact.

Приклади

Створити контакт з каналами, тегами й доп. полями

POST /api/v1/contact
Idempotency-Key: site-user-731

{
  "first_name": "Олена",
  "last_name": "Коваль",
  "external_id": "site-user-731",
  "account_id": 12,
  "channels": [
    { "type": "phone", "value": "+380671234567", "label": "Мобільний", "is_primary": true },
    { "type": "email", "value": "olena@example.com", "label": "Робочий" }
  ],
  "tags": [ { "name": "Сайт" } ],
  "contact_extra_fields": [
    { "field_id": 1101, "value": "Київ" },
    { "field_id": 1102, "value": "2814" }
  ]
}

Картка разом із каналами й доп. полями

GET /api/v1/contact/42?expand=Channels,ContactExtraFields

Знайти за телефоном

GET /api/v1/contact?filter[channels.phone;like]=671234567&fields=id,first_name,last_name

Змінити відповідального (решта не змінюється)

PUT /api/v1/contact/42
{ "owner_id": 7 }

Перед створенням шукайте контакт за телефоном чи external_id, тоді в базі не з’являться дублі.