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

Угоди

Продажі в роботі: угода йде етапами воронки до виграшу чи програшу, має очікувану суму й товари, з неї виставляється рахунок. Право ролі: opportunity.

Маршрути

GET/opportunity

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

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

GET/opportunity/{id}

Одна картка.

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

GET/opportunity/count

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

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

POST/opportunity

Створити.

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

PUT/opportunity/{id}

Оновити.

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

DELETE/opportunity/{id}

Видалити.

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

POST/opportunity/{id}/move-funnel

Перенести на інший етап чи в іншу воронку: { "funnel_id": 2, "status_id": 9 }. Без status_id угода стає на перший етап воронки.

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

GET/opportunity/document-products/{id}

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

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

POST/opportunity/{id}/create-invoice

Виставити рахунок з угоди.

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

POST/opportunity/{id}/create-act

Створити акт виконаних робіт.

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

GET/opportunity/deleted?since=…

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

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

Усі поля

Обов’язкове лише name. Теги й доп. поля описано в розділі Вкладені дані.

Поле	Тип	Обмеження	Опис
`name`обов.	рядок	≤ 255 симв.	Назва угоди.
`external_id`	рядок	≤ 64 симв.	Ключ запису у вашій системі. Унікальний; пошук: filter[external_id;eq]. Див. «Синхронізація».
`amount`	ціле, копійки		Очікувана сума угоди, копійки.
`currency_id`	id		Валюта (/currency).
`exchange_rate`	десяткове (рядок)		Курс валюти до гривні на дату документа: десяткове число рядком, напр. "41.250000". Для гривні завжди 1; якщо для валюти курс не передано, береться курс довідника.
`repeat`	ціле	0 \| 1	Повторний (1) чи перший (0) продаж.
`description`	рядок	≤ 1024 симв.	Опис / коментар.
`next_step`	рядок	≤ 100 симв.	Наступний крок.
`probability`	ціле	≤ 100	Ймовірність виграшу, %.
`falter_reason_id`	id		Причина програшу (/lookup?type=reason).
`falter_reason_text`	рядок	≤ 250 симв.	Коментар до причини програшу.
`closed_date`	дата-час		Дата закриття.
`status_id`	id		Етап воронки угод. Якщо не передано, ставиться перший етап.
`funnel_id`	id		Воронка (/lead/funnel).
`type_id`	id		Тип угоди (/lookup?type=opp_type).
`source_id`	id		Джерело (/lookup?type=source).
`owner_id`	id		Відповідальний користувач (/user). Якщо не передано, це користувач токена.
`contact_id`	id		Контакт (/contact).
`account_id`	id		Контрагент (/account).
`lead_opportunity_id`	id		Лід, з якого створено угоду.
`project_id`	id		Проєкт.
`project_stage_id`	id		Етап проєкту.
`is_archived`	bool		В архіві. Архівні записи приховує параметр is_archived=true.
`tags`	масив Tag		Теги: [{"id": 3}] або [{"name": "VIP"}]. Передані замінюють усі теги запису. Див. «Вкладені дані».
`id`лише читання	ціле		Ідентифікатор запису.
`cost`лише читання	ціле, копійки		Сума позицій у копійках, рахує сервер.
`payment`лише читання	ціле, копійки		Сплачено за рахунками угоди, у копійках; рахує сервер.
`won_at`лише читання	дата-час		Коли виграно. Ставить сервер при переході на етап kind=won.
`lost_at`лише читання	дата-час		Коли програно. Ставить сервер при переході на етап kind=lost.
`created_by_id`лише читання	id		Хто створив запис.
`shop_id`лише читання	id		Магазин (філія), ставиться з профілю користувача.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`deleted_at`лише читання	дата-час		Час видалення (у звичайних відповідях завжди null).
`tasks`лише читання	масив Task		Завдання запису (лише у відповіді).
`tasks_count`лише читання	ціле
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`version`лише читання	ціле		Службовий лічильник змін запису.

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

opportunity_extra_fields: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.

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

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

Currency → CurrencyFalterReason → LookupStatus → LeadFunnelItemFunnel → LeadFunnelType → LookupSource → LookupOwner → UserCreatedBy → UserShop → ShopContact → ContactAccount → AccountLead → LeadProject → ProjectProjectStage → ProjectStage

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

Воронки та етапи

Воронки угод живуть у тому ж довіднику, що й воронки лідів, але з entity_type=opportunity. Тип етапу kind: open (в роботі), won (виграно), lost (програно).

Воронки угод

GET /api/v1/lead/funnel?filter[entity_type;eq]=opportunity

Етапи воронки 2

GET /api/v1/lead/funnel/lead-funnel-items?filter[funnel_id;eq]=2&order=order

{ "items": [ { "id": 8, "name": "Нерозібрані", "kind": "open", "order": 1 }, ... ] }

Виграш і програш

Перенесіть угоду на етап з kind=won або kind=lost через move-funnel чи звичайний PUT зі status_id. Сервер сам поставить won_at / lost_at; повернення на відкритий етап їх скидає. Від цих дат рахуються плани продажів і комісії.

Позиції документа

Товари й послуги документа. Власного права в позицій немає: читати їх може той, хто бачить документ, а змінювати той, хто може змінювати документ. Сума документа перераховується автоматично.

GET/opportunity/{id}/items

Позиції з товаром і одиницею, з total.

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

POST/opportunity/{id}/items

Додати позицію.

право: opportunity.update10 очк.

PUT/opportunity/{id}/items/{item_id}

Змінити кількість, ціну, знижку.

право: opportunity.update10 очк.

DELETE/opportunity/{id}/items/{item_id}

Видалити позицію.

право: opportunity.update10 очк.

Поле	Тип	Обмеження	Опис
`entity_type`обов.лише читання	рядок		Тип документа, береться зі шляху.
`entity_id`обов.лише читання	id		Id документа, береться зі шляху.
`product_id`обов.	id		Товар. Для kind=custom не потрібен.
`name`	рядок	≤ 120 симв.	Назва рядка. Для kind=custom обов’язкова, для товару береться з картки.
`kind`	рядок	product \| custom, ≤ 10 симв.	product (товар) або custom (довільний рядок без товару, напр. доставка чи послуга).
`cost_price`	ціле, копійки		Собівартість одиниці, копійки. Вводиться лише для kind=custom; у товарного рядка береться з партій і в запиті ігнорується.
`cost_source`	рядок	none \| manual \| product \| batch, ≤ 10 симв.	Звідки собівартість: none, manual, product, batch.
`unit_label`	рядок	≤ 30 симв.	Підпис одиниці.
`input_unit_id`	id		Одиниця введення / упаковка (/product/{id}/units).
`input_quantity`	ціле, ×1000		Кількість в упаковках, ×1000.
`input_price`	ціле, копійки		Ціна упаковки, копійки.
`price`	ціле, копійки		Ціна за одиницю, копійки. При додаванні ставиться базова ціна товару; змінюйте PUT рядка.
`quantity`	ціле, ×1000		Кількість, ×1000.
`discount_amount`	ціле, копійки		Знижка сумою, копійки.
`discount`	ціле	≤ 10000	Знижка, соті частки % (1000 = 10 %). Якщо не передано, діє персональна знижка клієнта.
`exchange_rate`	десяткове (рядок)		Курс перерахунку ціни товару у валюту документа (службове).
`reason_id`	id		Причина (для повернень).
`price_book_id`	id		Прайс-лист, з якого взято ціну.
`status`	рядок		Статус рядка (службове).
`description`	рядок	≤ 255 симв.	Коментар до рядка.
`id`лише читання	ціле		Ідентифікатор запису.
`unit_id`лише читання	id		Одиниця товару (лише у відповіді).
`input_factor`лише читання	десяткове (рядок)		Скільки базових одиниць в упаковці, береться з картки товару.
`product_units`лише читання	масив ProductUnit		Одиниці товару (лише у відповіді).
`total`лише читання	ціле, копійки		Підсумок рядка, рахує сервер.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`version`лише читання	ціле		Службовий лічильник змін запису.

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

batches: лише у відповіді (expand=Batches).
serial_numbers: лише у відповіді (expand=SerialNumbers).

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

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

InputUnit → LookupProduct → ProductReason → LookupPriceBook → PriceBook

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

Додати товар

POST /api/v1/opportunity/85/items
Idempotency-Key: opportunity-85-add-258

{ "product_id": 258, "quantity": 3000 }

Змінити ціну й знижку рядка

PUT /api/v1/opportunity/85/items/323
{ "price": 145000, "discount": 500 }

Документ і рядок беруться зі шляху: entity_type / entity_id у тілі ігноруються. Рядок чужого документа в цьому шляху дає 404. Закритий обліковий період, недостатній залишок чи вже проведений документ дають 422 з поясненням (див. Помилки).

Приклади

Створити угоду

POST /api/v1/opportunity
Idempotency-Key: crm-deal-77

{
  "name": "Освітлення шоуруму",
  "external_id": "deal-77",
  "account_id": 12,
  "amount": 18500000,
  "currency_id": 1,
  "probability": 40
}

Угоди менеджера на етапі 9 з сумою від 100 000 грн

GET /api/v1/opportunity?filter[owner_id;eq]=7&filter[status_id;eq]=9&filter[amount;gte]=10000000&order=-amount

Виставити рахунок на всі позиції

POST /api/v1/opportunity/13/create-invoice
{}

Угоду можна отримати й кваліфікацією ліда (Ліди, прапорець opportunity).