Поля сделки в REST 3.0

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Поля относятся к методам REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.

Поля сделки возвращают методы crm.deal.get и crm.deal.list, а принимают методы crm.deal.add и crm.deal.update. Список полей с признаками возвращает метод crm.deal.field.list.

Часть полей существует в двух видах: как идентификатор и как связанный объект, например assignedById и assignedBy. Идентификатор можно передать при записи, а связанный объект — только запросить в select.

Какие поля принимают и возвращают методы

Метод

Принимает

Возвращает

crm.deal.add

Поля таблицы Объект сделки, которые можно изменять, и пользовательские поля. Обязательных полей нет: сделка создается и с пустым объектом fields

Идентификатор созданной сделки id

crm.deal.update

id сделки и те же поля, что add. Поля, которых нет в fields, сохраняют текущие значения

Признак успеха true

crm.deal.get

id сделки и select

Без select — только id. С select — только перечисленные поля, id не добавляется автоматически. Связанный объект целиком, например assignedBy, возвращает все свои поля, а путь через точку, например assignedBy.firstName, — только выбранные. Подробнее — в разделе Связанные объекты

crm.deal.list

select, filter, order, pagination

Без select — только id каждой сделки. Поля и связанные объекты запрашиваются в select так же, как в get

Поля с пометкой «только чтение» методы add и update не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION с текстом «Поле "contactId" не доступно к заполнению». Связанные объекты, например company и stage, тоже только для чтения: для записи передавайте идентификатор — companyId, stageId.

Поля со значениями из справочников метод проверяет при записи. Если значения нет в справочнике, метод вернет ошибку «Значение поля не содержится в списке допустимых значений». Для стадии, типа сделки, источника и валюты в тексте ошибки перечислены допустимые значения.

Логические поля принимают и возвращают true или false. Значения Y, N, 1 и 0 не подходят: метод вернет ошибку «В поле opened требуется тип данных bool для такого запроса».

Поля типа date принимают и возвращают дату в формате YYYY-MM-DD, например 2026-11-03. Дату со временем или в формате 03.11.2026 такое поле не принимает. Поля типа datetime возвращаются в формате ISO 8601, например 2026-11-03T14:47:23+03:00. В фильтре по полю datetime тоже передавайте дату со временем: значение 2026-11-03 метод не примет.

Фильтровать и сортировать можно только по полям, у которых это указано в описании. На другие поля метод list вернет ошибку «требуется наличие атрибута Filterable» или «Sortable». Через точку можно фильтровать по полям связанных элементов CRM и объектов lastCommunication и utm, например ["company.title", "=", "Ромашка"] или ["utm.source", "=", "google"]. По полям сотрудников, стадии, воронки, типа сделки и источника, например assignedBy.id или stage.semanticId, фильтр не работает: метод вернет ошибку BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION. Формат фильтра описан на странице crm.<тип>.list и в статье Обзор REST API 3.0.

Объект сделки

Название
тип

Описание

title
string

Название сделки, до 255 символов.

Можно изменять, фильтровать и сортировать

typeId
string | null

Идентификатор типа сделки, например SALE. Типы сделок возвращает метод crm.dictionary.dealtype.list.

Можно изменять, фильтровать и сортировать

type
object | null

Тип сделки. Объект типа тип сделки.

Только чтение. Запрашивается в select

quoteId
integer | null

Идентификатор предложения, из которого создана сделка.

Только чтение. Можно фильтровать и сортировать

quote
object | null

Предложение, из которого создана сделка. Объект типа элемент CRM.

Только чтение. Запрашивается в select

leadId
integer | null

Идентификатор лида, из которого создана сделка.

Только чтение. Можно фильтровать и сортировать

lead
object | null

Лид, из которого создана сделка. Объект типа элемент CRM.

Только чтение. Запрашивается в select

previousStageId
string

Идентификатор стадии, на которой сделка была до текущей, например EXECUTING. Если стадия не менялась — пустая строка.

Только чтение. Можно фильтровать и сортировать

previousStage
object | null

Предыдущая стадия. Объект типа стадия. Если стадия не менялась — null.

Только чтение. Запрашивается в select

locationId
integer | null

Идентификатор местоположения клиента. Служебное поле. Метод проверяет, что местоположение существует.

Можно изменять. Фильтровать и сортировать нельзя

isNew
boolean

Сделка на первой стадии воронки: true — да, false — нет.

Только чтение. Можно фильтровать и сортировать

isRepeatedApproach
boolean

Сделка — повторное обращение клиента: true — да, false — нет.

Только чтение. Можно фильтровать и сортировать

isReturnCustomer
boolean

Повторная сделка с клиентом: true — да, false — нет.

Только чтение. Можно фильтровать и сортировать

id
integer

Идентификатор сделки. Назначается при создании.

Только чтение. Можно фильтровать и сортировать

createdTime
datetime

Дата и время создания сделки.

Только чтение. Можно фильтровать и сортировать

createdById
integer

Идентификатор пользователя, который создал сделку.

Только чтение. Можно фильтровать и сортировать

createdBy
object

Пользователь, который создал сделку. Объект типа сотрудник.

Только чтение. Запрашивается в select

updatedTime
datetime

Дата и время последнего изменения сделки.

Только чтение. Можно фильтровать и сортировать

updatedById
integer

Идентификатор пользователя, который последним изменил сделку.

Только чтение. Можно фильтровать и сортировать

updatedBy
object

Пользователь, который последним изменил сделку. Объект типа сотрудник.

Только чтение. Запрашивается в select

lastActivityTime
datetime

Дата и время последней активности в таймлайне сделки.

Только чтение. Можно фильтровать и сортировать

lastActivityById
integer

Идентификатор автора последней активности в таймлайне.

Только чтение. Можно фильтровать и сортировать

lastActivityBy
object

Автор последней активности в таймлайне. Объект типа сотрудник.

Только чтение. Запрашивается в select

assignedById
integer

Идентификатор ответственного за сделку. Идентификаторы пользователей возвращает метод user.get. Если пользователя нет, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

Можно изменять, фильтровать и сортировать

assignedBy
object

Ответственный. Объект типа сотрудник.

Только чтение. Запрашивается в select

opened
boolean

Доступна ли сделка всем пользователям: true — да, false — нет.

Можно изменять, фильтровать и сортировать

comments
string | null

Комментарий к сделке. Поддерживает BB-коды, например [b]текст[/b].

Можно изменять. Фильтровать и сортировать нельзя

originatorId
string | null

Идентификатор внешней системы, из которой пришла сделка. Используйте вместе с originId для связи с внешним источником.

Можно изменять, фильтровать и сортировать

originId
string | null

Идентификатор сделки во внешней системе.

Можно изменять, фильтровать и сортировать

webformId
integer | null

Идентификатор CRM-формы, через которую создана сделка. Если сделка создана не формой — null. Список форм возвращает метод crm.form.list.

Только чтение. Можно фильтровать и сортировать

webform
object | null

CRM-форма, через которую создана сделка. Объект типа CRM-форма.

Только чтение. Запрашивается в select

lastCommunication
object

Даты последних коммуникаций с клиентом по сделке. Объект типа последняя коммуникация.

Только чтение. Запрашивается в select. Можно фильтровать по полям объекта через точку, например ["lastCommunication.callTime", ">=", "2026-11-01T00:00:00+03:00"]

entityTypeId
integer

Идентификатор типа объекта. Для сделки — 2.

Только чтение

canRead
boolean

Может ли текущий пользователь просматривать сделку: true — да, false — нет.

Только чтение

url
string

Относительная ссылка на карточку сделки, например /crm/deal/details/8983/?category_id=9.

Только чтение

stageId
string

Идентификатор стадии. В общей воронке — без префикса, например NEW, в других воронках — с префиксом воронки, например C9:NEW. Стадия должна относиться к воронке сделки. Стадии воронки возвращает метод crm.deal.category.stage.list.

Можно изменять, фильтровать и сортировать

stage
object

Стадия сделки. Объект типа стадия.

Только чтение. Запрашивается в select

movedTime
datetime

Дата и время последней смены стадии.

Только чтение. Можно фильтровать и сортировать

movedById
integer

Идентификатор пользователя, который последним сменил стадию.

Только чтение. Можно фильтровать и сортировать

movedBy
object

Пользователь, который последним сменил стадию. Объект типа сотрудник.

Только чтение. Запрашивается в select

closed
boolean

Закрыта ли сделка: true — да, false — нет.

Только чтение. Можно фильтровать и сортировать

stageSemanticId
string

Группа стадии. Возможные значения:

  • P — в работе
  • S — успех
  • F — провал

Только чтение. Можно фильтровать и сортировать

stageSemantic
object

Группа стадии с названием. Объект типа группа стадии.

Только чтение. Запрашивается в select

beginTime
date

Дата начала.

Можно изменять, фильтровать и сортировать

closeTime
date

Дата завершения.

Можно изменять, фильтровать и сортировать

categoryId
integer

Идентификатор воронки. Общая воронка — 0. Если не передать при создании, сделка попадет в общую воронку. Воронки сделок возвращает метод crm.deal.category.list.

Можно изменять, фильтровать и сортировать

category
object

Воронка сделки. Объект типа воронка.

Только чтение. Запрашивается в select

observersId
integer[]

Идентификаторы наблюдателей. Идентификаторы пользователей возвращает метод user.get.

Можно изменять и фильтровать, сортировать нельзя. В фильтре ["observersId", "=", 1] находит сделки, у которых среди наблюдателей есть пользователь 1

observers
object[]

Наблюдатели. Массив объектов типа сотрудник. Если наблюдателей нет — пустой массив.

Только чтение. Запрашивается в select

contactId
integer | null

Идентификатор основного контакта — первого в списке contactsId. Назначить основной контакт можно методом crm.deal.setprimarycontact.

Только чтение. Можно фильтровать, сортировать нельзя

contact
object | null

Основной контакт. Объект типа элемент CRM.

Только чтение. Запрашивается в select

contactsId
integer[]

Идентификаторы контактов сделки. Контакты возвращает метод crm.contact.list. Переданный массив заменяет текущий список контактов.

Можно изменять и фильтровать, сортировать нельзя

contacts
object[]

Контакты сделки. Массив объектов типа элемент CRM. Если контактов нет — пустой массив.

Только чтение. Запрашивается в select

companyId
integer | null

Идентификатор компании. Компании возвращает метод crm.company.list.

Можно изменять, фильтровать и сортировать

company
object | null

Компания. Объект типа элемент CRM.

Только чтение. Запрашивается в select

myCompanyId
integer | null

Идентификатор вашей компании, от имени которой вы работаете с клиентом. Список ваших компаний возвращает метод crm.mycompany.list.

Можно изменять, фильтровать и сортировать

myCompany
object | null

Ваша компания. Объект типа элемент CRM.

Только чтение. Запрашивается в select

sourceId
string | null

Идентификатор источника, например CALL. Источники возвращает метод crm.dictionary.source.list.

Можно изменять, фильтровать и сортировать

source
object | null

Источник. Объект типа значение справочника.

Только чтение. Запрашивается в select

sourceDescription
string | null

Дополнительная информация об источнике.

Можно изменять и фильтровать, сортировать нельзя

opportunity
double

Сумма сделки, не меньше 0. Способ расчета суммы задает поле isManualOpportunity.

Можно изменять, фильтровать и сортировать

taxValue
double

Сумма налога. Рассчитывается по товарным позициям.

Только чтение. Можно фильтровать и сортировать

isManualOpportunity
boolean

Режим расчета суммы: true — сумма задается вручную, false — рассчитывается по товарным позициям.

Можно изменять, фильтровать и сортировать

currencyId
string

Идентификатор валюты, например RUB. Валюты возвращает метод crm.currency.list.

Можно изменять, фильтровать и сортировать

currency
object

Валюта. Объект типа валюта.

Только чтение. Запрашивается в select

utm
object | null

UTM-метки сделки. Объект типа UTM-метки. Если меток нет — null.

Можно изменять: передайте объект с нужными метками, например {"source": "google", "medium": "cpc"}. Можно фильтровать по полям объекта через точку, например ["utm.source", "=", "google"], сортировать нельзя

trackingSourceId
integer | null

Идентификатор источника сквозной аналитики.

Можно изменять и фильтровать, сортировать нельзя

related<Код типа>Id
integer | null

Идентификатор родительского элемента другого типа объекта, например relatedSmartProcess177Id. Подробнее — в разделе Поля связей с другими типами.

Можно изменять и фильтровать, сортировать нельзя

related<Код типа>
object | null

Родительский элемент другого типа объекта, например relatedSmartProcess177. Объект типа элемент CRM.

Только чтение. Запрашивается в select

Поля related<Код типа>Id и related<Код типа> появляются, когда в Битрикс24 настроена связь, в которой сделка подчинена другому типу объекта, например смарт-процессу. Для каждого родительского типа у сделки есть пара полей:

  • related<Код типа>Id — идентификатор родительского элемента, например relatedSmartProcess177Id для смарт-процесса с entityTypeId = 177
  • related<Код типа> — родительский элемент как объект типа элемент CRM, например relatedSmartProcess177

Название поля в ответе crm.deal.field.list совпадает с названием родительского типа, например «Закупка оборудования». Метод проверяет, что элемент с переданным идентификатором существует. Если элемента нет, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

Состав этих полей зависит от связей, настроенных в Битрикс24. Актуальный список возвращает метод crm.deal.field.list.

Связанные объекты

Связанный объект запрашивается в select по имени поля без суффикса Id: assignedBy, stage, category. Имя объекта целиком возвращает все его поля, путь через точку — только выбранные, например ["stage.name", "assignedBy.firstName"]. Путь поддерживает один уровень вложенности.

Связанный элемент CRM — contact, company, myCompany, lead, quote, related<Код типа> — по имени целиком возвращает только id. Остальные поля элемента запрашивайте через точку, например ["company.title", "company.url"].

Если связь не заполнена, объект приходит как null, а массив объектов, например observers или contacts, — как пустой массив.

Объект сотрудника

Поля createdBy, updatedBy, lastActivityBy, assignedBy, movedBy, observers.

Название
тип

Описание

id
integer

Идентификатор пользователя

firstName
string

Имя

lastName
string

Фамилия

personalGender
string | null

Пол: M — мужской, F — женский. Если пол не указан — null

url
string

Относительная ссылка на профиль пользователя, например /company/personal/user/1/

personalPhoto
string | null

Ссылка на фотографию пользователя. Если фотографии нет — null

Объект элемента CRM

Поля contact, contacts, company, myCompany, lead, quote, related<Код типа>.

Название
тип

Описание

id
integer

Идентификатор элемента

entityTypeId
integer

Идентификатор типа объекта, например 3 — контакт, 4 — компания

canRead
boolean

Может ли текущий пользователь просматривать элемент

title
string

Название элемента. У контакта — фамилия, имя и отчество

url
string

Относительная ссылка на карточку элемента, например /crm/company/details/3/

Объект стадии

Поля stage и previousStage.

Название
тип

Описание

id
string

Идентификатор стадии, например C9:NEW

name
string

Название стадии

sort
integer

Порядок стадии в воронке

color
string

Цвет стадии в формате #RRGGBB

semanticId
string

Группа стадии: P — в работе, S — успех, F — провал

Объект группы стадии

Поле stageSemantic. Справочник групп возвращает метод crm.dictionary.stagesemantic.list.

Название
тип

Описание

id
string

Идентификатор группы: P, S или F

name
string

Название группы, например Группа стадий "Сделка в работе"

Объект воронки

Поле category.

Название
тип

Описание

id
integer

Идентификатор воронки

name
string

Название воронки

sort
integer

Порядок сортировки воронки

isDefault
boolean

Воронка по умолчанию: true — да, false — нет

Объект типа сделки

Поле type.

Название
тип

Описание

id
string

Идентификатор типа, например SALE

name
string

Название типа, например Продажа

sort
integer

Порядок сортировки

isSystem
boolean

Системный тип: true — да, false — нет

Объект значения справочника

Поле source.

Название
тип

Описание

id
string

Идентификатор значения, например CALL

name
string

Название значения, например Звонок

sort
integer

Порядок сортировки

Объект CRM-формы

Поле webform.

Название
тип

Описание

id
integer

Идентификатор CRM-формы

name
string

Название CRM-формы

Объект последней коммуникации

Поле lastCommunication. Если коммуникации такого вида не было, поле равно null.

Название
тип

Описание

communicationTime
datetime | null

Дата и время последней коммуникации любого вида

callTime
datetime | null

Дата и время последнего звонка

emailTime
datetime | null

Дата и время последнего письма

imolTime
datetime | null

Дата и время последнего сообщения в открытой линии

webformTime
datetime | null

Дата и время последнего заполнения CRM-формы

Объект валюты

Поле currency.

Название
тип

Описание

id
string

Код валюты, например RUB

fullName
string

Название валюты

formatString
string

Шаблон вывода суммы. Символ # заменяется суммой. Знак валюты приходит HTML-сущностью, например # &#8381;

decPoint
string

Десятичный разделитель

thousandsSep
string

Разделитель разрядов. Может приходить HTML-сущностью, например &nbsp;

decimals
integer

Количество знаков после запятой

hideZero
boolean

Скрывать ли незначащие нули в дробной части

amount
double

Курс валюты относительно базовой

amountCount
integer

Количество единиц валюты, к которому относится курс

base
boolean

Базовая валюта: true — да, false — нет

sort
integer

Порядок сортировки

numericCode
string

Цифровой код валюты, например 643

languageId
string

Язык, для которого заданы название и формат

createdTime
datetime | null

Дата и время создания валюты

updatedTime
datetime | null

Дата и время изменения валюты

createdById
integer | null

Идентификатор пользователя, который создал валюту

updatedById
integer | null

Идентификатор пользователя, который изменил валюту

Объект UTM-меток

Поле utm. Каждая метка — строка до 255 символов. Метки, которые не переданы, приходят как null.

Название
тип

Описание

source
string | null

Рекламная система, метка utm_source, например google

medium
string | null

Тип трафика, метка utm_medium, например cpc

campaign
string | null

Рекламная кампания, метка utm_campaign

content
string | null

Содержание объявления, метка utm_content

term
string | null

Ключевая фраза, метка utm_term

Пользовательские поля

Пользовательские поля сделки называются UF_CRM_<код>, например UF_CRM_1687529546. Их передают и запрашивают по имени так же, как стандартные поля. Список пользовательских полей возвращает метод crm.deal.field.custom.list.

У каждого пользовательского поля есть парное поле UF_CRM_…_data — только для чтения, запрашивается в select. Оно содержит значение в нескольких представлениях:

  • value — значение в том же формате, что в самом поле
  • rawValue — значение в формате хранения, например 100.5|RUB для поля «Деньги»
  • formattedValue — значение для показа пользователю: 100.50 ₽ для денег, имя сотрудника для поля «Привязка к сотруднику», текст варианта для списка
  • extra — дополнительные данные: для денег — amount, currencyId и currencyFullName, для сотрудника — поля объекта сотрудника. Для строки, даты и списка — null

У множественного пользовательского поля UF_CRM_…_data — массив таких объектов.

Продолжите изучение

Предыдущая
Получить список моих компаний с реквизитами и контактами
Следующая
Поля лида