Хорошее ТЗ на интеграцию отвечает на пять вопросов: какие системы и кто за них отвечает, какие данные передаются, в какую сторону и как часто, как записи узнают друг друга и что происходит при сбое. Если хотя бы один ответ звучит как «разработчик разберётся», согласования растянутся на недели, а спорные места всплывут уже после запуска. Ниже — чек-лист, по которому мы сами собираем требования к интеграции на аудите, и пример того, как описать один поток данных.
- ТЗ на интеграцию — это не перечень «хотелок», а договорённость о данных: кто источник правды по каждому полю.
- Описывайте по потокам: «заказ с сайта в 1С», «статус из 1С в CRM» — каждый поток отдельно.
- Обязательные разделы: системы и владельцы, сущности и поля, направление и частота, ключи сопоставления, ошибки и повторы, мониторинг.
- Неделя на аудит перед разработкой дешевле, чем месяц переделок после неё.
Зачем техническое задание на интеграцию систем, если подрядчик всё равно проведёт аудит
Аудит отвечает на вопрос «что технически возможно»: какие у систем API, форматы и лимиты. ТЗ отвечает на вопрос «что нужно бизнесу»: какие данные важны, кто принимает решения и что считать ошибкой. Без второго первое превращается в угадывание — разработчик сделает обмен, который работает, но не так, как ждал коммерческий директор.
Когда мы берём проект по разработке API и нестандартных интеграций, первая неделя уходит на аудит систем, API и данных, вторая — на архитектуру обмена. Если заказчик приходит с черновиком ТЗ, эти две недели проходят быстрее: не нужно собирать владельцев систем по одному и выяснять, почему в 1С три поля «Телефон». Черновик не обязан быть техническим — достаточно ответов по пунктам ниже.
Чек-лист ТЗ на интеграцию: что описать до разработки
Отметьте пункты, на которые у вас уже есть ответ. Всё, что осталось пустым, — повестка первой встречи с подрядчиком.
- Перечислены все системы: название, версия или конфигурация, где размещена (облако, свой сервер).
- У каждой системы назначен владелец со стороны компании и указан контакт администратора или вендора.
- Есть список сущностей для обмена: клиенты, заказы, товары, остатки, оплаты, статусы, документы.
- По каждой сущности перечислены поля и указано, какая система — источник правды по каждому полю.
- Для каждого потока указано направление: в одну сторону или двусторонний.
- Указана частота: в момент события, раз в N минут, раз в сутки.
- Определены ключи сопоставления: по какому полю запись в одной системе находит свою пару в другой.
- Описаны справочники, которые нужно сопоставить: статусы, склады, типы цен, единицы измерения, менеджеры.
- Решено, что делать с уже накопленными данными: переносить историю или начинать с даты запуска.
- Описано поведение при ошибке: повтор, очередь, уведомление ответственного.
- Назначено, кто получает алерты о сбое и в какой срок реагирует.
- Перечислены ограничения: лимиты API, окна обслуживания, требования к хранению данных в Казахстане.
- Есть критерии приёмки: какие сценарии должны пройти на тесте, прежде чем включать обмен на боевых данных.
Системы, владельцы и границы проекта
Начните с карты: прямоугольники — системы, стрелки — потоки данных. Даже набросок на листе бумаги снимает половину вопросов. Для каждой системы запишите, кто внутри компании отвечает за её настройки и кто может выдать доступы. Частая картина: 1С ведёт внешний программист, сайт — другой подрядчик, CRM — отдел продаж. Если не назначить человека, который принимает решения по правилам обмена, каждое разногласие будет ждать совещания.
Отдельно зафиксируйте границы: что точно не входит в проект. Например, «перенос архива сделок за пять лет — не входит» или «интеграция с бухгалтерской базой второго юрлица — следующий этап». Это защищает от разрастания задачи на середине разработки.
Сущности и поля: описание интеграции на примере
Самая трудоёмкая часть ТЗ — таблица полей. Её удобно вести в Excel или Google Таблицах: одна строка — одно поле. Ниже пример описания интеграции для потока «заказ с сайта в 1С и CRM».
| Поле | Источник правды | Куда передаётся | Правило |
|---|---|---|---|
| Номер заказа | Сайт | 1С, CRM | Не меняется после создания, служит ключом |
| Состав и цены | Сайт на момент заказа | 1С, CRM | Цена фиксируется, пересчёт только вручную менеджером |
| Остаток товара | 1С | Сайт | Обновление по расписанию и при изменении |
| Статус заказа | 1С | Сайт, CRM | Справочник статусов сопоставлен один к одному |
| Контакт покупателя | Система с последним изменением | Двусторонний | Конфликты пишутся в журнал, не перезаписываются молча |
Колонка «Источник правды» — главная. Если её нет, две системы начинают перезаписывать друг друга: менеджер исправил телефон в CRM, ночью пришла выгрузка из 1С и вернула старый. Правило простое: остатки — из учёта, статус сделки — из CRM, контакты — из той системы, где последнее изменение. Но записать его нужно явно, по каждому полю.
Справочники — отдельный пункт
Статусы, склады, типы цен, способы оплаты и доставки в разных системах называются по-разному. В ТЗ нужна таблица соответствий: «Собран» в 1С — это «Готов к выдаче» на сайте и стадия «Сборка завершена» в CRM. Если соответствия нет, интеграция либо остановится на незнакомом значении, либо подставит что-то по умолчанию — второе хуже.
Направление и частота обмена
Для каждого потока укажите, в какую сторону идут данные и насколько срочно они нужны. Не всё должно уходить мгновенно: оплату и новый заказ — да, справочник номенклатуры — достаточно раз в час или раз в сутки. Чем выше требование к скорости, тем сложнее и дороже архитектура, поэтому «в реальном времени везде» — плохое требование.
Если одна из сторон — интернет-магазин и 1С, сначала проверьте, не закрывает ли задачу типовой обмен. Для связки «магазин — 1С» есть отдельная услуга интеграции интернет-магазина с 1С: там дешевле и быстрее, чем разрабатывать нестандартный коннектор. Чем отличается штатный обмен от своей интеграции, мы разбирали в статье о CommerceML и собственном обмене.
Ключи сопоставления: как записи узнают друг друга
Ключ сопоставления — поле, по которому запись в одной системе находит свою пару в другой. Для товара это артикул, штрихкод или внутренний код из 1С. Для клиента — БИН или ИИН у юрлиц, телефон у физлиц. Для заказа — номер, который присвоила система-источник.
Сопоставлять по названию. «Кабель ВВГ 3х2,5» и «Кабель ВВГнг 3*2.5» — один товар для человека и два разных для программы. Если надёжного ключа нет, первым этапом проекта станет его наведение в данных: без этого обмен создаёт дубли.
Опишите, что делать, если пара не найдена: создать новую запись, поставить задачу менеджеру или отложить в очередь до ручного разбора. Каждый вариант уместен в своём случае, но выбрать его должен бизнес, а не программист по умолчанию.
Ошибки, повторы и мониторинг: раздел, который чаще всего пропускают
Требования к интеграции почти всегда описывают «как должно работать» и почти никогда — «что происходит, когда не работает». А сбои неизбежны: 1С обновляют, у банка технические работы, у вендора CRM меняется версия API. В ТЗ нужно зафиксировать:
- Очередь и повторы. Если принимающая система недоступна, данные ждут и уходят при восстановлении, а не теряются.
- Идемпотентность. Повторная отправка одного события не создаёт второй заказ или вторую оплату.
- Журнал. По каждому событию видно, что, когда и куда ушло и с каким результатом.
- Алерты. Кто получает уведомление о сбое — в Telegram, на почту — и за какое время должен отреагировать.
- Откаты. Как вернуть состояние, если обмен передал неверные данные.
ПРАВИЛОИнтеграция, которая падает молча, опаснее, чем её отсутствие: все уверены, что данные идут, а они не идут.
Как пройти путь от черновика до утверждённого ТЗ
- Соберите черновикКарта систем, список потоков и таблица полей по чек-листу выше. Не страшно, если половина ячеек пустая.
- Проведите аудитПодрядчик проверяет API, форматы, лимиты и состояние данных. На выходе — схема обмена, риски и смета. У нас это первая неделя проекта.
- Согласуйте архитектуруВладельцы систем подтверждают источники правды, справочники и поведение при ошибках.
- Утвердите критерии приёмкиСписок сценариев для теста: полный цикл, обрыв связи, повторная отправка, откат.
- Делите на этапыСначала связка, которая болит сильнее всего, затем следующая. Каждый коннектор — самостоятельный результат.
Документ аудита полезен сам по себе: с ним можно идти и к другому подрядчику, и сравнивать предложения на одной базе. Как формируется оценка и почему без аудита возможна только вилка, мы подробно разбирали в статье о стоимости интеграции через API. Ориентиры по форматам — коннектор двух систем от 400 000 ₸, шина данных для 3–5 систем от 900 000 ₸ — собраны на странице цен на CRM и интеграции.
Что делать дальше
Пройдите чек-лист и честно отметьте пустые пункты. Если не заполнены источники правды и ключи сопоставления — начните с них, это фундамент. Если пустой раздел про ошибки и мониторинг — обязательно поднимите его с подрядчиком: по нему видно, будет ли обмен работать годами или до первого обновления 1С.
Если систем больше двух, нет документации или одна из них — старая ERP или банк-клиент, приходите на аудит. За неделю мы составим схему обмена, список рисков и смету на нестандартную интеграцию систем, а ваш черновик ТЗ превратится в документ, по которому можно разрабатывать.
Кто должен писать ТЗ на интеграцию — заказчик или подрядчик?
Бизнес-часть — заказчик: какие данные нужны, кто источник правды, что считать ошибкой. Техническую часть — подрядчик по итогам аудита: протоколы, форматы, архитектуру очередей. Лучший результат даёт совместная работа на первой неделе.
Есть ли шаблон технического задания на интеграцию систем?
Универсальный шаблон — это разделы из чек-листа выше: системы и владельцы, сущности и поля, направление и частота, ключи, справочники, ошибки и мониторинг, критерии приёмки. Содержимое всегда своё.
Сколько времени занимает подготовка ТЗ?
Черновик заказчик собирает за несколько дней. Аудит и архитектура у подрядчика занимают около двух недель, после чего начинается разработка.
Можно ли начать разработку без полного ТЗ?
Можно начать с одного потока, для которого всё понятно, и параллельно дописывать требования к остальным. Начинать всё сразу без описания источников правды и ключей не стоит.
