В Odoo зберігаються дані, від яких залежить більшість бізнес-запитань: клієнти, замовлення, залишки, рахунки, оплати. AI-асистент, що може читати ці дані й діяти з ними, відповідає на «Де замовлення клієнта Х?» чи «Які рахунки прострочені понад 60 днів?» за секунди, а не за хвилини кліків. Починаючи з Odoo 19, найчистіший спосіб підключити такого асистента — новий JSON-2 API. У статті показуємо архітектуру, яку ми використовуємо: автентифікація, окремий інтеграційний користувач, дизайн інструментів, доступ до Odoo через Model Context Protocol і запобіжники, що не дають агенту наробити шкоди.

Чому варто будувати на JSON-2

В Odoo 19 з'явився зовнішній JSON-2 API: ви надсилаєте POST із JSON-тілом на /json/2/<model>/<method> з API-ключем як bearer-токеном і отримуєте результат методу в JSON (Odoo: external JSON-2 API). Старі ендпоінти XML-RPC і JSON-RPC (/xmlrpc, /xmlrpc/2, /jsonrpc) оголошені застарілими й будуть видалені в Odoo 22 восени 2028 року (Odoo: external RPC API). Нові інтеграції варто одразу будувати на JSON-2.

Два практичні наслідки:

  • Плануйте ліцензування. Доступ до зовнішнього API є лише в тарифах Custom, а не в One App Free чи Standard. Тарифи розбираємо у статті Odoo Community чи Enterprise.
  • Плануйте оновлення. Якщо ви на Odoo 17 чи 18 з інтеграціями на RPC, їхній перехід на JSON-2 — частина наступного проєкту оновлення.

Автентифікація: API-ключі та окремий користувач

JSON-2 використовує API-ключі в заголовку Authorization. Ключі створюються для користувача в Налаштування → Безпека облікового запису → Новий API-ключ, вимагають опису і строку дії та не можуть діяти довше трьох місяців — тож довготривалі інтеграції мусять їх ротувати (Odoo: API keys). Odoo також надає методи для програмної генерації та відкликання ключів, що дозволяє автоматизувати ротацію.

Ключ діє з правами свого користувача. Це найважливіше архітектурне рішення:

  • Створіть окремого інтеграційного користувача для агента лише з потрібними групами доступу — наприклад, читання продажів і складу, без доступу до зарплати чи налаштувань бухгалтерії.
  • Для асистентів, що працюють з користувачами, діяйте від імені реального користувача, де можливо: асистент менеджера з продажів має бачити рівно те, що бачить менеджер. Спільні ключі «суперкористувача» перетворюють кожну prompt injection на витік даних.
  • Використовуйте правила записів (record rules), щоб обмежити, які записи бачить інтеграційний користувач, — наприклад, лише одну компанію в мультикомпанійній конфігурації.

Мінімальний виклик JSON-2

import requests

ODOO = "https://erp.example.com"
HEADERS = {
    "Authorization": f"bearer {API_KEY}",
    "X-Odoo-Database": "prod",
    "Content-Type": "application/json",
}

def odoo(model: str, method: str, **params):
    r = requests.post(f"{ODOO}/json/2/{model}/{method}",
                      json=params, headers=HEADERS, timeout=20)
    r.raise_for_status()
    return r.json()

overdue = odoo("account.move", "search_read",
    domain=[["move_type", "=", "out_invoice"],
            ["payment_state", "in", ["not_paid", "partial"]],
            ["invoice_date_due", "<", "2026-07-25"]],
    fields=["name", "partner_id", "amount_residual", "invoice_date_due"],
    limit=50)

Кожна база також має сторінку /doc з переліком моделей, полів і методів, доступних саме в цій інсталяції, — корисно, коли пишете описи інструментів для кастомізованих баз.

Дизайн інструментів для агента

Не давайте моделі універсальний інструмент «виклич будь-який метод Odoo». Обгорніть API невеликим набором інструментів, орієнтованих на задачі, з чіткими описами, вузькими параметрами і компактними результатами:

Інструмент Виклики Odoo за ним Примітки
find_customer(query) res.partner search_read за назвою, email, ЄДРПОУ Повертає id, назву, email, менеджера, кредитний ліміт
get_order_status(order_ref) sale.order + пов'язані відвантаження і рахунки Поєднує три моделі в одну відповідь
stock_level(product, warehouse) Згрупований запит до stock.quant Доступна і зарезервована кількість
overdue_invoices(customer_id?) account.move search_read Обмежені поля, сортування за строком оплати
draft_quotation(customer_id, lines) sale.order create у стані чернетки Інструмент запису: лише чернетка, підтверджує людина

Правила, що роблять інструменти надійними:

  1. Спершу інструменти читання, інструменти запису — пізніше і лише після аналізу логів реального використання.
  2. Запис створює чернетки. Агент може підготувати комерційну пропозицію, замовлення постачальнику чи лист; підтвердження, проведення чи надсилання залишаються за людиною.
  3. Перевіряйте аргументи на сервері, а не лише в схемі інструмента.
  4. Повертайте бізнес-мову. payment_state: "partial" годиться для коду; інструмент може перекласти це для моделі як «частково оплачено».

Доступ до Odoo через MCP

Якщо Odoo потрібен кільком AI-застосункам — чат-асистенту для продажів, внутрішньому агенту для фінансів, асистенту для розробників, — обгорніть ці інструменти MCP-сервером замість того, щоб будувати їх заново для кожного застосунку. Тоді будь-який MCP-сумісний host користуватиметься тими самими інструментами з однаковими правами і логуванням. Протокол, дизайн сервера та його модель безпеки описані у статті MCP для бізнесу.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("odoo")

@mcp.tool()
def get_order_status(order_ref: str) -> dict:
    """Status of a sales order by its reference (e.g. S00042): order state,
    delivery status with carrier tracking, and invoice/payment status."""
    order = odoo("sale.order", "search_read",
                 domain=[["name", "=", order_ref]],
                 fields=["state", "partner_id", "picking_ids", "invoice_ids"], limit=1)
    if not order:
        return {"error": f"No order {order_ref}. Check the reference format S00000."}
    return summarize_order(order[0])   # поєднує відвантаження і рахунки в компактний dict

Сценарії, що окупаються першими

  • Асистент продажів: статус замовлення, наявність на складі, історія клієнта і чернетки комерційних пропозицій з листа.
  • Робота з дебіторкою: прострочені рахунки за клієнтами із запропонованими листами-нагадуваннями, які переглядає бухгалтер.
  • Закупівлі: товари нижче точки дозамовлення з чернетками замовлень, згрупованими за постачальниками.
  • Підтримка: статус замовлення і доставки для операторів у поєднанні з відповідями з бази знань через пошук, як описано у статті RAG-системи для бізнесу.
  • Запитання керівництва: «Виручка за категоріями товарів цього кварталу порівняно з минулим» через згруповані запити лише на читання.

Запобіжники

  • Мінімальні привілеї для інтеграційного користувача через групи і правила записів Odoo.
  • Підтвердження людиною для всього, що проводиться, підтверджується, надсилається чи оплачується.
  • Аудит-лог кожного виклику інструмента з користувачем, аргументами і розміром результату.
  • Ліміти й таймаути, щоб цикл агента не перевантажив воркери Odoo, — див. Оптимізація продуктивності Odoo.
  • Пам'ятайте про prompt injection: листи клієнтів, нотатки й описи товарів — недовірений текст. Наш чек-лист — у статті Безпека AI-агентів.
  • Ротація ключів: автоматизуйте оновлення до закінчення тримісячного строку і негайно відкликайте ключі, коли інтеграцію виводять з експлуатації.

Як виміряти, чи допомагає асистент

Ставтеся до інтеграції як до будь-якої продуктової функції і міряйте її з першого тижня пілоту:

  • Частка успішних задач: скільки запитань отримали правильну відповідь чи скільки дій підготовлено без виправлень — перевіряється на вибірці залогованих сесій.
  • Зекономлений час: наприклад, скільки хвилин займала відповідь на запитання про статус замовлення до і після.
  • Частка помилок інструментів: невдалі чи повторені виклики на сесію — часто ознака нечітких описів інструментів або відсутніх прав.
  • Частка виправлень чернеток людиною: як часто комерційні пропозиції чи замовлення постачальникам, підготовлені агентом, потребують змін перед підтвердженням.
  • Навантаження на Odoo: кількість API-викликів за хвилину і час відповіді, щоб асистент не сповільнював користувачів.

Як зібрати тестовий набір із реальних запитань — у статті Як оцінювати LLM-застосунки.

FAQ

Чи працює це з Odoo 17 або 18? Ці версії використовують XML-RPC чи JSON-RPC для зовнішнього доступу. Архітектура та сама, відрізняється транспорт, а на JSON-2 ви перейдете під час оновлення.

Чи можна натомість використовувати вбудовані AI-функції Odoo? Новіші версії Odoo мають вбудовані AI-можливості в тарифах Custom. Вони добре підходять усередині екранів Odoo; зовнішній агент має сенс, коли ви поєднуєте Odoo з іншими системами або потребуєте власних процесів.

Чи безпечно дозволяти AI створювати записи в ERP? Так — через чернетки і підтвердження. Агент готує, людина затверджує.

Скільки триває інтеграція? Асистент лише для читання з п'ятьма-шістьма інструментами зазвичай займає два-чотири тижні, включно з інтеграційним користувачем, логуванням і тестуванням на реальних запитаннях.

Джерела

  1. Odoo. External JSON-2 API.
  2. Odoo. External RPC API (застарілий).
  3. Odoo. Ціни.
  4. Model Context Protocol. Специфікація, ревізія 2026-07-28.
  5. OWASP. Secrets Management Cheat Sheet.