ТЗ на интеграцию систем: что написать, чтобы обмен между 1С, CRM и сайтом заработал с первого раза

Короткий ответ: в ТЗ на интеграцию описывают не экраны, а данные. Нужны шесть частей: какие системы и объекты связываем, какая система главная по каждому объекту, таблица маппинга полей и справочников, события и частота обмена, что делать при ошибке и как проверяем результат. Для связки двух систем это часто одна-две страницы и таблица — без них подрядчик угадывает, а угаданное потом переделывают.

Чем ТЗ на интеграцию отличается от ТЗ на сайт?

ТЗ на сайт отвечает на вопрос «что видит человек», ТЗ на интеграцию — «что происходит с записью». В нём нет макетов и текстов, зато есть ключи сопоставления, правила преобразования значений, очередь, повторы и журнал. Ошибка здесь не видна сразу: она всплывает через неделю расхождением остатков.

Если вы уже писали ТЗ на сайт по нашей инструкции о ТЗ на разработку сайта, многое пригодится: цель, границы работ, критерии приёмки. Но три вещи в интеграции особенные:

• Два хозяина у одной записи. Клиент живёт и в CRM, и в 1С. Если не решить, где его правят, обмен будет затирать изменения по очереди.
• Справочники не совпадают. «Самовывоз» на сайте, «Самовывоз со склада» в 1С и pickup в API — одно и то же только по вашему решению.
• Сбой — штатная ситуация. Сервер 1С перезагружается, CRM отвечает с задержкой, вебхук теряется. ТЗ должно говорить, что делать в эти минуты, а не только в хороший день.

Описание того, как работают люди, — отдельный документ. Его удобно готовить заранее по шаблону «как есть / как будет» из статьи как описать бизнес-процесс перед автоматизацией. ТЗ на интеграцию начинается там, где процесс уже понятен и нужно договориться о данных.

Из каких разделов состоит ТЗ на интеграцию?

Рабочий шаблон — восемь разделов. Каждый можно заполнить одним абзацем или таблицей; если раздел пуст, это вопрос, который всплывёт в разработке, только позже и дороже.

1. Цель и граница. Что перестаёт делаться руками. Например: «менеджеры больше не переносят заказы с сайта в 1С».
2. Системы и версии. Название, конфигурация и релиз 1С, тариф или редакция CRM, где стоит каждая система: облако или свой сервер.
3. Объекты обмена. Товары, цены, остатки, клиенты, заказы, оплаты, статусы — только то, что реально нужно.
4. Главная система по каждому объекту и ключ сопоставления.
5. Маппинг полей и справочников — таблица «поле там → поле здесь → правило».
6. События и частота. Что запускает передачу и как быстро данные должны оказаться на другой стороне.
7. Ошибки. Повтор, очередь, уведомление, кто разбирает.
8. Тестовые данные и приёмка. На чём проверяем и какой результат считаем готовым.

Отдельной строкой стоит записать, что не входит: например, перенос истории заказов за прошлые годы или изменение конфигурации 1С. Такие пункты чаще всего становятся предметом спора.

Объект	Где создают и правят	Кто только читает	Ключ для сопоставления
Товар, номенклатура	1С	Сайт, CRM	Артикул или код 1С
Цена	1С (вид цены «Розничная», «Оптовая»)	Сайт, CRM	Артикул + вид цены
Остаток	1С, по выбранным складам	Сайт, CRM	Артикул + склад
Клиент	CRM до первого документа, реквизиты — 1С	Сайт (личный кабинет)	ИНН + КПП, для физлиц — телефон
Заказ	Сайт или CRM — где он родился	1С	Номер заказа источника
Оплата, отгрузка	1С	CRM, сайт	Номер заказа + номер документа 1С

Как выбрать главную систему для каждого объекта?

Главная система — та, где запись создают и правят. Остальные только читают. Её выбирают отдельно для каждого объекта, а не одну на всё: товары и остатки обычно ведёт 1С, сделки — CRM, заказ — система, где он родился. Таблица ниже — заготовка, которую остаётся поправить под себя.

Три правила, которые стоит вписать в ТЗ рядом с таблицей:

• У каждого поля — один хозяин. Если адрес доставки правят и на сайте, и в 1С, укажите, чья правка главнее и в какой момент запись «замораживается», — например, после отгрузки.
• Ключ — не название. Сопоставлять товары по наименованию нельзя: одна лишняя точка — и появляется дубль. Артикул, код, ИНН, номер документа.
• Удаление тоже событие. Что происходит на сайте, если товар пометили на удаление в 1С: скрыть, оставить с пометкой «нет в наличии», убрать из каталога?

Неудачный ключ почти всегда даёт дубли: два «одинаковых» клиента или товара, у которых расходятся остатки и история. Объединять их после запуска дольше, чем один раз выбрать ключ в ТЗ.

Поле на сайте	Поле в 1С	Правило	Если значения нет
order.id	Номер по данным клиента	Копируем как есть, это ключ от повтора	Заказ не отправляем, пишем ошибку
customer.phone	Контрагент → телефон	Приводим к виду +7XXXXXXXXXX, ищем контрагента	Создаём контрагента «Розничный покупатель»
items[].sku	Номенклатура (по артикулу)	Ищем по артикулу, не по названию	Строку не создаём, заказ — в очередь разбора
delivery.method	Способ доставки	По таблице соответствий: courier → «Курьер»	Значение по умолчанию «Уточнить»
status: paid	Статус «Оплачен»	Справочник статусов — одна таблица на обе стороны	Статус не меняем, пишем в журнал

Что такое маппинг полей и как его оформить?

Маппинг — таблица соответствий: какое поле одной системы попадает в какое поле другой и по какому правилу. Минимум четыре колонки: поле-источник, поле-приёмник, правило преобразования и поведение при пустом значении. Без последней колонки обмен ломается на первом же неполном заказе.

Как собрать маппинг без мучений:

1. Попросите у разработчика выгрузку одного реального заказа или товара из каждой системы — со всеми полями, как их отдаёт API.
2. Отметьте поля, которые реально используются. Обычно это заметно меньше половины полей.
3. Для каждого поля впишите правило: копируем как есть, приводим формат, ищем по справочнику, вычисляем.
4. Отдельным листом выпишите справочники: статусы, способы доставки, оплаты, склады, единицы измерения, виды цен — значение слева, значение справа.
5. Для каждого справочника решите, что делать с новым значением, которого нет в таблице: значение по умолчанию или остановка с уведомлением.

Частые ловушки в маппинге:

• Форматы. Телефон «8 (900) 123-45-67» и «+79001234567», дата с часовым поясом и без, цена с копейками и в целых рублях, НДС внутри цены или сверху.
• Длина полей. Адрес из формы сайта может не поместиться в поле другой системы и обрезаться молча.
• Составные товары. Характеристики — размер, цвет — в одной системе отдельные товары, в другой — варианты одного.
• Единицы. На сайте продают упаковку, в 1С учитывают штуки.

Живой пример из нашей практики — магазин AleksFurs: обмен с 1С идёт по CommerceML 2.08, новая позиция создаётся, существующая обновляется по артикулу, товар без цены скрыт до загрузки цен, а заказы уходят в 1С и повторно не выгружаются. Каждое из этих правил — строка в ТЗ.

Какие события и частоту обмена указать?

Для каждого объекта запишите, что запускает передачу и какая задержка допустима. Заказ и оплата обычно нужны на другой стороне в течение минут, остатки — с интервалом, который выдерживает ваш темп продаж, справочник товаров — раз в час или раз в сутки. Формулировка «в реальном времени» без цифры — не требование.

Способов запуска три, и в ТЗ полезно указать, какой ожидается:

• По событию. Система сама сообщает о новом заказе или смене статуса — через вебхук. Быстро, но требует защиты от потерь; подробности — в статье что такое вебхук.
• По расписанию. Обработчик раз в N минут забирает изменения. Проще и надёжнее, но с задержкой.
• Вручную. Кнопка «выгрузить сейчас» — нужна как запасной путь даже при автоматическом обмене.

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

Как описать обработку ошибок?

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

Шаблон раздела, который можно взять целиком:

• Повтор. При недоступности системы — повтор через 1, 5 и 30 минут, затем запись уходит в очередь ошибок.
• Очередь. Неотправленные записи не теряются: их видно списком, с причиной, и можно отправить повторно одной кнопкой.
• Защита от двойной отправки. Повтор не создаёт второй заказ: на стороне приёмника проверяем ключ — номер заказа источника.
• Уведомление. Кому и куда: менеджеру в Telegram о каждом застрявшем заказе, администратору — если обмен стоит дольше часа.
• Журнал. Что записываем: время, объект, направление, результат, текст ошибки. Срок хранения журнала.
• Остановка. При каких ошибках обмен останавливается целиком, — например, если пришла выгрузка, где у всех товаров нулевые остатки.

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

Какие тестовые данные и критерии приёмки записать?

Проверять нужно на копии реальных данных, а не на трёх придуманных записях. В ТЗ перечислите обычные случаи и неудобные, и для каждого — ожидаемый результат. Тогда приёмка становится сверкой по списку, а не спором о впечатлениях.

Набор неудобных случаев, который стоит вписать почти в любой проект:

• заказ с товаром, которого уже нет в 1С;
• клиент, который уже есть в 1С, но с другим форматом телефона;
• заказ без необязательных полей и заказ с очень длинным комментарием;
• изменение заказа после отправки: добавили позицию, сменили адрес;
• отмена и возврат;
• недоступность одной из систем в момент обмена;
• одновременная правка одной записи в двух системах.

Критерии приёмки формулируйте проверяемо: «10 тестовых заказов из списка прошли в 1С с верными суммами, статусами и контрагентами; повтор не создал дублей; застрявший заказ виден в очереди и пришло уведомление». По нашему договору на проверку результата у заказчика 5 рабочих дней, а гарантия — 30 дней с даты акта; список случаев в ТЗ делает эти пять дней содержательными.

Как выглядит пример ТЗ на одну страницу?

Ниже — сокращённый пример для типовой задачи «сайт магазина и 1С». Он не заменяет таблицу маппинга, но показывает, сколько решений помещается на одну страницу и что подрядчику больше не придётся угадывать.

1. Цель: заказы с сайта попадают в 1С без ручного ввода; остатки и цены на сайте берутся из 1С.
2. Системы: сайт на своём движке; 1С на сервере компании, конфигурация и релиз указаны в приложении.
3. Объекты: товары, цены (вид «Розничная»), остатки (склады «Основной» и «Магазин»), заказы, статусы заказов.
4. Главные системы и ключи: товары, цены, остатки — 1С, ключ — артикул; заказ — сайт, ключ — номер заказа сайта.
5. Маппинг: таблица полей и справочники статусов, доставки и оплаты — приложение 1.
6. События: заказ — сразу после оформления; статусы из 1С — каждые 10 минут; остатки — каждые 15 минут; товары и цены — раз в сутки ночью и по кнопке.
7. Ошибки: три повтора, затем очередь; уведомление менеджеру в Telegram; если остатки обнулились у всех товаров — обмен останавливается, письмо администратору.
8. Приёмка: 10 обычных заказов и 7 неудобных случаев из списка — приложение 2; ожидаемый результат по каждому.
9. Не входит: перенос заказов за прошлые годы, изменение конфигурации 1С.

Цифры интервалов здесь условные — у вас они будут свои. Главное, что они есть, и каждая — повод договориться заранее.

Когда подробное ТЗ на интеграцию не нужно?

Подробный документ не нужен, если задача закрывается готовым модулем без доработок: штатный обмен, типовая конфигурация, стандартные поля. Тогда достаточно списка «что должно передаваться» и проверки на нескольких заказах. ТЗ окупает своё время там, где есть свои правила, нестандартные поля или больше двух систем.

Также не стоит писать ТЗ «на вырост» — с объектами, которые понадобятся когда-нибудь. Каждый лишний объект — новые поля в маппинге, новые ошибки и новые тесты. Разумнее запустить обмен по главному объекту и добавлять следующие, когда первый работает.

Какие ошибки в ТЗ на интеграцию встречаются чаще всего?

Чаще всего в ТЗ нет главной системы по объекту, нет поведения при пустом значении и нет списка неудобных случаев для теста. Все три пробела не видны при подписании и проявляются уже на живых данных.

• «Синхронизировать всё». Без списка объектов и полей это не требование, а пожелание.
• Справочники «по смыслу». Подрядчик сопоставит статусы так, как понял, а не так, как работает ваш склад.
• Нет версий систем. Без конфигурации, релиза и места установки 1С — облако или свой сервер — подрядчик не может точно оценить, как к ней подключаться.
• Нет владельца со стороны заказчика. Кто отвечает на вопросы по полям и разбирает очередь ошибок после запуска.
• Доработка системы спрятана в интеграцию. Если для обмена нужно новое поле в 1С, это работа на стороне 1С, и её стоит указать отдельно.

Сколько стоит интеграция по такому ТЗ и что входит?

Связка двух систем — например, сайта и 1С или CRM и склада — стоит у нас от 32 000 ₽, срок — от 2 дней. Каждая система сверх двух оценивается отдельно. Цену и срок фиксируем в договоре до старта, а готовое ТЗ на одну страницу делает оценку точнее.

В тариф интеграции систем входят аудит, схема обмена, обработчики, обработка ошибок и журнал, проверка на реальных данных и инструкция. Правок — до двух раундов: один на схеме интеграции, один после тестовой сборки. Это ровно те точки, где пригодится ваше ТЗ: схему сверяют с таблицами главных систем и маппинга, тестовую сборку — со списком случаев. Изменение конфигурации 1С или настроек CRM на их стороне и лицензии сторонних сервисов в тариф не входят. После запуска 7 дней исправляем сбои бесплатно, дальше — поддержка от 7 900 ₽/мес. О том, из чего ещё складывается цена связки, — в статье об интеграции по API.

Короткие ответы на частые вопросы

Чем ТЗ на интеграцию отличается от ТЗ на сайт?

ТЗ на сайт описывает страницы и поведение интерфейса, ТЗ на интеграцию — данные: какие объекты ходят между системами, кто из систем главный, по какому событию идёт обмен и что делать при сбое. Экранов в нём почти нет.

Сколько страниц должно быть в ТЗ на интеграцию?

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

Кто составляет маппинг полей — заказчик или разработчик?

Вместе. Заказчик знает, что значит поле в работе и какие значения в справочниках, разработчик — какие поля отдаёт API. Удобно, когда разработчик готовит черновик таблицы по выгрузке, а заказчик проверяет смысл каждой строки.

Нужно ли описывать обработку ошибок, если подрядчик опытный?

Да, потому что это бизнес-решение: ждать ли оператора, отклонять ли заказ, кого будить ночью. Технически повтор и журнал сделает разработчик, но что считать критичным, решаете вы.

На каких данных проверять интеграцию перед запуском?

На копии реальных данных: десяток обычных заказов и набор неудобных случаев — пустое поле, удалённый товар, клиент-дубль, длинный адрес, возврат. Список таких случаев полезно вписать прямо в ТЗ.

Услуги и кейсы по теме: интеграция с 1С и CRM от 32 000 ₽ · кейс AleksFurs · цены и сроки