Карта соответствия полей Битрикс24 для интеграции
Что согласовать между владельцем процесса и интегратором: смысл данных, точные поля, направление обмена, пустые значения и проверку результата.
У двух систем может быть поле «Статус», а задачи у этих полей — разные. В одной системе это этап доставки, в другой — стадия продажи. Если связать их только по подписи, технически успешный обмен способен передать неверный смысл. Карта нужна, чтобы договориться о значении данных до написания кода.
Сначала согласуйте операцию и результат
Выберите конкретный сценарий: что изменилось в источнике и что после этого должен увидеть сотрудник в CRM. Например, менеджеру нужно знать, отгружен ли заказ. Это не означает, что статус доставки должен автоматически переводить сделку в успешную стадию.
Определите участников: кто объясняет смысл поля, кто подтверждает технический источник и кто принимает результат. Если владельцы процесса ещё не решили, что считать оплатой, завершением или готовностью, разработчик не должен выводить это из названия столбца.
Ниже — предлагаемая рабочая методика и вымышленный пример. Это не официальный формат Битрикс24 и не описание внедрённого клиентского проекта. Состав карты можно расширять под конкретный обмен.
Что записать в карту соответствия
Для первого прохода достаточно описать одну связь подробно. В учебном примере статус доставки приходит из условной ERP в отдельное пользовательское поле сделки. Ниже нет готовых кодов вашего портала или подтверждённой настройки коннектора.
| Что фиксируем | Пример решения |
|---|---|
| Назначение | Показывать менеджеру статус доставки; не менять стадию продажи |
| Источник | Условная ERP, заказ, поле delivery_status; техническое имя учебное |
| Приёмник | Битрикс24, сделка, пользовательское поле «Статус доставки»; точный код получают на портале |
| Связь записей | Внешний ID заказа сопоставлен с ID сделки; равенство чисел не считается связью |
| Владелец и направление | В этом примере ERP определяет статус, обмен идёт в CRM; обратная запись не предусмотрена |
| Тип и количество значений | Код в источнике, одиночный список в CRM; соответствия вариантов согласованы отдельно |
| Событие и срок | Изменение статуса доставки; допустимую задержку и способ повторной обработки согласуют до разработки |
Когда источник и приёмник согласованы, добавьте правила значений, пустых состояний, повторов, ошибок и приёмки. Для каждой следующей связи повторяйте ту же структуру. Если несколько полей должны изменяться согласованно, отдельно опишите, что происходит при частичной ошибке.
Направление выбирают для каждого поля, а не только для интеграции в целом. Например, в учебной схеме ERP управляет доставкой, а менеджер ведёт комментарий в CRM. Двусторонняя синхронизация обоих полей потребовала бы отдельных правил конфликтов: чьё изменение и при каких условиях сохраняется.
Откуда взять точные названия, коды и типы
Если справочник полей CRM от TrueTell подключён к порталу, используйте его как источник метаданных сделок, лидов, контактов и компаний. Каталог помогает отличить похожие поля и записать техническое имя рядом с понятной подписью.
Экспорт описаний удобно использовать как заготовку; порядок работы разобран в инструкции по каталогу полей и CSV. Зафиксируйте портал, дату и фильтры выгрузки. Для точного кода и формата REST используйте разбор имён API, а для смысла свойств — материал о типах и множественности.
Каталог не показывает значения записей, зависимости роботов или используемость поля. Его CSV также не содержит готовой таблицы вариантов списка, соответствий внешним системам и всех настроек CRM. Эти части карты собираются отдельно; приложение не выполняет автоматическое сопоставление.
Сопоставляйте не только поля, но и значения
Связь «статус → статус» не объясняет, как переводить каждый вариант. В учебном примере внешнее значение ready означает «Готов к отгрузке», а shipped — «Отгружен». Приёмник — пользовательское поле «Статус доставки», а не стадия сделки.
Для списочного поля зафиксируйте соответствие внешнего кода конкретному варианту CRM. Одинаковая подпись не гарантирует одинаковый идентификатор на разных порталах. Проверьте настройки поля и подходящий метод его конфигурации. Также решите, что делать с новым неизвестным вариантом: отклонять изменение, отправлять на разбор или применять заранее согласованный резервный вариант.
Для привязок к объектам CRM нужна связь записей. Внешний клиент с ID 42 не становится контактом CRM с ID 42 по совпадению чисел. Сначала должна быть определена нужная запись, затем её идентификатор используется по правилам поля и метода.
Пустые значения и намеренное очищение
Разделите хотя бы четыре случая: ключ не пришёл; пришёл null; пришла пустая строка; отправитель явно просит очистить поле. У них могут быть разные причины. Для учебного статуса можно согласовать отсутствие ключа как «не менять CRM», а неизвестное пустое состояние — как ошибку, требующую разбора.
Это решения примера, а не поведение Битрикс24 по умолчанию. Если очистка допускается, запишите, кто может её инициировать и как она передаётся для конкретного типа и метода. Не используйте одну универсальную команду очистки для строк, списков, файлов и привязок без проверки документации.
Отдельно определите судьбу значения, которое не удалось преобразовать. Неверная дата, неизвестный код списка или отсутствующая связанная запись не должны молча заменяться похожим значением. В карте должен быть понятный следующий шаг и ответственный за исправление источника или правила.
Направление, повторы и конфликты изменений
Укажите событие обмена, допустимую задержку и способ повторной обработки после сбоя. «Синхронизировать постоянно» не объясняет, что делать, когда доставка уже изменилась второй раз, а старое событие пришло позже нового.
Согласуйте правила для повторного события и устаревшей версии: когда обновление пропускают, когда применяют и где виден результат. При двустороннем обмене дополнительно опишите, как предотвращается бесконечная передача одного изменения туда и обратно. Это требования к реализации, а не возможности справочника полей.
Уточните связанные автоматизации. Изменение одного поля может быть частью более широкого процесса, поэтому приёмка должна включать проверку ожидаемых действий и отсутствия ненужных повторов.
Как понять, что карта готова к разработке
У каждой связи должны быть примеры входа и ожидаемого результата. Начните с небольшой согласованной выборки и включите пограничные случаи. Следующий список описывает критерии проверки будущей интеграции; в рамках этой статьи обмен не запускался.
Правильная запись и значение.
Известный внешний объект связан с нужной записью CRM. Для обычного входа указаны точное целевое поле и ожидаемое значение.
Пустые и неизвестные данные.
Проверены отсутствие ключа, null, неизвестный вариант списка и недоступная связанная запись. Для каждого случая согласованы действие и ответственный.
Повтор и конфликт.
Повторное событие, устаревшее обновление и ручное изменение в CRM имеют понятный результат; нет дубликатов или бесконечного обмена.
Подтверждение результата.
После согласованного изменения проверяется целевое значение, а не только HTTP-ответ. Видны ошибка, результат повторной обработки и влияние на связанные процессы.
Документация crm.item.update отдельно предупреждает: некорректное поле может быть проигнорировано. Поэтому успешный ответ сам по себе не подтверждает выполнение договорённости. Проверять нужно согласованное значение в правильной записи.
Открытые вопросы оставляйте помеченными. Отсутствующий код, невыбранный владелец данных или неуточнённое правило очистки — повод уточнить карту, а не заполнить её предположением. Общий контекст такого обмена разобран в статье об интеграции Битрикс24 и МоегоСклада.
Если до сопоставления нужно разобраться в накопившихся полях, используйте методику аудита полей CRM. Она помогает отделить проблему вида карточки от изменения данных и зафиксировать основания решений.
Частые вопросы
Что такое карта соответствия полей Битрикс24?
Это рабочее описание того, откуда берётся значение, в какую сущность и поле CRM оно передаётся и по каким правилам. Кроме кодов в ней фиксируют смысл, направление обмена, типы, пустые значения, связь записей и критерии проверки.
Достаточно ли сопоставить одинаковые названия полей?
Нет. Похожая подпись может означать разные данные, например плановую и фактическую дату. Нужно проверить сущность, полный технический код, тип и назначение обоих полей.
CSV справочника уже является готовой картой интеграции?
Нет. Это каталог метаданных выбранной сущности с текущими фильтрами. Он помогает получить названия, коды и свойства, а правила обмена, значения списков и связи записей согласуют отдельно.
Можно ли связывать клиента по одинаковому ID в двух системах?
Совпадение чисел не подтверждает соответствие. Нужны правило поиска и сохранённая связь внешнего объекта с правильной записью CRM. Для привязки передают идентификатор нужной сущности по требованиям конкретного метода.
Пустое значение источника должно очищать поле CRM?
Это нужно согласовать отдельно. Отсутствие ключа, null, пустая строка и намеренное очищение не считаются одним случаем. Способ очистки зависит от типа поля и REST-метода; универсального правила для всех полей здесь нет.
Когда карту можно передавать разработчику?
Когда понятны источник и приёмник, зафиксированы точные коды, направление и владелец данных, правила преобразования и обработки ошибок, а нормальные и пограничные примеры имеют ожидаемый результат. Неуточнённые пункты должны оставаться явно открытыми.