Техническое задание на интеграцию должно описывать не только передачу полей, но и события, идентификаторы, повторы и восстановление после ошибок. Укажите, какая система владеет каждым значением и как подтверждается результат. Тогда исполнитель сможет построить проверяемый обмен, а поддержка — восстановить его без догадок.
Опишите деловые события
Начните с перечня изменений: обращение принято, заказ обновлён, платёж подтверждён, заказ отменён. Для каждого укажите источник, получателя, время и ожидаемый эффект. Не заменяйте смысл события технической фразой «синхронизировать карточку», если разные изменения требуют разного поведения.
Уточните границы проекта. Какие объекты передаются, какие остаются вне обмена, что происходит вручную? У каждого исключения должен быть владелец. Общую структуру требований можно связать с техническим заданием на CRM, но контракт интеграции требует отдельного внимания к доставке и повторной обработке.
Согласуйте поля и идентификаторы
В карте данных укажите тип, обязательность, допустимые значения, пустое состояние и источник истины. Для дат задайте формат и часовой пояс, для сумм — валюту и правила округления. Не позволяйте неизвестному значению превращаться в ноль без явного основания.
Разделите идентификатор объекта и идентификатор события. Один заказ может изменяться много раз; каждое изменение нуждается в собственном ключе или версии. Сохраните соответствие идентификаторов между системами. Название клиента или товара недостаточно надёжно для восстановления связей после переименования.
Определите поведение повторов
Идемпотентность означает, что повторная обработка одного события не создаёт дополнительного нежелательного эффекта. Это требование нужно реализовать и проверить, а не считать свойством любого API. Укажите срок и способ хранения признака обработки, а также ответ на повтор.
Условный пример: система отправила событие создания заказа, получатель создал запись, но подтверждение потерялось. Отправитель повторяет запрос. По тому же идентификатору должен находиться уже обработанный результат, если таков согласованный контракт. Новое событие изменения этого заказа, напротив, должно примениться. Проверка только одинакового содержимого не всегда различает эти ситуации.
Учтите порядок и конфликты
Обновления могут приходить с задержкой. Если старая версия суммы поступила после новой, нужно правило, которое не вернёт устаревшее значение. Укажите номер версии, источник времени или другой согласованный механизм сравнения. Для конфликтов между ручной правкой и внешним обновлением определите приоритет.
Отдельно опишите временную недоступность, ограничение частоты запросов и ошибку данных. Для временного отказа обычно нужен контролируемый повтор, для неверного справочника — разбор и исправление. Не отправляйте проблемное событие бесконечно без видимого состояния: очередь должна показывать причину остановки и ответственного.
Сделайте восстановление наблюдаемым
Журнал должен связывать событие, попытку, результат и созданный объект. Сохраняйте достаточно сведений для диагностики, не записывая секреты и лишние персональные данные. Определите, как найти все события периода сбоя и повторить только необходимые.
В инструкции восстановления укажите проверку уже выполненных действий, порядок запуска и сверку итогов. Для связанной цепочки важно учитывать частичный успех: заказ мог создаться, а товарные строки — нет. Повтор должен дополнять согласованное состояние или корректно компенсировать ошибку, а не размножать объекты.
Примите обмен по сценариям
Минимальный набор включает успешное событие, повтор, неверное поле, недоступность получателя, изменение порядка и восстановление накопленной очереди. Для каждого заранее рассчитайте ожидаемые объекты, суммы и связи. Сохраните протокол вместе с версией контракта.
Критерии приёмки: идентификаторы прослеживаются; данные соответствуют карте; повторы безопасны; конфликты разрешаются; ошибки видимы; восстановление проверено. При обмене с учётной системой дополните набор вопросами по CRM и 1С, чтобы техническая доставка сохраняла деловой смысл заказа и оплаты.
Применить в вашей компании
Обсудим вашу задачу?
Поможем разобраться с процессом, данными и настройками. Работаем удалённо с компаниями по всей России.