Odoo API: как построить управляемую интеграцию с n8n, WMS, e-commerce и биллингом

Автор: команда PMOffice. Документация проверена 12 ноября 2026 года.

Odoo API позволяет внешним приложениям читать данные ERP и вызывать операции, которые создают или изменяют записи. Но успешный запрос ещё не означает, что интеграция готова к работе. Для обмена заказами, отгрузками и финансовыми документами необходимо понимать, какой документ передан, что с ним произошло и как восстановить процесс после сбоя.

Мы в PMOffice, как официальные партнёры Odoo, самостоятельно разрабатываем интеграционные решения. Наш опыт включает работу с n8n, WMS-операторами, e-commerce и системами учёта биллинга. Внутри Odoo мы создаём integration instance — слой управления обменом, в котором отслеживаются документы, их статусы, обработчики, причины ошибок и повторные попытки.

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

Что именно предоставляет Odoo API

API открывает программный доступ к моделям и методам Odoo. Контрагенты, заказы, складские и финансовые документы представлены разными моделями. Например, res.partner используется для партнёров, sale.order — для заказов продажи, stock.picking — для складских операций, account.move — для бухгалтерских документов. Набор доступных объектов зависит от установленных приложений и доработок.

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

Архитектуру моделей и операций описывает официальная документация ORM Odoo. Мы рекомендуем выполнять обмен через ORM и согласованные бизнес-методы, чтобы сохранять проверки, вычисления и связи документов. Прямая запись во внутренние таблицы базы требует отдельного обоснования и не должна быть обычным способом интеграции.

Сначала версия и размещение Odoo, затем протокол

XML-RPC и JSON-RPC — способы вызова удалённых процедур, а не версии самой Odoo. Выбор интерфейса зависит от версии сервера, возможностей клиента и планируемого срока эксплуатации решения.

Для новых подключений к Odoo 19 следует рассматривать также JSON-2. Поэтому вопрос «JSON-RPC или XML-RPC?» уже не охватывает все варианты.

Интерфейс	Адреса запросов	Практический выбор
XML-RPC	/xmlrpc/2/common и /xmlrpc/2/object	Существующие подключения и библиотеки, рассчитанные на этот интерфейс
JSON-RPC	/jsonrpc	Существующие клиенты с RPC-вызовами в JSON
JSON-2	/json/2/<model>/<method>	Новые подключения начиная с Odoo 19 при поддержке выбранным окружением

В актуальной документации External RPC API Odoo объявляет удаление прежних XML-RPC и JSON-RPC endpoints в Odoo 22, осенью 2028 года, и в Odoo Online 21.1, зимой 2027 года. Это опубликованный план, который необходимо перепроверять перед проектированием и обновлением. Предупреждение не относится автоматически ко всем пользовательским контроллерам JSON-RPC.

Поэтому для действующего обмена мы оцениваем миграцию, а для нового — сразу выбираем интерфейс с учётом жизненного цикла. Описание нового интерфейса: External JSON-2 API.

Отдельно проверяем тариф и размещение. В документации коммерческих планов Odoo внешний API доступен на Custom и недоступен на One App Free и Standard. Это условие нельзя механически переносить на самостоятельно развёрнутую Community: там нужно проверять конкретную установку и её интерфейсы.

Возможность использовать API также не означает возможность установить собственный серверный модуль. Odoo Online не поддерживает пользовательские модули. Если integration instance реализуется нашим Python-модулем внутри Odoo, требуется подходящее размещение: Odoo.sh или собственная инфраструктура с поддержкой таких модулей.

Как выдавать ключи на подключение к данным Odoo

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

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

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

Общий порядок создания API key:

1. Подготовить технического пользователя и его права.
2. Открыть Preferences / My Profile → Account Security → New API Key. Названия пунктов зависят от версии и языка интерфейса.
3. Указать понятное назначение: например, wms-production или n8n-staging.
4. Если интерфейс предлагает срок действия, задать его с учётом процедуры замены ключа.
5. Скопировать ключ при создании и сохранить в защищённом хранилище учётных данных.
6. Проверить чтение и запись на тестовом окружении, затем настроить контроль срока действия и отзыв доступа.

В документации Odoo 18 по API keys ключ используется вместо пароля, а логин остаётся частью авторизации RPC. Повторно посмотреть созданный ключ нельзя.

Для JSON-2 ключ передаётся в Authorization как bearer token. В разделе API Keys документации Odoo 19 описан срок до трёх месяцев для ручного создания ключа. Поэтому ротацию нужно включать в эксплуатационный процесс, проверяя правила конкретной версии.

Мы не сохраняем ключи в исходном коде, URL, текстах ошибок или журнале integration instance. Тестовые и рабочие подключения должны использовать разные секреты.

Первый запрос: чтение данных через JSON-2

Учебный пример для Odoo 19: прочитать до пяти компаний из res.partner. ODOO_URL, ODOO_DATABASE и ODOO_API_KEY предварительно задаются в окружении; настоящий ключ не следует вставлять в публикуемый код или историю команд.

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  -X POST "${ODOO_URL}/json/2/res.partner/search_read" \
  -H "Authorization: bearer ${ODOO_API_KEY}" \
  -H "X-Odoo-Database: ${ODOO_DATABASE}" \
  -H "Content-Type: application/json" \
  --data '{
    "domain": [["is_company", "=", true]],
    "fields": ["id", "name"],
    "limit": 5,
    "order": "id"
  }'

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

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

Запись данных: почему недостаточно вызвать create или write

Базовые операции ORM позволяют создавать записи и менять их поля. Но подтверждение заказа, проведение счёта или выполнение отгрузки включает бизнес-правила. Мы рекомендуем вызывать предусмотренные операции, а не подменять их прямой записью желаемого значения в state.

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

Это особенно важно из-за границ транзакций. В JSON-2 каждый вызов выполняется в собственной SQL-транзакции: несколько последовательных запросов не становятся одной общей транзакцией. Odoo рекомендует объединять связанные действия в одном методе. См. Transaction.

Однако даже единая транзакция Odoo не охватывает одновременно внешний магазин, WMS или биллинг. Для всей цепочки нужны подтверждения, сверка и восстановление после частичного выполнения.

Integration instance: как мы управляем обменом внутри Odoo

В нашей архитектуре instance — объект управления конкретной интеграцией внутри Odoo. Это наше обозначение разработанного слоя, а не обязательная стандартная сущность Odoo и не отдельный сервер.

Мы создаём его, чтобы связать техническую обработку с бизнес-документом. Внутри системы можно проследить документы и их статусы, определить обработчик, увидеть причину ошибки и историю повторов.

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

Что фиксируем	Для чего это нужно
Подключение, направление и тип операции	Понять источник и назначение обмена
Внешний ID и ссылка на документ Odoo	Сопоставить объекты двух систем
ID события и ключ идемпотентности	Распознать повторную доставку
Статус и ответственный обработчик	Определить текущий этап и владельца проблемы
История попыток и следующая попытка	Контролировать восстановление
Категория и причина ошибки	Выбрать правильное действие
Время и correlation ID	Найти событие в журналах всех участников

Конкретный состав полей зависит от проекта. Исходные сообщения и ответы сохраняются в объёме, необходимом для диагностики, с учётом чувствительных данных и срока хранения.

Полезно различать состояния «получено», «проверено», «ожидает обработки», «обработано», «ожидает подтверждения», «нужна повторная попытка» и «нужно вмешательство». Это пример проектируемой модели состояний: смешивать подтверждение доставки и завершение бизнес-операции в одном статусе нельзя.

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

Идемпотентность: что делать, если ответ потерялся

Рассмотрим учебную ситуацию. Внешний сервис передал заказ. Odoo создала документ, но ответ не дошёл до отправителя. Тот видит таймаут и повторяет запрос. Без защиты в ERP появляются два заказа.

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

Проверки «сначала найти, затем создать» недостаточно: два параллельных обработчика могут одновременно ничего не найти. Защита должна обеспечиваться атомарно, например ограничением уникальности и транзакционной обработкой конфликта. Произвольный заголовок Idempotency-Key не добавляет такую гарантию стандартному API: поддержку нужно реализовать в контракте решения.

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

Для исходящего обмена рекомендуем transactional outbox: бизнес-изменение и задание на отправку фиксируются вместе в базе Odoo, а внешний вызов выполняется отдельно. Это помогает избежать потери события между сохранением документа и отправкой, но всё равно требует защиты получателя от повторов.

Как мы используем n8n

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

Встроенный Odoo node в n8n поддерживает операции с контактами, возможностями CRM, заметками и пользовательскими ресурсами. Настройка credentials предусматривает адрес, пользователя, базу и ключ либо пароль.

Однако наличие узла не доказывает совместимость с любым интерфейсом Odoo. Для выбранного релиза n8n проверяем фактический протокол, авторизацию и обработку ошибок. Если встроенный узел не покрывает JSON-2 или предметный метод, рассматриваем HTTP Request с явно заданным контрактом.

Учебная схема входящего обмена: webhook магазина → проверка структуры в n8n → приём события интеграционным слоем Odoo → обработка → запись результата → подтверждение внешней системе.

Учебная схема исходящего: документ Odoo → задание на обмен → n8n → внешний сервис → сохранение результата в instance.

История выполнения workflow полезна разработчику. Но сотруднику, работающему с заказом в Odoo, нужен также понятный статус самого документа. Поэтому мы связываем идентификатор выполнения n8n с интеграционной операцией и определяем, какой компонент отвечает за повтор, чтобы две системы не запускали его одновременно.

Наш опыт: WMS, e-commerce и учёт биллинга

Наш опыт включает интеграции с WMS-операторами, e-commerce и системами учёта биллинга. Ниже — технические задачи этих направлений и учебные схемы обмена, без раскрытия клиентских данных.

WMS-операторы

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

Учебный сценарий: Odoo передаёт поручение на отгрузку, оператор подтверждает приём, затем возвращает результат комплектации и фактической отгрузки. Частичная отгрузка, недостача или замена партии требуют отдельной обработки. Принятый WMS запрос ещё не означает выполненную отгрузку.

E-commerce

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

Учебный сценарий: магазин передаёт заказ, Odoo создаёт документ, результат возвращается в магазин. События оплаты и отмены могут прийти позже или не по порядку, поэтому обрабатываются по согласованным переходам состояний. Бизнес-контекст разобран в статье Odoo для интернет-магазина.

Системы учёта биллинга

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

Учебный сценарий: биллинговая система передаёт начисление за период, Odoo проверяет договор, валюту и параметры учёта, после чего создаёт согласованный документ. Корректировка должна ссылаться на исходную операцию, а повтор сообщения не должен создавать новое начисление.

Когда мы рекомендуем RabbitMQ

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

Решение принимается по нагрузочным требованиям: объёму и размеру сообщений, пиковым поступлениям, времени обработки и допустимому отставанию. Универсального порога «после N документов» нет.

RabbitMQ отвечает за передачу сообщений, а instance — за связь с бизнес-документами и управление результатом. Одно дополняет другое.

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

В руководстве RabbitMQ по надёжности объясняется возможность повторной доставки. Publisher confirms и consumer acknowledgements подтверждают разные участки пути сообщения. Подтверждение брокера само по себе не означает, что Odoo завершила бизнес-операцию. Поэтому идемпотентность необходима и при использовании очереди.

Ошибки и восстановление: что должно быть предусмотрено

Ситуация	Рекомендуемое действие
Ключ недействителен или истёк	Проверить и заменить credentials, остановить бесполезные повторы
Не хватает прав	Проверить пользователя, компании и правила доступа
Неизвестный товар или неверные реквизиты	Направить на исправление данных
Таймаут после отправки	Установить результат по ID операции перед повтором
Временная недоступность	Повторить с задержкой и ограничением числа попыток
Событие пришло повторно или не по порядку	Проверить уникальность и допустимый переход состояния

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

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

Что проверить перед запуском интеграции

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

В критерии приёмки включаем измеримые требования: допустимое отставание, порядок сверки, действия при остановке и безопасный повтор. Именно эти условия превращают подключение к Odoo API в интеграционный процесс, который можно сопровождать.

При внедрении Odoo ERP мы рассматриваем API, обработчики, документы, статусы и восстановление как части одного решения. Внешняя система может меняться, но управляемость обмена должна сохраняться.

Частые вопросы

Что выбрать: JSON-RPC или XML-RPC?

Для существующего подключения — интерфейс, который поддерживает конкретная версия и клиент, с планом дальнейшей миграции. Для нового решения на Odoo 19 нужно оценить JSON-2 и объявленный срок удаления прежних RPC endpoints.

Можно ли подключить Odoo через n8n?

Да. Нужно проверить возможности узла и протокол, настроить credentials и определить правила обработки, повторов и фиксации результата в Odoo.

Нужен ли RabbitMQ для каждой интеграции?

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

Instance — стандартная возможность Odoo?

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