Поля счета в REST 3.0

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

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

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

Поля счета возвращают методы crm.smartinvoice.get и crm.smartinvoice.list, а принимают методы crm.smartinvoice.add и crm.smartinvoice.update. Значения множественных полей по одному добавляют и удаляют методы crm.smartinvoice.addfieldvalue и crm.smartinvoice.deletefieldvalue. Список полей с признаками возвращает метод crm.smartinvoice.field.list.

Методы crm.smartinvoice.* работают со счетами нового типа, у которых entityTypeId = 31. Товары счета хранятся отдельно от полей, их возвращает метод crm.smartinvoice.productrow.list.

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

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

Метод

Принимает

Возвращает

crm.smartinvoice.add

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

Идентификатор созданного счета id

crm.smartinvoice.update

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

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

crm.smartinvoice.get

id счета и select

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

crm.smartinvoice.list

select, filter, order, pagination

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

crm.smartinvoice.addfieldvalue, crm.smartinvoice.deletefieldvalue

id счета, имя множественного поля fieldName и значение value. Подходят поля contactsId, observersId и множественные пользовательские поля. Для других полей метод вернет ошибку «The field is not supported.»

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

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

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

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

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

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

Поля closed, stageSemanticId и stageSemantic есть в ответе crm.smartinvoice.field.list, но методы get и list их не принимают. На такое поле в select, filter или order метод вернет ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION. Группу стадии можно получить из поля semanticId объекта стадии: "select": ["stage.semanticId"].

Объект счета

Название
тип

Описание

id
integer

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

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

title
string

Название счета, до 255 символов. Если не передать название при создании, Битрикс24 подставит слово «Счет» и идентификатор, например Счет #141. Пустую строку crm.smartinvoice.update не записывает: название не меняется.

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

accountNumber
string

Номер счета, например ТД-001. Если не передать номер при создании, Битрикс24 назначит его по настройкам нумерации счетов.

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

xmlId
string | null

Внешний код счета, до 255 символов. Используйте для связи счета с записью во внешней системе.

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

stageId
string

Идентификатор стадии, например DT31_5:N. Если не передать стадию при создании, счет попадет на первую стадию. Отдельного метода стадий счета в REST 3.0 нет. Стадии возвращает метод crm.status.list с фильтром {"ENTITY_ID": "SMART_INVOICE_STAGE_5"}, где 5 — номер воронки из stageId. Допустимые стадии перечислены и в тексте ошибки, если передать неверное значение.

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

stage
object

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

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

movedTime
datetime

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

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

movedById
integer

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

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

movedBy
object

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

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

closed
boolean

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

Только чтение. Поле есть в ответе field.list, но методы get и list его не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

stageSemanticId
string

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

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

Только чтение. Поле есть в ответе field.list, но методы get и list его не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION. Группу стадии возвращает поле stage.semanticId

stageSemantic
object

Группа стадии с названием: id и name. Справочник групп возвращает метод crm.dictionary.stagesemantic.list.

Только чтение. Поле есть в ответе field.list, но методы get и list его не принимают и возвращают ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

beginTime
date

Дата выставления счета. Если не передать при создании, Битрикс24 подставит дату создания счета.

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

closeTime
date

Срок оплаты. Если не передать при создании, Битрикс24 подставит дату через семь дней после создания счета.

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

opportunity
double

Сумма счета, не меньше 0. На отрицательное значение метод вернет ошибку «Значение поля должно быть не меньше, чем 0». Способ расчета суммы задает поле isManualOpportunity.

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

isManualOpportunity
boolean

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

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

taxValue
double

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

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

currencyId
string

Идентификатор валюты, например RUB. Если не передать при создании, Битрикс24 подставит базовую валюту. Валюты возвращает метод crm.currency.list.

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

currency
object

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

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

companyId
integer | null

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

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

company
object | null

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

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

contactsId
integer[]

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

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

contacts
object[]

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

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

contactId
integer | null

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

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

contact
object | null

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

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

myCompanyId
integer | null

Идентификатор вашей компании, от имени которой выставлен счет. Если не передать при создании, Битрикс24 подставит вашу компанию по умолчанию. Список ваших компаний возвращает метод crm.mycompany.list. Идентификатор компании клиента метод не примет и вернет ошибку «Значение поля не содержится в списке допустимых значений». Реквизиты вашей компании в счете задает метод crm.smartinvoice.mycompanyrequisite.set.

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

myCompany
object | null

Ваша компания. Объект типа элемент CRM. Ее поля описаны в статье Поля моей компании в REST 3.0.

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

relatedDealId
integer | null

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

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

relatedDeal
object | null

Сделка, к которой относится счет. Объект типа элемент CRM.

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

relatedQuoteId
integer | null

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

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

relatedQuote
object | null

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

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

locationId
integer | null

Идентификатор местоположения. Если местоположение не задано — 0. Если местоположения нет в Битрикс24, метод вернет ошибку «Значение поля не содержится в списке допустимых значений».

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

sourceId
string | null

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

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

source
object | null

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

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

sourceDescription
string | null

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

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

assignedById
integer

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

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

assignedBy
object

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

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

observersId
integer[]

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

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

observers
object[]

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

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

opened
boolean

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

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

comments
string | null

Комментарий к счету.

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

createdTime
datetime

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

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

createdById
integer

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

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

createdBy
object

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

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

updatedTime
datetime

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

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

updatedById
integer

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

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

updatedBy
object

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

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

lastActivityTime
datetime

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

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

lastActivityById
integer

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

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

lastActivityBy
object

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

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

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

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

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

canRead
boolean

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

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

url
string

Относительная ссылка на карточку счета, например /crm/type/31/details/139/?categoryId=5.

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

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

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

Связанный элемент CRM — contact, contacts, company, myCompany, relatedDeal, relatedQuote — по имени целиком возвращает только id. Остальные поля элемента запрашивайте через точку. Через точку доступны поля из объекта элемента CRM и любые поля типа связанного элемента, например ["company.title", "company.phone", "myCompany.title"].

Если связь не заполнена, объект приходит как 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, relatedDeal, relatedQuote.

Название
тип

Описание

id
integer

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

entityTypeId
integer

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

canRead
boolean

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

title
string

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

url
string

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

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

Поле stage.

Название
тип

Описание

id
string

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

name
string

Название стадии, например Оплачен

sort
integer

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

color
string

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

semanticId
string

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

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

Поле source.

Название
тип

Описание

id
string

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

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

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

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

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

Значение поля типа «Деньги» передается объектом {"sum": 150.5, "currencyId": "RUB"}. Строка вида 150.5|RUB не подходит: метод вернет ошибку «В поле UF_CRM_… требуется тип данных MoneyDto для такого запроса».

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

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

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

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

Предыдущая
Поля предложения
Следующая
Поля смарт-процесса