Блог Горошко Андрея Bitrix24,PHP Типы данных и структура объектов в REST API CRM

Типы данных и структура объектов в REST API CRM

goroshckogoroshcko| Нет комментария|
Рубрики:

Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Типы данных и структура объектов в REST API CRM», проанализируем лучшие практики и покажем, как правильно использовать битрикс в реальных задачах.

Типы данных и структура объектов в REST API CRM

  • Сделать ссылки с catalog_product.id и catalog_measure.code на справочник, когда появится

Базовые типы данных перечислены в отдельной статье.

В этой статье рассмотрим типы данных и структуру объектов, характерные именно для crm.

Типы данных

ТипОписания и значения
crm_statusСтроковый идентификатор элемента справочника CRM (например, NEW). Получить возможные значения конкретного справочника можно с помощью метода crm.status.list с фильтром по ENTITY_ID.
crm_leadЦелочисленный идентификатор лида CRM. Получить информацию о лиде можно с помощью метода crm.lead.get.
crm_dealЦелочисленный идентификатор сделки CRM. Получить информацию о сделке можно с помощью метода crm.deal.get.
crm_contactЦелочисленный идентификатор контакта CRM. Получить информацию о контакте можно с помощью метода crm.contact.get.
crm_companyЦелочисленный идентификатор компании CRM. Получить информацию о компании можно с помощью метода crm.company.get.
crm_quoteЦелочисленный идентификатор коммерческого предложения CRM. Получить информацию о коммерческом предложении можно с помощью метода crm.quote.get.
crm_categoryЦелочисленный идентификатор воронки (направления) CRM. Получить информацию о воронке (направлении) можно с помощью метода crm.category.get
crm_entityЦелочисленный идентификатор элемента некоторого объекта CRM. Поля с таким типом явно содержат в себе информацию к какому объекту CRM они принадлежат. Например, поля вида parentId{entityTypeId}, содержат внутри своего названия идентификатор типа сущности CRM. Получить информацию об элементе можно с помощью метода crm.item.get передав entityTypeId из названия поля и id из его значения
lang_mapОбъект формата:

{
    lang_1: value_1,
    lang_2: value_2,
    ..
    lang_n: value_n,
}

где
lang_n — Идентификатор языка
value_n — Значение для языка lang_n

crm_item_product_rowЦелочисленный идентификатор товарной позиции объекта CRM. Получить идентификаторы товарных позиций можно с помощью метода crm.item.productrow.list
crm_multifieldОбъект, описывающий «множественное поле». Множественные поля применяются для хранения телефонов, email-адресов и другой контактной информации. В лидах, контактах и компаниях полями этого типа являются PHONE, EMAIL, WEB и IM.
crm_currencyОбъект, описывающий валюту
crm_currency_localizationОбъект, описывающий локализацию валюты
crm_orderentityОбъект, описывающий связь CRM с заказами интернет-магазина
typeОбъект, описывающий пользовательский тип объекта CRM (смарт-процесс)
type.relationsОбъект, содержащий в себе связи к другим сущностям CRM
relationОбъект, описывающий привязанный элемент CRM
type.linkedUserFieldsОбъект, описывающий набор полей, в которых должен отображаться смарт-процесс

Структура объектов

crm_multifield {#crm_multifield}

Значение
тип		Описание
ID
integer		Идентификатор значения множественного поля
TYPE_ID
string		Тип множественного поля. Может принимать значения PHONE, EMAIL, WEB, IM, LINK
VALUE
string		Строковое значение множественного поля
VALUE_TYPE
string		Тип значения множественного поля.
Может принимать значения WORK, MOBILE, FAX, HOME, PAGER, MAILING, OTHER для телефона,
WORK, HOME, MAILING, OTHER для почты,
WORK, HOME, fb, VK, LIVEJOURNAL, TWITTER, OTHER для сайта,
fb, TELEGRAM, VK, SKYPE, VIBER, inst, BITRIX24, OPENLINE, IMOL, ICQ, MSN, JABBER, OTHER для мессенджера

crm_item_product_row

Значение
тип		Описание
id
integer		Идентификатор товарной позиции
ownerId
integer		Идентификатор объекта CRM
ownerType
string		Идентификатор типа объекта CRM
productId
catalog_product.id		Идентификатор товара из каталога
productName
string		Название товара в товарной позиции
price
double		Цена за единицу товарной позиции с учетом скидок и налогов
priceAccount
double		Стоимость за единицу товарной позиции с учетом скидок и налогов, сконвертированная в валюту отчетов
priceExclusive
double		Стоимость за единицу товарной позиции с учетом скидок, но без учета налогов
priceNetto
double		Стоимость за единицу товарной позиции без учета скидок и без учета налогов
priceBrutto
double		Стоимость за единицу товарной позиции с учетом налогов, но без учета скидок
quantity
double		Количество товара
discountTypeId
integer		Тип скидки
Возможные значения:
— 1 — абсолютное значение
— 2 — процентное значение
discountRate
double		Значение скидки в процентах
discountSum
double		Абсолютное значение скидки
taxRate
double		Ставка налога в процентах
taxIncluded
string		Индикатор того, включен ли налог в стоимость
Возможные значения:
— Y – налог включен
— N – налог не включен
customized
string		Устаревшее
measureCode
catalog_measure.code		Код единицы измерения
measureName
string		Текстовое представление единицы измерения (например — шт, кг, м, л и т.д.)
sort
integer		Сортировка
xmlId
string		Внешний идентификатор товарной позиции
type
integer		Тип товара
Возможные значения:
— 1 — Простой товар
— 2 — Комплект
— 3 — Товар с торговыми предложениями
— 4 — Торговое предложение
— 5 — Торговое предложение, у которого нет товара (не указан или удален)
— 6 — Специфический тип, означает невалидный товар с торговыми предложениями
— 7 — Услуга
storeId
integer		Идентификатор склада

crm_currency

Значение
тип		Описание
AMOUNT
double		Курс обмена по отношению к базовой валюте
Для базовой валюты всегда равен 1. Точность — 4 знака после запятой
AMOUNT_CNT
integer		Номинал.
Для базовой валюты всегда равен 1
BASE
string		Признак, является ли валюта базовой (Y/N)
CURRENCY
string		Идентификатор валюты. Соответствует стандарту ISO 4217
DATE_UPDATE
datetime		Дата последнего изменения
SORT
integer		Сортировка
LID
string		Код языка, для которого возвращаются параметры локализации
DECIMALS
integer		Число десятичных знаков дробной части (параметр локализации)
DEC_POINT
string		Десятичная точка при выводе (параметр локализации)
FORMAT_STRING
string		Шаблон формата (параметр локализации)
FULL_NAME
string		Название валюты (параметр локализации)
THOUSANDS_SEP
string		Разделитель триад (параметр локализации)
LANG
object		Локализации валюты.
Объект со списком доступных локализаций в формате {"lang_1": "value_1", ... "lang_N": "value_N"}, где lang_N — идентификатор языка, а value — объект типа crm_currency_localization.
Идентификатор языка — строка из двух латинских букв. Возможные значения смотрите в таблице идентификаторов языков

crm_currency_localization

Значение
тип		Описание
DECIMALS
integer		Число десятичных знаков дробной части.

Значение по умолчанию — 2

DEC_POINT
string		Десятичная точка при выводе.

Значение по умолчанию — . (символ точки)

FORMAT_STRING
string		Шаблон формата. Должен содержать символ # — вместо него будет подставлено значение цены.

Значение по умолчанию — #.

Примеры шаблонов для суммы 1000:
— $ # — $ 1000
— # руб. — 1000 руб.
— € # — € 1000

FULL_NAME
string		Название валюты.

Значение по умолчанию — crm_currency.CURRENCY

HIDE_ZERO
string		Признак, скрывать незначащие нули или нет (Y/N).

Значение по умолчанию — N

THOUSANDS_SEP
string		Разделитель триад.

Значение по умолчанию — (пробел)

THOUSANDS_VARIANT
string		Код разделителя триад.

Значение по умолчанию — S.

При создании или изменении локализации, если указано значение для поля THOUSANDS_VARIANT, то значение в THOUSANDS_SEP будет проигнорировано и заменено согласно списку:
— N — пусто, разделитель триад отсутствует. Пример: 12345678
— C — запятая. Пример: 12,345,678
— D — точка. Пример: 12.345.678
— S — пробел. Пример: 12 345 678
— B — неразрывный пробел. Пример: 12 345 678
От предыдущего варианта отличается тем, что при переносе строк результат не разбивается на части

Если разделитель триад не нужен, необходимо явно передавать поле THOUSANDS_VARIANT со значением N. Пустая строка в поле THOUSANDS_SEP не допускается.

crm_orderentity

Значение
тип		Описание
OWNER_ID
integer		Идентификатор объекта CRM
OWNER_TYPE_ID
integer		Идентификатор типа объекта CRM
ORDER_ID
sale_order.id		Идентификатор заказа

type

Значение
тип		Описание
id
integer		Идентификатор смарт-процесса
title
string		Название смарт-процесса
code
string		Символьный код
createdBy
integer		Идентификатор пользователя, который создал данный смарт-процесс
entityTypeId
integer		Идентификатор типа сущности
isCategoriesEnabled
boolean		Включены ли свои воронки и туннели продаж
isStagesEnabled
boolean		Включено ли использование своих стадий и канбана
isBeginCloseDatesEnabled
boolean		Включены ли поля Дата начала и Дата завершения
isClientEnabled
boolean		Включено ли поле Клиент
isUseInUserfieldEnabled
boolean		Включено ли использование смарт-процесса в пользовательском поле
isLinkWithProductsEnabled
boolean		Включена ли привязка товаров каталога
isMycompanyEnabled
boolean		Включено ли поле Реквизиты вашей компании
isDocumentsEnabled
boolean		Включена ли печать документов
isSourceEnabled
boolean		Включены ли поля Источник и Дополнительно об источнике
isObserversEnabled
boolean		Включено ли поле Наблюдатели
isRecyclebinEnabled
boolean		Включено ли использование корзины
isAutomationEnabled
boolean		Включены ли роботы и триггеры
isBizProcEnabled
boolean		Включено ли использование дизайнера бизнес процессов
isSetOpenPermissions
boolean		Делать ли новые воронки доступными для всех
isPaymentsEnabled
boolean		Системное поле, которое показывает, включена ли возможность оплаты
isCountersEnabled
boolean		Системное поле, которое показывает, включена ли счётчики
createdTime
datetime		Системное поле, указывающее время создания смарт-процесса
updatedTime
datetime		Системное поле, указывающее на время изменения данного смарт-процесса
updatedBy
integer		Идентификатор пользователя, изменившего данный смарт-процесс
relations
object		Объект, содержащий в себе связи к другим сущностям CRM
linkedUserFields
object		Набор полей в которых должен отображаться данный смарт-процесс
customSections
array		Список всех цифровых рабочих мест

Параметр устарел. Для работы с цифровыми рабочими местами используйте методы crm.automatedsolution.*

customSectionId
integer		Идентификатор цифрового рабочего места

Параметр устарел. Для работы с цифровыми рабочими местами используйте методы crm.automatedsolution.*

type.relations

Значение
тип		Описание
parent
relation[]		Элементы CRM, которые будут привязаны к данному смарт-процессу
child
relation[]		Элементы CRM, к котором будет привязан данный смарт-процесс

relation

Значение
тип		Описание
entityTypeId
integer		Идентификатор системного или пользовательского типа сущности CRM
isChildrenListEnabled
boolean		Добавлять ли связанный элемент в карточку
isPredefined
boolean		Является ли данная связь предустановленной (системной)

type.linkedUserFields

Значение
тип		Описание
CALENDAR_EVENT\UF_CRM_CAL_EVENT
boolean		Событие в календаре
TASKS_TASK\UF_CRM_TASK
boolean		Задачи
TASKS_TASK_TEMPLATE\UF_CRM_TASK
boolean		Шаблоны задач

Идентификаторы языков для Битрикс24 {#lang-ids}

Идентификатор языкаЯзык
arАрабский
brПортугальский (Бразилия)
deНемецкий
enАнглийский
frФранцузский
hiХинди
idИндонезийский
itИтальянский
jaЯпонский
laИспанский
msМалайский
plПольский
ruРусский
scКитайский
tcКитайский (Тайвань)
thТайский
trТурецкий
uaУкраинский
vnВьетнамский

Объекты, используемые в ответах

Описание отдельно взятого поля crm_rest_field_description {#crm_rest_field_description}

Название
тип		Описание
type
string		Тип поля
isRequired
boolean		Является ли поле обязательным
isReadOnly
boolean		Является ли поле неизменяемым
isImmutable
boolean		Признак возможности однократного заполнения значения поля только при создании нового элемента
isMultiple
boolean		Признак множественности поля. При true значения в поле передаются в виде массива
isDynamic
boolean		Является ли поле пользовательским
title
string		Название поля

Описание пользовательского поля типа адресс {#crm_user_field_address}

Пользовательское поле типа «Адрес» хранит данные одной строкой. В таблице приведено описание составных частей этой строки.
Подробное описание составляющих частей адреса можно найти в статье Об адресах.

Название
тип		ОписаниеПример
ADDRESS_1
string		Улица, номер домаМалый Знаменский переулок 7/10 с2
ADDRESS_2
string		Квартира, офис, комната, этаж5
POSTAL_CODE
string		Почтовый индекс119019
CITY
string		Населенный пунктМосква
REGION
string		Районрайон Арбат
PROVINCE
string		РегионМосква
COUNTRY
string		СтранаРоссия
LATITUDE
string		Координаты широты55.748289
LONGITUDE
string		Координаты долготы37.60504
LOC_ADDR_ID
string		Идентификатор адреса местоположения10

Тип объекта CRM {#object_type}

Тип объектаЧисловой идентификатор типа
entityTypeId		Символьный код типа
entityTypeName		Краткий символьный код типа
entityTypeAbbr		Тип объекта пользовательского поля
userFieldEntityId
Лид1LEADLCRM_LEAD
Сделка2DEALDCRM_DEAL
Контакт3CONTACTCCRM_CONTACT
Компания4COMPANYCOCRM_COMPANY
Счет (старый)5INVOICEICRM_INVOICE
Счет (новый)31SMART_INVOICESICRM_SMART_INVOICE
Предложение7QUOTEQCRM_QUOTE
Реквизит8REQUISITERQCRM_REQUISITE
Заказ14ORDEROORDER
Смарт-процесс128DYNAMIC_128T80CRM_1

> В таблице приведено описание смарт-процесса с идентификатором типа 128 и идентификатором 1.
>
> Идентификаторы типа смарт-процессов находятся в промежутке от 128 до 191 (включительно), либо имеют значение больше чем 1030 (включительно) и являются четными.
>
> Идентификаторы типа смарт-процессов, удаленных в корзину, находятся в промежутке от 192 до 255 (включительно), либо имеют значение больше чем 1030 и являются нечетными.
>
> Чтобы определить префикс смарт-процесса, необходимо:
> — сконвертировать идентификатор из десятичной системы в шестнадцатеричную. В случае с идентификатором равным 128, получаем значение 80.
> — взять полученное значение в нижнем регистре и к полученному значению дописать латинскую букву T в начале. Таким образом, получаем префикс — T80.

💡 Экспертное мнение и рекомендации

Ключевые выводы по теме «Типы данных и структура объектов в REST API CRM»:

Использование современных стандартов D7 при работе с битрикс позволяет писать чистый, масштабируемый и безопасный код. Не забывайте обрабатывать исключения (try/catch) и проверять права доступа текущего пользователя перед выполнением критических операций.

Похожая задача в бизнесе?

Помогу автоматизировать процессы и внедрить ИИ

Меня зовут Андрей Горошко. Я Full-stack разработчик и эксперт по 1С-Битрикс. Настраиваю CRM Битрикс24, разрабатываю защищенные API и создаю умных ИИ-агентов для автоматизации рутины.

Related Post

Создать новую стадию rpa.stage.addСоздать новую стадию rpa.stage.add

25.05.202625.05.2026| goroshckogoroshcko| Нет комментария|

Эффективная интеграция и кастомизация функционала в Битрикс24 часто требует работы на уровне API. Сегодня мы подробно рассмотрим «Создать новую стадию rpa.stage.add». Вы узнаете экспертные методики работы с rpa.stage.add и научитесь

Читать далееЧитать далее

Как использовать метод SDK sale.property.update в Битрикс24Как использовать метод SDK sale.property.update в Битрикс24

25.05.202625.05.2026| goroshckogoroshcko| Нет комментария|

При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Как использовать метод SDK sale.property.update в Битрикс24», разберем

Читать далееЧитать далее

Получить историю задачи tasks.task.history.listПолучить историю задачи tasks.task.history.list

25.05.202625.05.2026| goroshckogoroshcko| Нет комментария|

При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Получить историю задачи tasks.task.history.list», разберем архитектурные особенности и

Читать далееЧитать далее