Интеграция OpenCart и Vendus: разработка сервиса синхронизации

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

С такой задачей к IPWAY обратилась международная компания, которая работает одновременно через физический магазин и интернет-магазин на OpenCart. Для обслуживания платежных терминалов и связанных операций заказчик использовал сервис Vendus.

В августе 2023 года для клиента был разработан отдельный сервис двусторонней синхронизации. Решение написано на Python, развернуто на виртуальном сервере заказчика и дополнено Telegram-ботом для ручного управления обменом.

Исходная задача

У заказчика существовали две самостоятельные системы:

• интернет-магазин на OpenCart;
• сервис Vendus, используемый в контуре физической торговли и платежных терминалов.

Без интеграции изменения приходилось переносить между системами вручную или контролировать раздельно. По мере роста каталога такой подход создавал несколько проблем:

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

Требовалось создать отдельный сервис, который автоматически получает данные из одной системы, преобразует их в нужный формат и передает в другую.

Почему потребовалась двусторонняя синхронизация

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

Она сложнее односторонней, поскольку необходимо определить:

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

Как была построена архитектура сервиса

Интеграцию реализовали не внутри одной из систем, а в виде отдельного сервиса-посредника. Такой подход позволяет изолировать логику преобразования данных и изменять ее без глубокой переработки OpenCart или Vendus.

                  ┌────────────────────┐
                  │     OpenCart       │
                  │ Интернет-магазин   │
                  └─────────┬──────────┘
                            │
                     получение данных
                            │
                            ▼
             ┌────────────────────────────┐
             │ Сервис синхронизации       │
             │                            │
             │ • получение изменений      │
             │ • сопоставление объектов   │
             │ • преобразование полей     │
             │ • проверка данных          │
             │ • передача изменений       │
             │ • журналирование           │
             └──────────────┬─────────────┘
                            │
                     передача данных
                            │
                            ▼
                  ┌────────────────────┐
                  │       Vendus       │
                  │ Внешняя система    │
                  └────────────────────┘

             Управление и отчеты
                      │
                      ▼
              ┌─────────────────┐
              │  Telegram-бот   │
              └─────────────────┘

Как читать схему

Сервис синхронизации обращается к обеим системам, получает доступные изменения и приводит данные к внутреннему формату. После проверки они преобразуются в структуру принимающей системы и отправляются через предусмотренный интерфейс обмена.

Telegram-бот не участвует непосредственно в преобразовании данных. Он служит интерфейсом управления: через него пользователь может вручную запустить полную или частичную синхронизацию и получить отчет о выполненной операции.

Почему использован отдельный сервис

Размещение интеграционной логики в отдельном компоненте дает несколько преимуществ:

• системы остаются менее зависимыми друг от друга;
• ошибка интеграции не требует изменять основную логику интернет-магазина;
• проще вести отдельный журнал обмена;
• можно независимо обновлять сервис;
• удобнее выполнять повторную обработку;
• можно масштабировать сервис отдельно от OpenCart;
• проще перенести интеграцию на другой сервер.

Недостаток подхода — появление дополнительного компонента, который необходимо обновлять, резервировать и контролировать.

Преобразование и сопоставление данных

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

Даже если две системы хранят сведения об одном бизнес-объекте, они могут по-разному описывать:

• идентификаторы;
• названия и описания;
• категории;
• варианты и характеристики;
• единицы измерения;
• налоговые параметры;
• статусы;
• даты изменения;
• обязательные поля;
• связи между объектами.

Таблица соответствий

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

Внутренняя модель данных

Чтобы не связывать преобразование напрямую с форматами двух систем, сервис может использовать промежуточную модель:

Данные OpenCart
       │
       ▼
Преобразование во внутреннюю модель
       │
       ├── проверка обязательных значений
       ├── нормализация форматов
       ├── сопоставление идентификаторов
       └── применение бизнес-правил
       │
       ▼
Преобразование в формат Vendus

Как читать схему

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

Такая модель упрощает сопровождение. Если формат одной системы изменится, корректируется соответствующий преобразователь, а не весь процесс обмена.

Сопоставление идентификаторов

Одна запись может иметь разные внутренние идентификаторы в OpenCart и Vendus. Поэтому сервису требуется хранить связь между ними.

Для каждого сопоставленного объекта полезно фиксировать:

• идентификатор в OpenCart;
• идентификатор в Vendus;
• дату последней успешной синхронизации;
• направление последнего изменения;
• контрольную версию или признак изменения;
• результат последней обработки;
• описание ошибки, если обмен не завершен.

Полная и частичная синхронизация

В проекте предусмотрены два режима ручного запуска через Telegram-бота: полная и частичная синхронизация.

Полная синхронизация

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

Он может понадобиться:

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

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

Частичная синхронизация

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

Преимущества такого режима:

• меньше обращений к API;
• быстрее завершается операция;
• снижается нагрузка на системы;
• проще повторить обработку после ошибки;
• меньше риск перезаписать данные, которые не изменялись.

Как избежать повторной обработки

Интеграционный сервис должен распознавать уже обработанные изменения. Иначе одна и та же запись будет передаваться при каждом запуске.

Для этого применяют один или несколько признаков:

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

Конкретный механизм зависит от возможностей обеих систем и правил проекта.

Обработка ошибок и контроль результата

Интеграция работает с двумя внешними системами и сетью, поэтому ошибки неизбежны. Сервис должен не только зафиксировать сбой, но и позволить безопасно повторить операцию.

Какие ошибки необходимо учитывать

• недоступность одной из систем;
• истечение или отзыв учетных данных;
• ограничение количества запросов;
• изменение формата ответа;
• отсутствие обязательного поля;
• неизвестный идентификатор;
• конфликт изменений;
• ошибка преобразования значения;
• частичное выполнение пакетной операции;
• тайм-аут соединения;
• повторная отправка одного объекта;
• нехватка ресурсов сервера.

Безопасный повтор

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

Поэтому повторная обработка должна учитывать:

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

Журнал синхронизации

Для каждой операции полезно сохранять:

Отчеты через Telegram-бота

Разработанный для заказчика Telegram-бот позволяет:

• запускать полную синхронизацию;
• запускать частичную синхронизацию;
• получать отчеты о синхронизированных товарах.

При использовании мессенджера в качестве административного интерфейса необходимо ограничить список пользователей и не передавать через сообщения пароли, токены API и полные конфиденциальные данные.

Размещение сервиса на Linux VPS

Сервис был написан на Python и развернут на виртуальном сервере заказчика. Тестирование и отладка выполнялись на Linux VPS IPWAY с Ubuntu.

Отдельный сервер позволяет изолировать интеграцию от интернет-магазина и управлять ее ресурсами независимо.

Что требуется интеграционному серверу

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

Хранение секретов

Ключи API, пароли и токен Telegram-бота не следует размещать непосредственно в исходном коде или передавать через репозиторий.

Для них необходимо предусмотреть:

• отдельное хранилище или защищенные переменные окружения;
• ограниченные права на чтение;
• разные учетные данные для тестовой и рабочей среды;
• периодическую замену;
• отзыв при увольнении ответственного сотрудника;
• исключение секретов из журналов ошибок.

Мониторинг

Нужно контролировать не только доступность VPS, но и работу самого сервиса:

• запущен ли процесс;
• когда завершилась последняя успешная синхронизация;
• сколько объектов ожидает обработки;
• растет ли число ошибок;
• как изменилась длительность операции;
• доступны ли OpenCart и Vendus;
• достаточно ли свободного места;
• доставляются ли отчеты Telegram-бота.

Резервное копирование

Состав резервной копии определяется архитектурой сервиса. Обычно необходимо сохранять:

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

Секреты можно резервировать только в защищенном виде и с ограниченным доступом.

Как тестировалась интеграция

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

Основные сценарии тестирования

1. Первичная синхронизация. Передача предусмотренного набора данных в пустую или подготовленную среду.
2. Изменение в OpenCart. Проверка появления изменения во второй системе.
3. Изменение в Vendus. Проверка обратного направления.
4. Повторный запуск. Убеждение, что обработанные записи не дублируются.
5. Неполные данные. Проверка обязательных полей и понятности ошибки.
6. Недоступность системы. Контроль повторных попыток и сохранения очереди.
7. Конфликт изменений. Проверка заранее определенного правила приоритета.
8. Большой объем. Измерение длительности и нагрузки.
9. Перезапуск сервера. Проверка автоматического восстановления сервиса.
10. Telegram-бот. Проверка прав пользователей, запуска режимов и отчетов.

Тестовая и рабочая среды

Отладку безопаснее выполнять на копиях данных и отдельных учетных записях. Рабочие токены и реальные операции не следует использовать до проверки сценариев на тестовом контуре.

Перед запуском в рабочей среде необходимо:

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

Заключение

В рамках проекта для международной торговой компании был создан отдельный сервис двусторонней синхронизации OpenCart и Vendus. Решение разработано на Python, развернуто на виртуальном сервере заказчика и дополнено Telegram-ботом для ручного запуска обмена и получения отчетов.

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

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

Что почитать дальше

• VPS для сайта: полное руководство — когда сайту и связанным сервисам требуется отдельный виртуальный сервер.
• Как выбрать VPS — процессор, память, диски, сеть и масштабирование.
• Почему нельзя экономить на безопасности VPS — обновления, доступ, резервное копирование и защита серверных приложений.
• Как интеграция с amoCRM создала нагрузку на PostgreSQL — практический пример диагностики интеграционного сервиса и базы данных.

Когда стоит обратиться к специалистам

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

Для размещения интеграционных сервисов IPWAY предоставляет Linux VPS. Конфигурацию можно подобрать с учетом языка разработки, числа запросов, объема служебных данных и требований к резервному копированию.

Кратко

• Проект реализован для компании с физическим и интернет-магазином.
• Интернет-магазин работал на OpenCart, второй системой был Vendus.
• Для проекта выбрана двусторонняя синхронизация.
• Основная сложность заключалась в преобразовании структур данных.
• Сервис разработан на Python.
• Решение развернуто на виртуальном сервере заказчика.
• Тестирование выполнялось на Linux VPS с Ubuntu.
• Telegram-бот позволяет запускать полную и частичную синхронизацию.
• Бот также предоставляет отчеты о синхронизированных товарах.
• Интеграционный сервис необходимо отдельно защищать, резервировать и контролировать.