Как получить список полей Битрикс24 и выгрузить его в CSV
Соберите названия, технические коды и свойства полей для интегратора. Разберём, где посмотреть каталог, как выбрать нужные строки и что проверить в CSV.
Перед обменом данными разработчику нужен перечень полей: как они называются, какой у них тип и по какому коду к ним обращаться. Выгрузка сделок для этой задачи избыточна: она содержит записи CRM, а не отдельный каталог их структуры. Сначала определите, что именно предстоит передать.
Какой список нужен
Для просмотра пользовательских полей откройте CRM → Ещё → Настройки → Настройки CRM → Настройки форм и отчётов → Пользовательские поля и выберите тип элемента. Расположение меню зависит от интерфейса портала. Этот раздел подходит для проверки существующих пользовательских настроек; менять их ради получения списка не требуется.
Для перечня технических описаний системных и пользовательских полей выбранной сущности можно использовать справочник или REST-метод crm.item.fields. Если нужен один код по известному названию, достаточно инструкции по поиску кода поля.
Для таблицы «одна строка — одна сделка» используйте штатный экспорт данных CRM. Он решает другую задачу: передаёт значения записей. Не отправляйте клиентскую базу, если интегратору нужны только названия и коды полей.
Как открыть каталог полей
В установленном справочнике TrueTell выберите нужную сущность. Начните со сделок, если обмен будет записывать сведения в сделку; поля контакта или компании выгружайте отдельно. Похожая подпись в двух каталогах не подтверждает одинаковое назначение.
Таблица позволяет сравнить название, код, тип, техническую обязательность и множественность. Переключение страниц нужно для просмотра. Чтобы подготовить CSV, не требуется по очереди открывать каждую страницу.
Справочник работает с четырьмя сущностями: сделки, лиды, контакты и компании. Каталог смарт-процессов в эту версию не входит. Если приложение ещё не подключено, сначала обсудите возможность подключения; наличие инструкции не означает доступность публичной установки.
Как выгрузить нужные поля в CSV
Поиск, тип и категория действуют одновременно. Например, если в строке поиска осталось название одного поля, категория «Пользовательские» не покажет все пользовательские поля: останутся только совпадения с этим названием. Для полного списка используйте «Сбросить фильтры» и проверьте выбранную сущность.
Выберите сущность и область списка.
Сбросьте фильтры для полного каталога или оставьте согласованный поиск, тип и категорию для выборки.
Нажмите «Экспорт CSV».
Приложение заново запросит описания полей и применит выбранные фильтры ко всему каталогу. Текущая страница таблицы не ограничивает выгрузку.
Дождитесь начала загрузки.
Не блокируйте и не закрывайте вспомогательное окно до начала скачивания. Если браузер сообщает о блокировке окна, разрешите его для этого действия и повторите экспорт.
Проверьте файл в загрузках.
Убедитесь, что скачался CSV для нужной сущности. При нулевом результате фильтра файл не формируется: сначала измените выборку.
Сохраните рядом с файлом дату, название портала и применённые фильтры. Если каталог изменился между просмотром и экспортом, заново полученный список может отличаться от прежнего количества на экране. Для четырёх сущностей подготовьте четыре отдельных файла и подпишите их.
Какие колонки будут в файле
Текущий CSV содержит восемь колонок. Он удобен как исходник для согласования структуры: интегратор видит код рядом с понятным названием и типом. Указанные ниже свойства относятся к описанию поля, а не к конкретной сделке.
| Колонка | Содержание | Что учитывать |
|---|---|---|
| Сущность | Сделки, лиды, контакты или компании | Одинаковое название в разных сущностях может обозначать разные поля |
| Название | Подпись, которую передал API | Не заменяет технический код |
| Код универсального API | Точный ключ описания поля | Используйте формат, который ожидает целевой REST-метод |
| Дополнительный код API | upperName, если он передан | Не считайте взаимозаменяемым с основным ключом |
| Тип | Технический тип, например string или double | Специальные типы могут требовать отдельной обработки |
| Обязательное | Технический признак isRequired | Не описывает обязательность на стадии CRM |
| Множественное | Признак isMultiple | Учитывайте возможность нескольких значений |
| Категория | Системное, пользовательское или не определено | Это классификация описания поля, а не оценка его использования |
Если свойство отсутствует в ответе, в файле может быть «Не передано API»; если API вернул null — «Не указано». Это не то же самое, что «Нет». Не заменяйте такие состояния автоматически логическим значением.
В текущем справочнике используется crm.item.fields с useOriginalUfNames=Y: пользовательские ключи сохраняют исходный формат UF_CRM_…. У системного поля основное имя может выглядеть как title, а дополнительное — TITLE. Выбирайте имя по документации конкретного метода; самостоятельно менять регистр нельзя.
Как открыть CSV и проверить результат
Файл формируется в UTF-8 с BOM, разделителем «точка с запятой» и строкой заголовков. Если табличный редактор показывает нечитаемый текст или одну длинную колонку, откройте файл через импорт текста и явно задайте UTF-8 и разделитель ;. Сохраните исходный CSV до редактирования.
Проверьте восемь колонок, сущность, несколько известных названий и точность кодов. Коды лучше импортировать как текст. Число строк данных считайте без строки заголовков и сравнивайте с ожидаемой выборкой, учитывая возможные изменения каталога.
В текстовые ячейки с потенциально формульным началом приложение добавляет защитный апостроф. Его отображение зависит от редактора. Поэтому файл предназначен для просмотра и согласования; не считайте его готовым входом для обратного импорта без проверки правил обработки.
Если поле не найдено, сначала сбросьте фильтры и проверьте сущность и портал. При сообщении об ошибке загрузки выполните предложенный в интерфейсе шаг восстановления. Отказ чтения API и отсутствие совпадений — разные состояния; пустая выборка сама по себе не доказывает удаление поля.
Что передать интегратору вместе со списком
Одних кодов недостаточно для обмена. В рабочей копии таблицы добавьте назначение поля, источник значения, правила преобразования, допустимые пустые значения и ответственного за проверку. Совпадение названий в двух системах не заменяет согласование смысла данных. Этот шаг особенно важен при интеграции Битрикс24 и МоегоСклада.
Каталог не показывает заполненность карточек, использование поля роботами, настройки видимости или обязательность на конкретной стадии. Он также не содержит полной конфигурации, значений вариантов списков и данных для восстановления CRM. Эти сведения собирают отдельно под задачу; справочник не создаёт и не изменяет поля.
Для BI список помогает уточнить, что означает технический код, но сам не подключает наборы данных и не меняет подписи отчёта. Следующий шаг разобран в инструкции о первом BI-отчёте в Битрикс24.
Если нужно расшифровать отдельную колонку отчёта, начните с поиска названия поля UF_CRM в контексте BI. Каталог описаний не заменяет проверку источника и формул отчёта.
Перед использованием выгрузки разберите значение типа, множественности и обязательности поля. Эти свойства отвечают на разные вопросы и не описывают использование поля роботами или заполненность сделок.
Основной и дополнительный коды из CSV сверяйте с форматом имён конкретного REST-метода. Наличие обоих имён не делает их взаимозаменяемыми во всех запросах.
Если каталог нужен для интеграции, дополните его картой соответствия полей: укажите владельца данных, направление передачи, преобразования значений и ожидаемый результат.
Когда каталог собран для наведения порядка, переходите к методике аудита полей CRM: названия и коды дополняются назначением, проверкой значений и зависимостей, а затем решением по конкретному полю.
Частые вопросы
Где посмотреть список пользовательских полей сделки в Битрикс24?
В настройках CRM откройте пользовательские поля и выберите сделки. Названия пунктов меню могут отличаться. Для каталога системных и пользовательских описаний можно использовать установленный справочник полей или crm.item.fields для нужной сущности.
В CSV попадут только 20 полей с первой страницы?
В текущем справочнике таблица показывает по 20 строк на странице, а CSV формируется по всем совпадениям выбранной сущности и действующих фильтров. При экспорте каталог запрашивается заново, поэтому после изменений CRM количество может отличаться от прежнего экрана.
Как выгрузить все поля без фильтров?
Выберите нужную сущность, сбросьте поиск, тип и категорию, проверьте список и нажмите «Экспорт CSV». Для другой сущности повторите действие отдельно. Один файл не объединяет все четыре каталога.
Справочник выгружает значения полей из сделок?
Нет. CSV содержит описания полей: названия, коды, типы и технические свойства. Для строк со сделками и их значениями нужен отдельный экспорт данных CRM.
Можно ли открыть CSV в Excel?
Файл имеет кодировку UTF-8 и разделитель «точка с запятой». Если текст нечитаем или вся строка оказалась в одной колонке, используйте импорт текстового файла и явно выберите эти параметры. После открытия проверьте названия и точность кодов.
Почему найдено меньше полей, чем ожидалось?
Проверьте портал, сущность, строку поиска, тип и категорию. Справочник показывает описания, возвращённые API с текущими правами; он не объединяет поля разных сущностей. Ошибку загрузки не принимайте за отсутствие полей.
Можно ли восстановить настройки CRM из этого CSV?
Нет. Это каталог описаний для проверки и согласования. В нём нет значений карточек и полного набора настроек CRM, а справочник не создаёт и не изменяет поля.