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

Контрагенти

Компанії та ФОП: клієнти, постачальники, партнери. Право ролі: account.

Маршрути

GET/account

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

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

GET/account/{id}

Одна картка.

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

GET/account/count

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

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

POST/account

Створити.

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

PUT/account/{id}

Оновити.

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

DELETE/account/{id}

Видалити.

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

GET/account/deleted?since=…

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

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

Усі поля

Обов’язкове лише name. Канали, теги, доп. поля, адреси й реквізити (ЄДРПОУ, IBAN) описані в розділі Вкладені дані.

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

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

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

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

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

Owner → UserCreatedBy → UserShop → ShopType → LookupLead → LeadPriceBook → PriceBook

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

Приклади

Створити контрагента з кодом з 1С

POST /api/v1/account
{
  "name": "ТОВ «Ромашка»",
  "external_id": "1c-000123",
  "channels": [ { "type": "phone", "value": "+380441234567", "label": "Офіс" } ],
  "tags": [ { "name": "Опт" } ]
}

Додати реквізити

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

Знайти за ЄДРПОУ

GET /api/v1/account?filter[requisites.tax_number;eq]=12345678&fields=id,name

payment_details у тілі контрагента не приймаються, реквізити передавайте тільки через /payment-detail.