Требования к интеграции — это отдельный документ на девять разделов: какие системы и в какую сторону обмениваются, состав данных по полям, ключ соответствия записей, частота и триггер обмена, объёмы, поведение при отказе, журналирование, доступы и секреты, владелец и порядок изменений. Его пишут до разработки, а пользуются им обычно через год — когда никто уже не помнит, какая система главная по полю «скидка».
Документ, описывающий одну связку двух систем целиком: что передаётся, по какому ключу, как часто, что происходит при сбое, кто отвечает и как вносятся изменения. Живёт дольше проекта и дольше подрядчика: код можно прочитать, а вот причину, по которой скидка передаётся из CRM, а не считается в учёте, восстановить из кода невозможно.
Дальше — все девять разделов с заполненным примером. Связка: amoCRM и 1С:Управление торговлей, выгрузка выигранной сделки в документ «Заказ покупателя». Компания: оптовая торговля, 9 менеджеров, 320 сделок в месяц, пик — 40 сделок в день. Стоимость часа инженера — 2 900 ₽, сотрудника — 780 ₽, руководителя — 1 400 ₽.
Девять разделов и что ломается без каждого
Разделы идут в порядке от общего к частному, и это не эстетика: первые три отвечают на вопрос «что происходит», следующие три — «когда и сколько», последние три — «кто отвечает, если сломалось».
| Раздел | Что в нём написано | Что бывает, если пропустить |
|---|---|---|
| 1. Системы и направление | amoCRM — источник, 1С:УТ — приёмник, обмен односторонний. Обратно уходит только номер созданного заказа | Через полгода кто-то дописывает обратную выгрузку статусов, и два источника начинают перетирать данные друг друга |
| 2. Состав данных по полям | Таблица из 12 строк: поле в источнике, поле в приёмнике, тип, обязательность, поведение при пустом значении | Поле «скидка» тихо перестаёт приходить после обновления CRM, замечают на закрытии месяца |
| 3. Ключ соответствия | Контрагент — по ИНН и КПП, документ — по внешнему идентификатору сделки в реквизите заказа | Дубли контрагентов: один клиент четырьмя карточками, дебиторка считается неверно |
| 4. Частота и триггер | Триггер — переход сделки в статус «Успешно». Плюс сверка очереди раз в 5 минут | Обмен запускают «раз в сутки ночью», и менеджер весь день не видит, ушёл заказ или нет |
| 5. Объёмы | 320 сделок в месяц, пик 40 в день, до 60 позиций в заказе, лимиты API обеих систем | На пиковой неделе упираются в лимит запросов, обмен встаёт без единого сообщения об ошибке |
| 6. Поведение при отказе | Три попытки через 1, 5 и 15 минут, дальше карантин; уведомление при пяти записях за час | Непринятые заказы исчезают бесследно; узнают о них от клиента через неделю |
| 7. Журналирование | Что пишем в журнал, срок хранения 90 дней, что в журнал не попадает | Разбор любого спора превращается в гадание: доказать, что заказ уходил, нечем |
| 8. Доступы и секреты | Служебная учётная запись с правами только на нужные объекты; где хранятся ключи | Обмен работает под учётной записью уволившегося сотрудника и умирает в день её отключения |
| 9. Владелец и порядок изменений | Фамилия владельца интеграции и правило: сначала правка документа, потом правка кода | Через год документ описывает одну связку, а работает другая; доверие к тексту потеряно |
Отдельно стоит сказать про раздел 1. Направление обмена кажется очевидным ровно до того момента, когда обе системы получают право менять одно и то же поле. Правило, которое стоит записать буквально: у каждого поля ровно одна система-хозяин, остальные его только читают. Формулировка в документе выглядит так: «Цена и скидка — хозяин amoCRM. 1С:УТ значения не изменяет; ручная правка цены в заказе допускается только после снятия связи с сделкой».
Таблица полей — ядро документа
Всё остальное можно описать абзацем текста, а состав данных — только таблицей. Колонок пять: имя поля в источнике, имя в приёмнике, тип и ограничения, обязательность, поведение при пустом или неверном значении. Последняя колонка — та самая, из-за отсутствия которой обмены ломаются молча.
| Поле в amoCRM | Поле в 1С:УТ | Тип | Обяз. | Если пусто или неверно |
|---|---|---|---|---|
| ID сделки | Реквизит «Внешний идентификатор» | строка, 36 символов | да | Обмен не выполняется, запись уходит в карантин |
| ИНН компании | Контрагент.ИНН | строка, 10 или 12 цифр | да | Карантин, задача менеджеру «уточнить реквизиты» |
| КПП компании | Контрагент.КПП | строка, 9 цифр | для юрлиц | Для ИП пустое значение — норма, обмен продолжается |
| Название компании | Контрагент.Наименование | строка, до 150 | да | Для ключа не используется, служит только для чтения человеком |
| Ответственный | Менеджер | справочник пользователей | да | Подставляется «Не распределён», уведомление руководителю отдела |
| Дата закрытия сделки | Дата заказа | дата | да | Подставляется дата обмена, в журнале ставится пометка |
| Артикул позиции | Номенклатура по артикулу | строка, до 20 | да | Артикул не найден — карантин, задача категорийному менеджеру |
| Количество | Количество | число, 3 знака после запятой | да | Ноль или отрицательное — карантин, обмен по заказу не проводится |
| Цена за единицу | Цена | число, 2 знака после запятой | да | Пусто — карантин; цена из прайса не подставляется никогда |
| Скидка, % | Скидка ручная | число, 2 знака | нет | Пусто трактуется как 0; отдельно фиксируем, что это осознанное решение |
| Склад отгрузки | Склад | справочник складов | нет | Подставляется склад по умолчанию, закреплённый за менеджером |
| Комментарий менеджера | Комментарий | строка, до 1000 | нет | Обрезается по 1000 символов, факт обрезки пишется в журнал |
Две строки в этой таблице стоят дороже остальных десяти. Первая — «Цена за единицу» с припиской «цена из прайса не подставляется никогда»: без неё разработчик почти наверняка сделает разумное с виду умолчание, и заказ уедет по прайсовой цене вместо согласованной. Вторая — «Скидка, %» с явной трактовкой пустого значения: пустое поле и ноль — это разные вещи, и решение, что они означают одно и то же, должен принять заказчик, а не программист в три часа ночи.
Нарисованный бланк документа (не скриншот продукта) с шапкой «Паспорт интеграции · раздел 2. Состав данных» и таблицей на пять колонок: «Поле в источнике», «Поле в приёмнике», «Тип», «Обяз.», «Если пусто или неверно». Три строки заполнены целиком: «ИНН компании · Контрагент.ИНН · строка 10 или 12 цифр · да · карантин, задача менеджеру»; «Цена за единицу · Цена · число, 2 знака · да · карантин; цена из прайса не подставляется никогда»; «Скидка, % · Скидка ручная · число, 2 знака · нет · пусто = 0, решение согласовано». Ниже видны ещё девять частично заполненных строк и счётчик «12 полей». Чертёжный стиль, подписи по-русски.
Ключ соответствия: почему нельзя по названию
Ключ — это правило, по которому запись в одной системе опознаётся как та же самая запись в другой. Именно здесь совершается самая дорогая ошибка проектирования, и выглядит она безобидно: «будем искать контрагента по названию».
- Название нестабильно. «ООО Ромашка», «ООО «Ромашка»», «Ромашка ООО» и «ООО РОМАШКА» — четыре разных строки и четыре карточки контрагента. Через год дебиторка по клиенту разложена на четыре части, и ни одна не показывает реальный долг.
- Телефон не уникален и меняется. Один номер приходится на несколько юрлиц группы, а личный номер менеджера клиента меняется вместе с менеджером. Как это выглядит в базе на практике, мы разбирали в статье про дубли клиентов в CRM.
- Связка «название плюс сумма» кажется надёжной ровно до первого повторного заказа. Два одинаковых заказа в один день — обычное дело в оптовой торговле, и второй просто не создастся.
- Электронная почта — общая. На info@ приходят заявки от всех подразделений клиента, и в приёмнике они склеиваются в одного контрагента.
Рабочее правило записывается в документ двумя строками. Для контрагента ключ — ИНН и КПП: пара уникальна, меняется редко и проверяема. Для документа ключ — внешний идентификатор: система-источник передаёт свой идентификатор сделки, приёмник хранит его в отдельном реквизите заказа и при повторной передаче обновляет существующий документ, а не создаёт новый. Третье правило — про то, кто ключ выдаёт: идентификатор всегда назначает та система, которая создаёт запись, и никогда — принимающая.
Связка по наименованию дешевле на два часа разработки и дороже на несколько дней ручной чистки через год. В базе на 3 000 контрагентов доля дублей после года работы такого обмена обычно составляет 8–15 %, и склеивать их приходится вручную: автоматическое объединение карточек с разной историей платежей — отдельный риск для учёта.
Раздел отказов: три попытки, карантин, уведомление
Обмен падает всегда: у приёмника обновление, у источника лимит запросов, у сети — пять минут недоступности. Вопрос документа не в том, случится ли это, а в том, что происходит дальше. Раздел пишется числами, а не словами «предусмотрена обработка ошибок».
- 1Сколько повторных попыток и с какими интервалами. В примере — три: через 1, 5 и 15 минут. Интервалы растут, чтобы не добивать систему, которая уже перегружена.
- 2Куда уходит непринятое. В карантин — отдельное хранилище с полным телом сообщения и причиной отказа. Не в лог, не «в никуда с уведомлением»: из карантина запись должна повторно уходить в обмен одной кнопкой после исправления.
- 3Кто и когда узнаёт. Порог уведомления: пять записей в карантине за час либо любая запись, пролежавшая там дольше четырёх часов. Адресат — владелец интеграции по фамилии, а не общая почта отдела.
- 4За какой срок разбирается карантин. Один рабочий день. Срок нужен затем, чтобы карантин не превратился в кладбище: непроверяемое хранилище на 400 записей ничем не лучше их потери.
- 5Что считается критическим отказом. Обмен не проходит дольше двух часов подряд — это уже не сбой записи, а остановка процесса: менеджеры не видят заказов в учёте и начинают заводить их руками, создавая те самые дубли.
Схема из блоков со стрелками: «Сделка в статусе «Успешно»» → «Очередь обмена» → «Попытка 1 · сразу» → «Попытка 2 · через 5 мин» → «Попытка 3 · через 15 мин» → «1С:УТ: заказ покупателя». От третьей попытки вниз стрелка «Карантин: тело сообщения и причина», от карантина обратная стрелка к очереди с подписью «повтор одной кнопкой» и стрелка вбок «Уведомление владельцу: 5 записей за час или запись старше 4 часов». Отдельным блоком сбоку «Журнал обменов, хранение 90 дней». Внизу подпись: «нет обмена дольше 2 часов — критический отказ». Чертёжный стиль, подписи по-русски.
Проверять всё это заказчик должен уметь сам — иначе раздел останется декларацией. Простой приём: раз в месяц сверять число выигранных сделок в CRM с числом созданных заказов за тот же период. Расхождение в одну запись — повод открыть карантин. Полный порядок такой самостоятельной проверки на девяти сценариях мы описывали в статье о том, как убедиться, что интеграция работает.
Журнал, доступы и секреты
Три оставшихся раздела короткие, но именно они решают, можно ли будет разобрать спор через полгода и переживёт ли обмен увольнение сотрудника.
- 1Журналирование
Пишем: время, направление, идентификатор записи, результат, причину отказа, длительность. Не пишем: полное тело документа с персональными данными в открытом виде. Срок хранения — 90 дней; для обменов, связанных с деньгами, разумнее год. Отдельно фиксируется, кто имеет доступ к журналу.
- 2Доступы
Обмен работает под отдельной служебной учётной записью с правами только на нужные объекты: чтение сделок в CRM, создание и изменение заказов в учёте — и ничего больше. Именная учётная запись сотрудника для этого не используется никогда, даже временно на период отладки.
- 3Секреты
В самом документе не должно быть ни одного ключа, токена или пароля. В нём пишется только, где они лежат и кто выдаёт доступ: «токен API amoCRM — в менеджере паролей компании, раздел «Интеграции», доступ у Соколова и Ковалёвой». Требования к хранению и передаче доступов подрядчику разобраны на странице о безопасности и доступах.
Девятый раздел — владелец и порядок изменений — умещается в четыре строки: фамилия владельца интеграции со стороны заказчика, фамилия ответственного инженера, срок пересмотра документа и правило внесения изменений. Правило одно: любое изменение состава полей сначала вносится в документ и согласовывается, потом попадает в код. Порядок «сделали, потом допишем» не работает никогда — дописывать через две недели уже некому и незачем.
Что стоит отсутствие документа через год
Сначала цена самого паспорта. Собирается он один раз на связку, вместе с теми, кто работает с обеими системами.
Теперь типичный счёт за его отсутствие. Ситуация обычная: связку год назад делал сотрудник, который уволился; после обновления CRM поле скидки перестало приходить, заметили это на закрытии месяца.
Самая дорогая строка здесь не деньги, а 14 часов разбора кода. Из кода видно, что передаётся, но не видно, почему: было ли решение не передавать склад осознанным или просто забытым, кто согласовал трактовку пустой скидки как нуля, менялся ли ключ соответствия за год. Эти ответы существуют только в паспорте, и именно поэтому он входит в перечень документов, которые остаются у заказчика по итогам проекта — вместе с разделом об интеграциях в структуре ТЗ. Что ещё входит в «надёжный обмен» помимо передачи полей и сколько это стоит построчно, мы разбирали в статье про цену надёжной интеграции.
Столбчатая диаграмма из двух столбцов в рублях. Левый низкий столбец «Паспорт интеграции — 17 300 ₽» с тремя сегментами: 8 700, 5 800, 2 800 ₽. Правый высокий столбец «Восстановление через год — 115 116 ₽» с пятью сегментами: 40 600, 8 700, 16 640, 7 176, 42 000 ₽. Самый крупный сегмент правого столбца подписан «разбор кода и журналов, 14 часов». Между столбцами подпись «в 6,7 раза». Ось значений в рублях, все числа подписаны.
Когда паспорт интеграции избыточен
Документ на девять разделов рассчитан на обмен, который влияет на деньги и работает без человека. Не всякая связка такая.
- Обмен односторонний, одно-два поля и всё видно глазами. Уведомление о новой заявке в мессенджер описывается тремя строками: что за событие, куда уходит, что делать, если не ушло.
- Связка сделана готовым коннектором и не настраивается. Здесь достаточно записать, какой коннектор, кто его оплачивает, под какой учётной записью он работает и куда обращаться при сбое: состав полей задан вендором и вами не управляется.
- Пилот на две недели с ручной сверкой. На время проверки гипотезы паспорт правда избыточен — но ровно до решения оставить связку в работе. Это тот момент, когда документ пишется задним числом и всё ещё дёшево.
- Обмен внутри одной системы между её же модулями. Здесь роль паспорта выполняет документация конфигурации, дублировать её не нужно.
Во всех остальных случаях работает простой признак: если при остановке обмена кто-то в компании через час начнёт вводить данные руками — паспорт нужен. Полтора дня и 17 300 ₽ — это цена того, чтобы через год чинить связку по документу, а не методом подбора.
Код показывает, что передаётся. Почему именно так — знает только документ, и через год он единственный свидетель.
