Интеграция ломается редко в момент демонстрации. Она ломается позже: повторная отправка создаёт дубль, в одной системе меняется реквизит, API временно недоступен, пользователь отменяет заказ после частичной оплаты. Поэтому проектировать нужно не только «счастливый путь».
- Определить источник истины по каждой сущности
- Проектировать повторяемость и антидубли
- Добавить журнал, retry и алерты до запуска
Сначала карта сущностей
Опишите не методы API, а бизнес‑объекты: компания, контакт, товар, заказ, счёт, оплата, отгрузка. Для каждого укажите, где он создаётся и какая система имеет право менять ключевые поля.
| Сущность | Источник истины | Что передаём в другую систему |
|---|---|---|
| Контрагент | Определяется процессом | ID, реквизиты, контактные данные |
| Товар/цена | Обычно учётная система | Номенклатура, цена, остаток при необходимости |
| Сделка/лид | Обычно CRM | Клиент, состав, стадия продаж |
| Оплата | Учётная система | Сумма, дата, статус |
Один внешний ID лучше поиска «по названию»
После первой синхронизации сохраняйте устойчивую связь объектов между системами. Названия, телефоны и реквизиты могут меняться; внешний идентификатор должен оставаться связующим ключом. Поиск по названию годится только как часть первичного сопоставления.
Повторная отправка не должна создавать дубль
Любая интеграция должна безопасно переживать повтор. Сеть может оборваться после того, как принимающая сторона уже сохранила объект, но отправитель не получил ответ. Если повторный запрос создаёт вторую сущность, рано или поздно база загрязнится.
Практическое правило: каждый обмен должен иметь idempotency‑логику — повтор одного события приводит к тому же состоянию, а не к новому объекту.
Очередь и retry вместо «попробовали — не получилось»
Временная ошибка 1С, API или сети — нормальная ситуация. Событие нужно поставить в очередь, повторить по политике retry и только после нескольких неудач переводить в ручной разбор.
- Фиксируем время, тип события и ID объекта
- Храним статус попытки и текст ошибки
- Повторяем автоматически с увеличением интервала
- Даём оператору кнопку безопасного повтора
Тестируйте не только создание заказа
Перед запуском соберите матрицу сценариев. Обязательные случаи — изменение реквизитов, отмена, частичная оплата, повторная отправка, недоступность одной системы, неизвестный товар, дубль клиента.
- Создание и обновление
- Отмена и возврат
- Частичная/полная оплата
- Несколько заказов одного клиента
- Ошибка связи и восстановление
- Ручное изменение в обеих системах
Мониторинг: что смотреть после запуска
Здоровая интеграция имеет технический журнал и бизнес‑контроль. Технический показывает ошибки обмена, бизнес‑контроль — расхождения, которые важны пользователю: заказ в CRM оплачен, а статус не обновился.
| Контроль | Сигнал | Действие |
|---|---|---|
| Очередь | Событие долго не обработано | Алерт + retry |
| Ошибки | Рост одинаковой ошибки | Разбор причины/релиз |
| Сверка | Количество/сумма не сходятся | Отчёт расхождений |
| Latency | Обмен стал медленнее нормы | Проверка нагрузки/API |
Перед тем как закрыть задачу
- ✓Есть карта сущностей и источник истины
- ✓Есть устойчивые внешние ID
- ✓Повторы не создают дубли
- ✓Есть очередь и повторная отправка
- ✓Есть журнал ошибок и алерты
- ✓Есть тест‑матрица исключений
Интеграция считается законченной не когда данные один раз успешно передались, а когда команда понимает, как увидеть ошибку, повторить обмен и доказать, что системы снова согласованы.
