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

Ліди

Вхідні заявки: форми сайту, дзвінки, реклама. Лід рухається етапами воронки й кваліфікується в контакт, контрагента, угоду чи замовлення. Право ролі: lead.

Маршрути

GET/lead

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

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

GET/lead/{id}

Одна картка.

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

GET/lead/count

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

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

POST/lead

Створити.

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

PUT/lead/{id}

Оновити.

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

DELETE/lead/{id}

Видалити.

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

POST/lead/{id}/move-funnel

Перенести в іншу воронку: { "funnel_id": 3, "status_id": 17 }. Без status_id лід потрапляє на перший етап воронки.

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

POST/lead/qualification/{id}

Кваліфікувати: створити з ліда контакт, контрагента, угоду та/або замовлення.

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

GET/lead/funnel

Воронки продажів.

2 очк.

GET/lead/funnel/lead-funnel-items

Етапи воронок: filter[funnel_id;eq]=3.

2 очк.

GET/lead/deleted?since=…

Видалені записи: розділ Синхронізація.

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

Усі поля

Обов’язкових полів немає; передайте хоча б ім’я чи телефон. Канали, теги й доп. поля описано в розділі Вкладені дані.

Поле	Тип	Обмеження	Опис
`external_id`	рядок	≤ 64 симв.	Ключ запису у вашій системі. Унікальний; пошук: filter[external_id;eq]. Див. «Синхронізація».
`name`	рядок	≤ 255 симв.	Назва ліда. Якщо не передано, збирається з імені.
`first_name`	рядок	≤ 80 симв.	Ім’я.
`last_name`	рядок	≤ 80 симв.	Прізвище.
`middle_name`	рядок	≤ 80 симв.	По батькові.
`company`	рядок	≤ 255 симв.	Компанія з заявки.
`phone`	рядок	≤ 30 симв.	Основний телефон (окреме поле; телефони для пошуку й дзвінків зберігаються в channels).
`email`	рядок	≤ 80 симв.	Основний email (окреме поле; адреси для розсилок зберігаються в channels).
`website`	рядок	≤ 150 симв.	Сайт.
`amount`	ціле, копійки		Очікувана сума, копійки.
`exchange_rate`	десяткове (рядок)		Курс валюти до гривні на дату документа: десяткове число рядком, напр. "41.250000". Для гривні завжди 1; якщо для валюти курс не передано, береться курс довідника.
`description`	рядок	≤ 1024 симв.	Опис / коментар.
`utm_source`	рядок	≤ 120 симв.	UTM-мітка джерела.
`currency_id`	id		Валюта (/currency).
`source_id`	id		Джерело (/lookup?type=source).
`status_id`	id		Етап воронки (/lead/funnel/lead-funnel-items). Якщо не передано, ставиться перший етап.
`type_id`	id		Тип ліда (/lookup?type=lead_type).
`falter_reason_id`	id		Причина програшу (/lookup?type=reason).
`falter_reason_text`	рядок	≤ 250 симв.	Коментар до причини програшу.
`funnel_id`	id		Воронка (/lead/funnel).
`owner_id`	id		Відповідальний користувач (/user). Якщо не передано, це користувач токена.
`is_archived`	bool		В архіві. Архівні записи приховує параметр is_archived=true.
`marketing_attribution_id`	id		Маркетингова атрибуція (службове).
`tags`	масив Tag		Теги: [{"id": 3}] або [{"name": "VIP"}]. Передані замінюють усі теги запису. Див. «Вкладені дані».
`id`лише читання	ціле		Ідентифікатор запису.
`import_id`лише читання	id		Id імпорту, яким створено запис.
`won_at`лише читання	дата-час		Коли виграно. Ставить сервер при переході на етап kind=won.
`lost_at`лише читання	дата-час		Коли програно. Ставить сервер при переході на етап kind=lost.
`created_by_id`лише читання	id		Хто створив запис.
`shop_id`лише читання	id		Магазин (філія), ставиться з профілю користувача.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`deleted_at`лише читання	дата-час		Час видалення (у звичайних відповідях завжди null).
`tasks`лише читання	масив Task		Завдання запису (лише у відповіді).
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`version`лише читання	ціле		Службовий лічильник змін запису.

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

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

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

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

Currency → CurrencySource → LookupStatus → LeadFunnelItemType → LookupFalterReason → LookupFunnel → LeadFunnelOwner → UserCreatedBy → UserShop → ShopMarketingAttribution → MarketingAttributionAccount → AccountContact → ContactOrder → OrderOpportunity → Opportunity

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

Заявка з сайту

POST /api/v1/lead
Idempotency-Key: form-2026-09-30-000731

{
  "first_name": "Олена",
  "company": "ТОВ «Ромашка»",
  "external_id": "form-731",
  "utm_source": "google",
  "description": "Хочу розрахунок на 200 шт.",
  "channels": [
    { "type": "phone", "value": "+380671234567", "label": "Мобільний", "is_primary": true },
    { "type": "email", "value": "olena@example.com", "label": "Робочий" }
  ],
  "tags": [ { "name": "Сайт" } ],
  "lead_extra_fields": [
    { "field_id": 1105, "value": "2820" },
    { "field_id": 1106, "value": "|2822|,|2824|" }
  ]
}

Телефон і email кладіть у channels: за ними працює пошук (filter[channels.phone;like]) і дзвінки. Поля phone / email самого ліда є окремими рядками й з каналами не синхронізуються. Формати описано в розділі Вкладені дані.

Створену кваліфікацією угоду далі ведіть через Угоди. Бізнес-процеси, налаштовані на створення ліда (розподіл, сповіщення, завдання), спрацьовують і для лідів з API.

Кваліфікація

Прапорці вирішують, що створити; решта полів містить дані для створених записів.

POST /api/v1/lead/qualification/15

{
  "contact": true,
  "account": true,
  "order": true,
  "first_name": "Олена",
  "last_name": "Коваль",
  "company": "ТОВ «Ромашка»",
  "owner_id": 7,
  "is_order_products": true
}

Поля

Поле	Опис
`contact`, `account`, `opportunity`, `order`	Що створити (true/false).
`owner_id`, `account_owner_id`, `opportunity_owner_id`, `order_owner_id`	Відповідальні за створені записи.
`is_contact_requisites`, `is_account_address`, ...	Перенести реквізити й адреси ліда.
`is_opportunity_products`, `is_order_products`	Перенести товари ліда.
`opportunity_name`, `amount`, `currency_id`	Дані угоди.