Очень немногие компании работают в одной-единственной системе. Даже когда Odoo является основной ERP, ему обычно приходится взаимодействовать с платёжным шлюзом, службой доставки, банком, интернет-магазином, терминалом учёта рабочего времени или унаследованным приложением. Качество этих связей определяет, можно ли доверять вашим данным или команда будет каждый месяц вручную сверять расхождения.
Odoo 19 Enterprise предлагает многоуровневый набор инструментов: встроенные коннекторы, настраиваемые из приложений, внешний API для разработчиков, правила автоматизации, способные принимать и отправлять вебхуки, и импорт файлов для случаев, когда прямое подключение невозможно. Промежуточное ПО надстраивается над ними, когда нужна оркестрация между множеством систем.
Об источниках: статья основана на официальной документации Odoo для версии 19.0 (репозиторий odoo/documentation). Меню, параметры и условия тарифов могут различаться в зависимости от версии и типа размещения, поэтому всегда проверяйте каждый шаг в тестовой базе данных или её копии, прежде чем применять его в рабочей среде.
Выберите подходящую схему интеграции
Отталкивайтесь от потребности бизнеса, а не от технологии. Выясните, какие данные должны передаваться, в каком направлении, как быстро и кто владеет главной записью. Затем выберите самый лёгкий вариант, удовлетворяющий потребность.
- Используйте встроенный коннектор, если Odoo уже поддерживает поставщика услуги, например платёжного провайдера из списка, службу доставки, провайдера синхронизации с банком или коннектор Amazon.
- Используйте внешний API, когда другому приложению нужно читать или записывать записи Odoo по собственному расписанию.
- Используйте входящий вебхук, когда внешняя система должна передать событие в Odoo в момент его возникновения.
- Используйте исходящий вебхук, когда Odoo должен уведомить другую систему после изменения, например при создании записи или обновлении поля.
- Используйте промежуточное ПО, когда задействовано несколько систем, когда данные требуют сложного преобразования или когда нужны централизованные повторные попытки и мониторинг.
- Используйте импорт файлов, когда другая сторона предоставляет только файлы, например банковские выписки в форматах CAMT.053, OFX, QIF, CSV или XLSX.
Внешний API в Odoo 19: JSON-2 и ключи API
В Odoo 19 появился API JSON-2, который открывает часть ORM через HTTP. Каждый вызов — это POST-запрос к конечной точке вида /json/2/, за которой следуют имя модели и имя метода, например метод search_read модели res.partner. Тело запроса передаёт аргументы метода в формате JSON.
Аутентификация выполняется с помощью ключа API, передаваемого в заголовке Authorization как токен bearer. Отдельного шага входа с ID пользователя и паролем нет, поэтому ключ идентифицирует пользователя, и интеграция действует с правами доступа этого пользователя.
Чтобы создать ключ вручную, откройте настройки своего пользователя, перейдите в раздел «Безопасность учётной записи» и выберите «Новый ключ API». Описание и срок действия обязательны, а значение ключа показывается только один раз, поэтому сразу сохраните его в защищённом хранилище секретов. В документации указано, что ключи нельзя создавать на срок более трёх месяцев, поэтому с самого начала запланируйте порядок их ротации.
Если на одном сервере размещено несколько баз данных, необязательный заголовок X-Odoo-Database сообщает Odoo, к какой базе данных относится вызов. При работе за обратным прокси убедитесь, что заголовок Host правильно доходит до Odoo.
Каждый вызов JSON-2 выполняется в собственной транзакции базы данных: при успехе она фиксируется, при ошибке откатывается. Объединить несколько вызовов в одну транзакцию нельзя, поэтому предпочитайте один метод, выполняющий всю связанную работу, например search_read или бизнес-метод, вместо множества мелких вызовов, которые могут оставить данные обновлёнными наполовину.
Ошибки возвращаются с HTTP-статусом 4xx или 5xx и телом JSON, содержащим имя и сообщение. Клиентский код должен считывать и журналировать оба значения.
Устаревшие XML-RPC и JSON-RPC: спланируйте переход
Многие существующие интеграции используют старые конечные точки XML-RPC или конечную точку JSON-RPC. В Odoo 19 они объявлены устаревшими, и в официальной документации сказано, что их планируется удалить в Odoo 22. Сегодня они ещё работают, но новые проекты следует строить на JSON-2, а существующие — включить в перечень и перенести в рамках дорожной карты обновлений.
- Составьте перечень всех скриптов, коннекторов и сторонних инструментов, обращающихся к старым конечным точкам.
- Замените аутентификацию по логину и паролю отдельными ключами API для каждой интеграции.
- По возможности переделайте многошаговые последовательности в одиночные вызовы, учитывая принцип «одна транзакция на вызов».
- Протестируйте перенесённую версию на копии базы данных, прежде чем переключать на неё рабочий трафик.
Важна и доступность в рамках тарифа. В документации указано, что доступ к данным через внешний API есть только на тарифах «Индивидуальный», но не на тарифах «Одно приложение бесплатно» или «Стандартный». Проверьте свою подписку, прежде чем проектировать интеграцию через API в Odoo Online.
Вебхуки и правила автоматизации
Правила автоматизации позволяют Odoo реагировать на события без собственных модулей. В Odoo 19 Enterprise ими управляют из Studio через меню «Автоматизации», а для входящих вебхуков в Studio есть отдельный пункт «Вебхуки». Режим разработчика даёт больше контроля, в том числе возможность выбрать целевую модель.
Для входящего вебхука создайте правило с триггером «При вебхуке». Odoo автоматически генерирует URL; внешняя система отправляет на этот URL POST-запрос с полезной нагрузкой в формате JSON. Код целевой записи сообщает Odoo, к какой записи относится полезная нагрузка, а вкладка «Действия к выполнению» определяет, что произойдёт дальше; как правило, это действие «Выполнить код», если нужно создавать записи, а не обновлять одну.
На этапе разработки и диагностики включите «Журналировать вызовы». Этот параметр сохраняет историю запросов к URL, которую можно открыть смарт-кнопкой «Журналы» в правиле.
Относитесь к URL вебхука как к секрету. Документация предупреждает, что его разглашение может дать непредусмотренный доступ к базе данных. Если URL скомпрометирован, воспользуйтесь функцией «Сменить секрет», чтобы сгенерировать новый URL, и обновите его во внешней системе.
Для исходящих уведомлений добавьте в правило действие «Отправить уведомление вебхука». Оно отправляет на указанный URL POST-запрос со значениями выбранных полей, а пример полезной нагрузки помогает проверить структуру до запуска.
При написании действий «Выполнить код» используйте функцию log для записи сообщений в таблицу журнала базы данных, чтобы сбои были видны функциональным пользователям, а не только в журналах сервера.
Studio входит в Odoo Enterprise. В Community интерфейса Studio нет, поэтому те же потребности обычно закрываются настройкой в режиме разработчика или небольшими собственными модулями, которые сопровождает разработчик.
Встроенные коннекторы для типовых интеграций
Прежде чем писать код, проверьте, не поддерживает ли Odoo уже нужного поставщика. Встроенные коннекторы обновляются с каждым выпуском и обычно являются самым безопасным выбором.
- Платёжные шлюзы: настраиваются в меню «Настройка» → «Платёжные провайдеры» в приложениях «Бухгалтерия», «Сайт» или «Продажи». В списке провайдеров есть Stripe, Adyen, PayPal, Paymob, Mollie, Razorpay и другие. Введите учётные данные на вкладке «Учётные данные» и сначала используйте тестовый режим с учётными данными песочницы, желательно в копии базы данных, чтобы не нарушить нумерацию счетов. Платёжный журнал должен иметь тип «Банк».
- Службы доставки: включаются в настройках приложения «Склад» в разделе «Коннекторы доставки». Среди поддерживаемых коннекторов — DHL Express, FedEx, UPS, Sendcloud, EasyPost и другие. Каждый способ доставки начинает работу в тестовой среде; переключение в рабочую среду создаёт реальные этикетки, за которые служба доставки может выставить счёт, поэтому сначала проверьте тарифы и этикетки. Параметр «Отладка запросов» журналирует передаваемые сообщения.
- Банки: синхронизация с банком импортирует операции через сторонних провайдеров, таких как Plaid, Yodlee, Salt Edge, Ponto, Enable Banking и Basiq, и требует действующей подписки Enterprise. Если ваш банк не поддерживается, импортируйте файлы выписок из банковского журнала на панели «Бухгалтерии».
- Электронная коммерция и маркетплейсы: собственное приложение Odoo «Интернет-магазин» работает в той же базе данных, поэтому коннектор не нужен. Для Amazon коннектор Amazon Connector синхронизирует заказы в заказы на продажу и сопоставляет товары по внутреннему артикулу.
- Терминалы учёта рабочего времени: приложение «Посещаемость» поддерживает режим киоска на выделенном устройстве и отметку из бэкенда. Биометрические терминалы других производителей в официальной документации не описаны, поэтому их обычно подключают через собственный модуль или промежуточное ПО, передающее отметки в Odoo.
Промежуточное ПО, например n8n
Платформы промежуточного ПО, такие как n8n, располагаются между Odoo и другими системами. Это сторонние инструменты, не входящие в Odoo, и они взаимодействуют с Odoo через тот же внешний API и вебхуки, о которых говорилось выше.
Они полезны, когда одно событие должно обновить несколько систем, когда сопоставление полей сложное или когда нужен визуальный процесс с централизованной обработкой ошибок и повторными попытками. Обратная сторона — ещё один компонент, который нужно размещать, защищать, отслеживать и обновлять, а условия тарифов для доступа к API по-прежнему действуют.
Принципы проектирования: идемпотентность, обработка ошибок и журналирование
Большинство проблем интеграции возникает из-за повторных сообщений, частичных сбоев и незаметных ошибок. Учитывайте их с первого дня.
- Делайте каждую запись идемпотентной: храните внешний идентификатор в записи Odoo и проверяйте его перед созданием, чтобы повторно отправленный вебхук или повторный вызов не создал дубликат заказа или платежа.
- Определите, какая система владеет каждым полем, и никогда не позволяйте двум системам перезаписывать одно и то же значение.
- По возможности выполняйте одну бизнес-операцию одним вызовом, поскольку каждый вызов JSON-2 — отдельная транзакция.
- Повторяйте попытки только при временных сбоях, с увеличивающимися интервалами, а постоянные сбои направляйте в очередь на разбор.
- Журналируйте запрос, ответ и ссылку на запись Odoo для каждого обмена с помощью «Журналировать вызовы», «Отладки запросов» или истории вашего промежуточного ПО.
- В первые недели ежедневно отслеживайте объёмы и сбои и сверяйте итоги, такие как платежи, отгрузки и банковские остатки, между системами.
Контрольный список безопасности
- Создайте отдельного пользователя для интеграции только с теми правами доступа, которые ей нужны, и сгенерируйте ключ API от имени этого пользователя.
- Используйте по одному ключу на интеграцию, указывайте его назначение в описании, выбирайте короткий срок действия и меняйте ключ до истечения срока.
- Храните ключи и URL вебхуков в менеджере секретов, а не в электронных таблицах, сообщениях чатов или исходном коде.
- Немедленно отзывайте ключи и меняйте секреты вебхуков при прекращении отношений с поставщиком или подозрении на утечку.
- Всегда используйте HTTPS, а каждую интеграцию разрабатывайте и тестируйте на копии базы данных, прежде чем включать её в рабочей среде.
Чем может помочь 1CBMS
1CBMS проектирует и внедряет интеграции Odoo 19 для компаний в Египте и Ираке: от настройки платёжных провайдеров, служб доставки и банковских каналов до создания интеграций через API JSON-2 и вебхуки, переноса устаревших скриптов XML-RPC и подключения терминалов учёта рабочего времени и внутренних систем через собственные модули или промежуточное ПО. Мы начинаем с карты владения данными и потоков, тестируем всё на копии базы данных и передаём понятную документацию и мониторинг, чтобы ваша команда могла доверять цифрам. Свяжитесь с нами через www.1cbms.com, чтобы проанализировать вашу интеграционную среду.