Почти любая интеграция сводится к переводу данных с языка одной системы на язык другой. В CRM клиент — это contact с полями firstName и lastName, в учётной системе — Контрагент с полем Наименование, а в XML для налоговой — элемент СвФЛ с атрибутами. Правила такого перевода — маппинг — чаще всего живут в голове разработчика или в коде трансформации. Пока всё работает, это незаметно. Когда появляется расхождение данных, выясняется, что никто не может сказать, откуда в поле взялось значение. Разберём, как оформить маппинг так, чтобы он был понятен и разработчику, и тестировщику, и через год вам самим.
Что такое маппинг и зачем он отдельным документом
Маппинг данных (спецификация соответствий, mapping specification) — описание того, как каждое поле целевой структуры получается из полей источника: напрямую, через преобразование, справочник, константу или вычисление.
Зачем выделять его в отдельный артефакт, если есть контракты API обеих сторон:
- Контракты описывают структуры, но не связь между ними. По двум схемам OpenAPI нельзя понять, что
status: "A"в одной системе означаетACTIVEв другой. - Маппинг — основа для тестирования. Тестировщик проверяет преобразование по таблице, а не по коду.
- Маппинг — основа для разбора инцидентов. Когда в целевой системе неверное значение, первый вопрос — по какому правилу оно получено.
- Маппинг обсуждают с бизнесом. Владелец данных подтверждает, что «дата заключения договора» — это действительно дата подписания, а не дата регистрации в системе.
Структура таблицы маппинга
Самая удобная форма — таблица, где одна строка соответствует одному полю целевой структуры. Почему целевой: каждое поле результата должно откуда-то получить значение, и так легко увидеть поля, для которых правило не определено. Поля источника, которые никуда не идут, перечисляют отдельно.
| Колонка | Что писать |
|---|---|
| № | номер правила, на него ссылаются в задачах и дефектах |
| Целевое поле | путь в целевой структуре: customer.contacts[].phone или XPath /Документ/СвФЛ/@ИНН |
| Тип и ограничения цели | тип, длина, формат, обязательность |
| Источник | путь в исходной структуре; несколько полей, если значение составное |
| Тип источника | тип и формат исходного поля |
| Правило | как получается значение: «напрямую», «по справочнику», формула, условие |
| Если пусто | что делать, если в источнике нет значения: пропустить поле, значение по умолчанию, ошибка |
| Пример | значение на входе → значение на выходе |
| Комментарий | вопросы, ссылки на требования, кто подтвердил |
Пример
Передача клиента из CRM (JSON) в учётную систему (XML):
| № | Целевое поле | Источник | Правило | Если пусто | Пример |
|---|---|---|---|---|---|
| 1 | /Контрагент/@Ид, строка(36), обяз. | id | напрямую | ошибка, сообщение не отправлять | "c7a1…" → c7a1… |
| 2 | /Контрагент/Наименование, строка(250), обяз. | lastName, firstName, middleName | склеить через пробел, пустые части пропустить, обрезать до 250 | ошибка | Иванов, Иван, — → «Иванов Иван» |
| 3 | /Контрагент/ВидЛица, перечисление, обяз. | type | по справочнику: person → ФЛ, company → ЮЛ, entrepreneur → ИП | ошибка | "person" → ФЛ |
| 4 | /Контрагент/ИНН, строка 10 или 12 цифр | taxId | убрать пробелы; проверить длину: 12 для ФЛ и ИП, 10 для ЮЛ | элемент не передавать | " 7701 234567 " → 7701234567 |
| 5 | /Контрагент/Телефон, 0..1 | phones[] | первый телефон с isPrimary = true, иначе первый в списке; привести к формату +7XXXXXXXXXX | элемент не передавать | ["8 (900) 111-22-33"] → +79001112233 |
| 6 | /Контрагент/ДатаСоздания, xs:date | createdAt (date-time, UTC) | перевести в часовой пояс Москвы, взять дату | текущая дата | 2026-10-05T22:30:00Z → 2026-10-06 |
| 7 | /Контрагент/Источник | — | константа CRM | — | CRM |
Обратите внимание на правило 6: без него разработчик возьмёт дату из UTC, и клиенты, созданные поздно вечером, окажутся созданы «вчера» в учётной системе. Именно такие мелочи маппинг и должен фиксировать.
Виды правил
- Прямое соответствие — значение переносится как есть. Даже здесь стоит проверить типы и длины: строка 500 символов в поле на 250 — уже правило (обрезать, отклонить?).
- Преобразование формата — даты, телефоны, суммы (копейки в рубли), регистр, кодировки.
- Справочное соответствие — перевод кодов одной системы в коды другой. Таблицу соответствия выносят отдельно, если значений больше пяти — в отдельный лист или справочник.
- Константа — значение, которого нет в источнике, но которое требует цель.
- Вычисление — сумма, количество, склейка, извлечение части строки.
- Условие — «если тип = ЮЛ, то КПП из поля
kpp, иначе не передавать». - Обогащение — значение, которого нет в сообщении, а берётся из другой системы или справочника по ключу. Это важно отметить отдельно: появляется зависимость от ещё одного источника.
- Агрегация и разбиение — несколько записей источника в одну цель или наоборот.
Справочники и перекодировки
Перекодировка значений — самое частое место ошибок. Для каждой таблицы соответствий нужно ответить на вопросы:
- Полнота. Все ли значения источника имеют соответствие? Что делать с неизвестным значением: ошибка, значение по умолчанию, пропуск?
- Однозначность. Если двум значениям источника соответствует одно значение цели, обратное преобразование станет невозможным — это нормально для односторонней интеграции, но опасно для двусторонней синхронизации.
- Где живёт таблица. В коде, в конфигурации или в справочнике, который может менять пользователь? Кто её владелец?
- Что при изменении справочника. В источнике появился новый статус — интеграция упадёт, пропустит запись или передаст значение по умолчанию? Узнает ли кто-нибудь об этом?
| Статус в CRM | Статус в учётной системе | Комментарий |
|---|---|---|
lead | — (не передавать) | потенциальные клиенты в учёт не попадают |
active | Действующий | |
suspended | Действующий | в учётной системе нет приостановки; подтверждено владельцем данных |
closed | Закрыт | |
| любое другое | ошибка | сообщение в очередь разбора, уведомление дежурному |
Пустые значения
Отдельная колонка «Если пусто» в таблице не случайна. Для каждого поля нужно различать:
- поле отсутствует в источнике;
- поле присутствует со значением null;
- поле содержит пустую строку или строку из пробелов;
- поле содержит значение-заглушку:
"-","0","N/A", дата1900-01-01.
И для каждого случая решить, что передаём в цель. Особенно важно при обновлении: «поле не пришло» обычно означает «не трогать», а «пришёл null» — «очистить». Если цель — XML, решение ещё и техническое: отсутствующий элемент, пустой элемент или xsi:nil.
Массивы и вложенные структуры
Правила для коллекций описывают на уровне коллекции, а затем — для полей её элементов:
- сколько элементов допустимо в цели и что делать, если в источнике больше (взять первые N, отклонить);
- как выбирать элемент, если в цели одно значение, а в источнике список (первый, основной, последний по дате);
- порядок элементов в цели;
- как сопоставлять элементы при обновлении: по идентификатору, по позиции или заменой списка целиком.
Для путей внутри массивов удобна запись с []: items[].price → Товары/Товар/Цена, с примечанием «для каждого элемента».
Ошибки и неполные данные
Маппинг должен описывать не только успешное преобразование, но и что происходит, когда оно невозможно:
- какие ошибки останавливают передачу всего сообщения, а какие — только поля;
- куда попадают отклонённые сообщения: лог, очередь разбора, ответ источнику;
- кто получает уведомление и в каком виде;
- можно ли передать сообщение повторно после исправления данных.
Форма документа
Маппинг чаще всего ведут в таблице (Excel, Google Sheets, страница вики), и это нормально, если соблюдать несколько правил:
- Версия и дата в заголовке, история изменений — отдельным листом или разделом.
- Ссылки на контракты обеих сторон с версиями: маппинг составлен для OpenAPI v2.3 источника и XSD v1.7 цели.
- Справочники перекодировок — отдельными листами, со ссылками из основной таблицы.
- Открытые вопросы выделены цветом или отдельной колонкой, с ответственным.
- Набор тестовых примеров — пары «входной документ → ожидаемый результат», включая граничные случаи.
Всё чаще маппинг хранят рядом с кодом в текстовом формате — Markdown-таблица или YAML — и версионируют в git вместе с контрактами. Тогда изменение маппинга проходит ревью так же, как изменение кода, и всегда видно, какая версия правил действовала на дату инцидента.
Как проверять маппинг
- Полнота цели: у каждого обязательного поля цели есть правило.
- Полнота источника: про каждое поле источника известно, куда оно идёт или почему не используется.
- Совместимость типов и длин для каждой пары полей.
- Перекодировки: покрыты все значения справочников источника.
- Граничные случаи: пустые значения, максимальные длины, спецсимволы и кавычки, кириллица, даты на границе суток и часовых поясов, массивы из нуля и одного элемента.
- Обратимость для двусторонних интеграций: туда и обратно — то же значение.
- Проверка на реальных данных: прогнать выгрузку из промышленной системы через преобразование и посмотреть, что получилось, — до запуска, а не после.
Типичные ошибки
- Маппинг «по названиям полей» — поля с одинаковыми именами в разных системах означают разное (
date— дата создания или дата документа?). - Нет правила для неизвестных значений — в источнике появился новый статус, интеграция молча передаёт пустоту.
- Часовые пояса — дата смещается на сутки.
- Обрезка без предупреждения — наименование организации теряет окончание, и документы не проходят сверку.
- Маппинг не обновляется — код давно делает иначе, а документ остался в первой версии.
- Нет примеров — формулировка «привести к формату телефона» понимается тремя разработчиками тремя способами.
Итог
Маппинг — мост между контрактами двух систем. Хорошая спецификация соответствий описывает для каждого поля цели источник, правило, поведение при пустом значении и пример, а отдельно — справочники перекодировок, работу с массивами и ошибки. Она становится общим языком для аналитика, разработчика, тестировщика и владельца данных и экономит недели при разборе первого же расхождения.
Структуры обеих сторон удобно держать рядом: JSON Schema, XSD или OpenAPI, а примеры документов проверять в инструментах JSON и XML. Для быстрой проверки преобразований пригодятся гайды «JSON в XML» и «XML в JSON». Таблицу маппинга можно вести в Markdown прямо в проекте. О том, почему JSON и XML плохо стыкуются на уровне схем, — в статье «JSON Schema и XSD».
