Как сопоставить поля сайта, CRM и учётной системы

Начните со смысла, а не названий

Поле status существует во многих системах, но может означать этап продажи, техническую обработку или доступность записи. Совпадение имени не подтверждает совместимость. Для каждого значения запишите бизнес-определение и пример. Если два специалиста объясняют поле по-разному, автоматическое сопоставление нужно отложить до уточнения.

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

Задайте структуру карты

Не превращайте карту в копию всей документации API. Укажите только используемые операции и поля, но достаточно подробно, чтобы не возникали догадки. Сохраните ссылку на версию внешнего контракта и дату проверки. Если поставщик изменит формат, будет понятно, какое основание использовалось при разработке.

Сопоставьте идентификаторы и связи

Название организации, артикул и телефон не всегда устойчивы или уникальны. Определите первичный идентификатор каждой системы и таблицу соответствий. Для вариантов товара и связанных документов нужны отдельные ключи, если они самостоятельные объекты. Без этого обновление может создать дубли или привязать документ не к тому заказу.

Опишите поведение неизвестной связи. Если пришёл заказ с клиентом, которого ещё нет, система может ожидать зависимую запись, создать предусмотренную сущность или отправить ошибку на разбор. Выбор должен быть явным. Подстановка первого похожего клиента по названию не является безопасным универсальным решением.

Разберите форматы и справочники

Для дат определите часовой пояс, момент события и допустимость отсутствия времени. Для сумм — валюту, точность, единицу и округление. Для телефона — сохранение исходного значения и нормализованное представление, если оно нужно. Не теряйте ведущие нули у идентификаторов, которые выглядят числом, но являются строковым кодом.

Статусы и причины отказа требуют отдельной таблицы соответствий. Если несколько значений источника объединяются в одно, отметьте потерю детализации. При обратном обмене такое преобразование может быть неоднозначным. Новое неизвестное значение должно попадать в контролируемую ошибку или предусмотренный общий статус, а не случайно считаться успешным.

Опишите частичные изменения

Отсутствующее поле в запросе часто означает «не изменять», а явное пустое значение может означать очистку — но это зависит от контракта. Зафиксируйте правило для каждого важного поля. Не отправляйте полную старую копию объекта, если операция требует только одного изменения: так можно затереть новые данные другой стороны.

Версия записи помогает обнаружить конфликт, однако нужно определить реакцию на несовпадение. Повторить чтение, показать оператору или отклонить изменение — разные решения. В карте укажите ожидаемый результат и доступную диагностику. Успешный ответ HTTP проверяет транспортный результат, а правильность значений подтверждается отдельной сверкой.

Учебный пример суммы заказа

Источник передаёт цену в минимальных денежных единицах, а интерфейс ожидает значение с дробной частью. Карта задаёт преобразование и округление, затем проверяет ноль, дробную сумму, большую сумму и отсутствующую валюту. Отрицательное значение не принимается автоматически как скидка, если такой смысл не предусмотрен. Пример условный и не описывает конкретный API.

Добавьте пакет из нескольких строк, одна из которых содержит неизвестный статус. Укажите, применяется ли пакет целиком или допускает частичный успех. Отчёт должен позволять найти исходную запись и повторить исправленную обработку. Иначе сотрудник знает только о «сбое интеграции», но не понимает, какие данные уже изменились.

Как поддерживать карту после запуска

Сохраняйте версию правил вместе с изменением интеграции. При добавлении поля обновляйте примеры и проверку старых записей. Карта полезна разработчику, тестировщику и владельцу процесса, если по ней можно объяснить каждое преобразование. Для CRM это также основа достоверных карточек и отчётов, а не формальное приложение к задаче.

Чем различаются пустое поле, null и отсутствие поля в обмене

Эти состояния могут означать разные операции: очистить значение, оставить прежнее или сообщить, что данных нет. Контракт должен задавать смысл каждого случая. Если любое отсутствие превращать в пустую строку, частичное обновление случайно удалит ранее заполненные данные.

Добавьте в таблицу сопоставления допустимые типы, преобразование и правило очистки. В учебной проверке передайте запись без телефона, с явно пустым телефоном и с новым номером. Ожидаемые результаты должны различаться согласно контракту. То же касается единиц измерения, часовых поясов и идентификаторов: визуально похожие значения не всегда взаимозаменяемы. Необработанное преобразование лучше обнаружить до массового импорта, чем исправлять после потери исходной информации.