# Як інтегрувати ConnectiveOne з Odoo CRM

> **Важливо:** інтеграцію з Odoo CRM (модуль, iframe, webhooks) **розробляє IT-команда клієнта**. ConnectiveOne надає публічні інструкції та стандартні механізми (autologin, `event_webhook_url`); **не входить** в імплементаційну оцінку ConnectiveOne.

Цей документ описує типові способи інтеграції ConnectiveOne з Odoo CRM: вбудовування операторської панелі, webhook-події, синхронізація контактів і лідів. Підходить для команди, яка розробляє Odoo-модуль на боці клієнта.

## Що можна інтегрувати

| Можливість | Напрям | Документація |
|------------|--------|--------------|
| Операторська панель у картці контакта / ліда | Odoo → ConnectiveOne (iframe + autologin) | [Віджет ОП в Odoo](./integrate-operator-panel-as-widget-odoo.md) |
| Події чату (створення, підключення оператора, закриття) | ConnectiveOne → Odoo (webhook) | [Webhook панелі оператора](../webhook/configure-operator-panel-webhook.md) |
| Створення / оновлення ліда з бота | ConnectiveOne → Odoo (XML-RPC / JSON-RPC) | Цей документ, § «Ліди та контакти» |
| Передача custom fields у CRM | Двостороння через сценарій + API Odoo | § «Custom fields» |
| Повідомлення в Discuss | Зазвичай **не** дублюють — рекомендовано embed ОП | [Пояснення](#чому-embed-а-не-discuss) |

---

## Архітектура (рекомендована)

```mermaid
flowchart LR
  subgraph Odoo["Odoo CRM"]
    Partner["res.partner / crm.lead"]
    Iframe["iframe ОП"]
    WebhookCtrl["HTTP controller<br/>/connectiveone/events"]
  end
  subgraph CO["ConnectiveOne"]
    Bot["Бот / сценарій"]
    OP["Operator Panel"]
    AJ["Action Jail"]
  end
  Partner --> Iframe
  Iframe -->|"autologin"| OP
  Bot --> OP
  OP -->|"event_webhook_url"| WebhookCtrl
  AJ -->|"XML-RPC"| Partner
```

**Принцип:** діалоги та маршрутизація залишаються в ConnectiveOne; Odoo — CRM-картка, activity та довідники менеджерів.

---

## Крок 1. Вбудовування операторської панелі

Детальна інструкція: [Як інтегрувати операторську панель як віджет у Odoo CRM](./integrate-operator-panel-as-widget-odoo.md).

Коротко:

1. Збіг email менеджера в Odoo та ConnectiveOne.
2. `login_key` для autologin — у secure storage Odoo.
3. Вкладка з iframe у `res.partner` / `crm.lead`.
4. URL формується на **сервері** Odoo з телефоном клієнта.

---

## Крок 2. Webhook подій операторської панелі в Odoo

### Налаштування в ConnectiveOne

У action `operator_panel__connect_to_operator_with_msg` вкажіть URL контролера Odoo:

```json
{
  "auto_connect_operator": true,
  "subject_alias": "support",
  "event_webhook_url": "https://your-odoo.example.com/connectiveone/events"
}
```

Повний перелік подій і формат тіла — у [налаштуванні webhook](../webhook/configure-operator-panel-webhook.md).

### Приклад контролера Odoo (Python)

```python
# controllers/connectiveone_webhook.py
from odoo import http
from odoo.http import request
import json
import logging

_logger = logging.getLogger(__name__)

class ConnectiveOneWebhook(http.Controller):

    @http.route("/connectiveone/events", type="json", auth="public", methods=["POST"], csrf=False)
    def receive_event(self, **kwargs):
        # Рекомендується: перевірка підпису / IP allowlist
        data = request.jsonrequest
        event_name = data.get("event_name")
        client = data.get("client") or {}
        phone = client.get("phone")
        partner = False
        if phone:
            partner = request.env["res.partner"].sudo().search([
                "|", ("phone", "ilike", phone[-9:]),
                ("mobile", "ilike", phone[-9:]),
            ], limit=1)

        if event_name == "chat_created" and partner:
            partner.activity_schedule(
                "mail.mail_activity_data_todo",
                summary="Новий чат ConnectiveOne",
                note=data.get("text", ""),
            )
        elif event_name == "chat_closed_by_operator" and partner:
            partner.message_post(body="Чат ConnectiveOne закрито оператором")

        return {"status": "ok"}
```

> Для production додайте **автентифікацію** (shared secret у header, VPN або mTLS).

### Типові події для CRM

| Подія | Рекомендована дія в Odoo |
|-------|--------------------------|
| `chat_created` | Activity на partner / lead |
| `operator_connected` | Повідомлення в chatter |
| `chat_closed_by_operator` | Закрити activity, оновити стадію |
| `chat_transferred_to_operator` | Перепризначити responsible (опційно) |

---

## Крок 3. Ліди та контакти з бота

### Створення ліда через Odoo External API

З Action Jail або сценарію ConnectiveOne викличте [Odoo External API](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html):

```javascript
// Приклад у custom action (псевдокод)
const xmlrpc = require("xmlrpc");
// authenticate → execute_kw('crm.lead', 'create', [{ name, phone, description }])
```

**Рекомендовані поля ліда:**

| Поле Odoo | Джерело в боті |
|-----------|----------------|
| `name` | Ім'я клієнта або тема звернення |
| `phone` / `mobile` | Константа сценарію |
| `description` | Текст звернення / продукт |
| `user_id` | Відповідальний менеджер (якщо відомий) |
| `tag_ids` | Джерело каналу (Telegram, Viber) |

### Пошук менеджера за клієнтом

Перед підключенням оператора можна в Odoo знайти `res.partner` за телефоном і прочитати `user_id` (відповідальний) — передати в custom fields ConnectiveOne для assign.

---

## Крок 4. Custom fields і ідентифікатори

Зберігайте зв'язок між системами в custom fields:

| ConnectiveOne (клієнт OP) | Odoo |
|---------------------------|------|
| `external_id` / phone | `res.partner.id` |
| Custom field `odoo_partner_id` | ID партнера |
| `chat_room_id` | Поле на partner (опційно) |

Це дозволяє відкривати правильний діалог з iframe та оновлювати ту саму картку з webhook.

---

## Крок 5. Налаштування System Parameters в Odoo

| Ключ | Приклад | Опис |
|------|---------|------|
| `connectiveone.instance_url` | `https://company.connectiveone.io` | Базовий URL |
| `connectiveone.login_key` | *(secret)* | Autologin |
| `connectiveone.default_bot_id` | `12` | Бот для `init_dialog` |
| `connectiveone.default_channel` | `telegram` | Канал за замовчуванням |
| `connectiveone.webhook_secret` | *(secret)* | Перевірка webhook |

---

## Чому embed, а не Discuss

Дублювання переписки в Odoo Discuss потребує повної синхронізації повідомлень, вкладень і маршрутизації. Це дорожче в підтримці та гірше збігається з skill groups ConnectiveOne.

**Рекомендація:** iframe операторської панелі + webhook для статусів і activity.

---

## Чекліст впровадження

- [ ] Користувачі Odoo = оператори ConnectiveOne (email)
- [ ] Autologin URL тестується на staging
- [ ] iframe відображається в form view partner / lead
- [ ] Webhook endpoint приймає `chat_created` і створює activity
- [ ] (Опційно) Action Jail створює `crm.lead` при зверненні з бота
- [ ] CSP / cookies перевірені в production браузерах
- [ ] Секрети не в репозиторії Odoo-модуля

---

## Обмеження

- Odoo Online може обмежувати custom controllers — перевірте план хостингу
- Autologin потребує актуального `login_key`
- Webhook URL має бути доступний з серверів ConnectiveOne
- Двостороння синхронізація всіх повідомлень — окремий великий scope

## Пов'язані статті

- [Віджет операторської панелі в Odoo](./integrate-operator-panel-as-widget-odoo.md)
- [Інтеграція ОП як віджету (загальна)](./integrate-operator-panel-as-widget.md)
- [Webhook панелі оператора](../webhook/configure-operator-panel-webhook.md)
- [Інтеграція через Custom Channel](../custom-channel/integrate-via-custom-channel.md)
- [Що таке інтеграції](../../explanation/what-are-integrations.md)