UF_CRM и ufCrm: коды полей API Битрикс24
Как выбрать точное имя поля для REST-метода, зачем нужен useOriginalUfNames и почему нельзя автоматически менять регистр кода из справочника.
В одном примере интеграции написано TITLE, в другом — title. Пользовательское поле тоже может выглядеть по-разному. Вместо попыток угадать имя зафиксируйте, какой метод вызывается, с каким типом элемента и в каком режиме. Это делает проверку воспроизводимой.
UF_CRM и ufCrm: два режима имён
В crm.item.fields параметр useOriginalUfNames по умолчанию равен N. Для пользовательских полей это camelCase. Значение Y включает исходные имена. Пара из документации показана ниже; это пример формата, а не готовый код для вашего портала.
Параметр расположен на уровне запроса, рядом с entityTypeId, а не внутри fields. Сначала задайте режим явно при получении метаданных. Если затем читаете запись через crm.item.get, согласуйте тот же режим, чтобы сравнивать соответствующие имена.
Не выводите код другого поля из суффикса примера. Название, портал и сущность проверяются по текущим описаниям. Если требуется найти техническое имя по подписи, начните с инструкции о коде поля.
TITLE и title: проверьте семейство методов
В универсальном описании поле названия имеет ключ title, а свойство upperName может содержать TITLE. У crm.deal.fields название сделки описано ключом TITLE. Параметр формата пользовательских имён не переименовывает системные поля.
| Метод | Что уточнить | Что читать в ответе |
|---|---|---|
| crm.item.fields | entityTypeId и режим N/Y | result.fields: точный ключ и описание; у title может быть upperName: TITLE |
| crm.item.get | entityTypeId, ID записи и режим N/Y | result.item: значения записи в выбранном формате |
| crm.deal.fields | Поля именно сделок | result: описания с ключами семейства методов сделок, например TITLE |
У этих ответов различается и структура. Не ищите значения записи внутри описания поля: метаданные объясняют тип и свойства, а чтение записи возвращает её содержимое. Не переносите логику чтения result.fields в обработчик ответа crm.deal.fields без изменения структуры.
Для изменения сделки через crm.deal.update проверяйте правила этого метода и его объекта fields. Дополнительное имя из универсального ответа — подсказка для сверки, а не универсальная замена основного ключа.
Как читать два кода в справочнике
Если справочник TrueTell уже подключён, выберите нужную сущность и найдите поле. Основное имя подписано «Код универсального API», а второе, если оно получено, — «Дополнительный код API». Не объединяйте их в одну строку и не копируйте поясняющие подписи вместе с кодом.
Текущий справочник запрашивает crm.item.fields с useOriginalUfNames=Y, поэтому пользовательские ключи показывает в исходном формате. Системное title при этом остаётся title. Наличие второго имени зависит от того, что передал API.
Приложение помогает проверить метаданные сделок, лидов, контактов и компаний. Оно не переключает режим в вашей интеграции и не выполняет операции записи. Для нескольких полей можно подготовить каталог кодов в CSV, сохранив рядом назначение каждого поля.
Как проверить выбранный формат
Зафиксируйте метод и объект CRM.
Название метода, портал, сущность и ID записи — отдельные параметры задачи. entityTypeId описывает тип элемента, а ID — конкретную запись.
Получите актуальное описание.
Для универсального семейства задайте режим имён явно и проверьте result.fields. Для семейства сделок используйте его собственные описания и ключи.
Сверьте весь ключ и тип значения.
Проверьте полное имя без самостоятельного изменения регистра, затем тип, множественность и требования к передаче значения.
Проверьте результат чтением.
После согласованного изменения прочитайте ту же запись подходящим методом и сравните нужное значение, а не только HTTP-статус запроса.
Для crm.item.update документация отдельно описывает useOriginalUfNames для имён в запросе и ответе. Некорректный ключ в fields может быть проигнорирован. Поэтому успешный HTTP-ответ не подтверждает, что нужное поле получило ожидаемое значение.
Чтобы проверить именно имена без изменения CRM, начните с метаданных и разрешённого чтения. Вызов записи — отдельное действие по задаче интеграции. В этой статье реальные записи не изменялись: проверен экран описаний, а правила методов сверены с документацией.
Если поле не находится или запрос не даёт ожидаемого результата
Проверьте семейство и режим. Имя могло быть взято из другого метода, CSV старой интеграции или BI-отчёта. При переносе запроса согласуйте источник метаданных и обработку ответа. Для BI есть отдельная инструкция по сопоставлению технической колонки и названия поля.
Проверьте сущность и полный код. Поле контакта не становится полем сделки из-за похожего названия. Если справочник даёт несколько совпадений по части кода, сравните имя целиком. Старый код удалённого и заново созданного поля не считается актуальным автоматически.
Проверьте содержимое. Верное имя не исправляет неверный формат даты, массива или привязки. Отдельно прочитайте тип и технические свойства поля. Ограничение прав и ошибка значения требуют другого решения, чем выбор ключа.
Проверьте чтение после записи. Убедитесь, что сравниваются та же сущность, запись и режим имён. Если значение не изменилось, разберите ответ API и переданный объект fields. Не перебирайте варианты кодов повторными изменениями рабочей карточки.
Точный код — часть технического описания. Для согласования бизнес-правил используйте пример карты соответствия полей для интеграции: он включает направление обмена, пустые значения, повторы и критерии проверки.
Частые вопросы
UF_CRM и ufCrm — это разные поля?
Они могут обозначать одно пользовательское поле в разных режимах универсального API. Сначала проверьте портал, сущность и полное имя. Совпадение части имени само по себе не доказывает соответствие.
Что делает useOriginalUfNames?
В поддерживающих его универсальных методах параметр управляет форматом пользовательских имён. N соответствует camelCase, Y — исходным именам. Условия применения проверяйте на странице конкретного метода.
Параметр Y превращает title в TITLE?
Нет. Он относится к пользовательским полям. Для системного поля проверяйте точный ключ своего метода; например, crm.item.fields описывает title, а crm.deal.fields — TITLE.
Можно ли использовать дополнительный код API вместо основного?
Только если этот код соответствует требованиям выбранного метода. upperName в описании не означает, что два имени взаимозаменяемы в любом запросе. Основной ключ и дополнительное имя сверяют отдельно.
Почему запрос успешен, а поле не изменилось?
Проверьте ключ поля, сущность, ID, режим имён и формат значения. В crm.item.update некорректное поле может быть проигнорировано. После разрешённого изменения прочитайте запись через crm.item.get с согласованным режимом и сравните ожидаемое значение.
Справочник автоматически исправит имена в моей интеграции?
Нет. Справочник показывает метаданные четырёх основных сущностей и позволяет копировать коды. Он не редактирует запросы, не меняет поля и не настраивает интеграцию.