Kitworks Event Suite — повний гід з налаштування

Цей гід проходить весь шлях з нуля на чистій базі event19 з demo-даними. Усі скриншоти — реальні екрани локального стека Odoo 19.

0. Що це за система і кому вона потрібна

Kitworks Event Suite — це надбудова над модулем Events ядра Odoo, заточена під компанії, що регулярно проводять платні заходи з виїзним персоналом: екскурсійні бюро, тури, майстер-класи, виїзні лекції. Ключові відмінності від «голого» Odoo Events:

1. Які модулі встановити для якого функціоналу

Suite складається з ~34 опційних модулів kw_event_*. Встановлюйте не «усе підряд», а під потрібний функціонал — залежності підтягнуться автоматично. Нижче — групи за призначенням.

1.1 База (встановити завжди)

1.2 Ціни та квитки

1.3 Бюджет та аналітика

1.4 Гіди / виконавці та витрати

1.5 Логістика, формати, додаткове

2. Які довідники заповнити і в якому порядку

Порядок важливий: кожен наступний довідник посилається на попередній. Не можна зробити каталог без типу події, а тип події без продукту-квитка не дасть продавати.

3. Види витрат

Вид витрат (kw.event.expense) — це багаторазова категорія собівартості події: оренда автобуса, обід, вхідні квитки до музею. Кожен вид описує формулу вартості, продукт для обліку і одержувача оплати.

3.1 Поля виду витрат

3.2 Формула вартості

підсумок = fixed_cost + (person_cost × К-сть_учасників) + груповий_тариф + коригування
фінал    = max(підсумок, minimal_cost)

3.3 Три суми кожної витрати в події

Коли вид витрат потрапляє в подію (рядок kw.event.expense.line), система рахує три величини — вони ж видно у вкладці «Бюджет»:

3.4 Витрати на каталозі

У каталозі (kw.event.catalog.expense) перелічуються види витрат, які автоматично клонуються в кожну подію, створену з цього каталогу. Так ви один раз описуєте собівартість екскурсії, а далі вона зʼявляється в кожному виїзді.

4. Принципи розрахунку ставки гіда

Ставка гіда — це сума, яку компанія платить гіду за проведену екскурсію. Suite підтримує чотири способи розрахунку. Спосіб задається у вкладці «Performance fee» на контакті гіда (kw.event.performance.type.fee), а сума фіксується на події у вкладці «Виконавці» (kw.event.performance).

4.1 Як це працює на події

У вкладці «Виконавці» додаєте рядок: гід + тип виступу (Екскурсовод) + спосіб розрахунку. Система:

1. Бере ставку гіда з його довідника ставок.
2. Для фіксованих типів: сума = ставка × кількість (1 для per_event, години для per_hour).
3. Для %: відкладається до завершення події (бо потрібен підсумковий прибуток).
4. confirmed_amount («До сплати») = custom_amount (якщо вписали вручну) або розрахована сума.

4.2 Особливість «% від прибутку»

5. Тип події — за що відповідає кожне налаштування

Тип події (event.type) — це «профіль поведінки» події. Більшість налаштувань — це перемикачі-фічі: вмикаєш — зʼявляється вкладка/поле/логіка, вимикаєш — приховується (і відповідні записи не створюються).

5.1 Видимість вкладок (UI)

5.2 Формат і структура події

5.3 Квитки та ціни

5.4 Клієнт і бюджет

6. Створюємо екскурсію в каталозі

Практична частина. Створюємо каталог «Оглядова екскурсія Старим Києвом» — шаблон, з якого далі штампуватимемо конкретні виїзди.

7. Регулярна подія з каталогу

З каталогу створюємо регулярний виїзд на конкретну дату з авто-згенерованими квитками.

1На каталозі натисніть «Створити подію»

Відкривається майстер, попередньо заповнений із каталогу: каталог, Категорія = «Регулярна екскурсія», мова, набір квитків, запланована/мінімальна к-сть, гід. Лишається задати дату/час і місце початку.

2Подію створено — квитки згенерувались автоматично

Натисніть «Створити подію». Система створює event.event і з пресету каталогу сама генерує квитки з розрахованими цінами та вікнами продажу. Зверху — лічильники (Учасники, Оплати, Витрати), статуси «Новий → Зарезервовано → Оголошено → Закінчений», вкладки suite (Квитки, Зв'язок, Витрати, Запитання, Гонорари, Розрахунки з гідом, Маркетинг, Бюджет).

3Вкладка «Квитки»

Три типи квитків з пресету, ціни розраховані від базової 400 ₴: Повний 400 ₴, Пільговий 200 ₴ (−50%), Дитячий 0 ₴ (−100%). Вікна продажу: відкрито за 30 днів, закрито за 1 день до події.

8. Індивідуальна подія

Той самий каталог, але індивідуальний захід на замовлення (режим «є клієнт»).

1Створення з тим самим каталогом, але іншою категорією

У майстрі «Створити подію» змініть Категорію на «Індивідуальна екскурсія». Каталог один і той самий — змінюється лише тип події, а з ним і поведінка.

2Різниця: зʼявляється поле «Клієнт»

Оскільки тип «Індивідуальна екскурсія» має увімкнений прапор «Має клієнта», на події зʼявляється поле Клієнт — замовник заходу, якому виставлятимуть рахунок за весь тур (а не продаватимуть окремі квитки відвідувачам). Вкладка «Зв'язок» одразу містить автоматичні листи (підтвердження, нагадування за 1 год і за 3 дні) — це фіча «Показати вкладку Спілкування».

9. Як записувати людей і продавати квитки

Реєстрація учасників + продаж квитків + прийом оплати — все в одному майстрі «Запис/Квитки».

1Кнопка «Запис/Квитки» на події

Відкриває майстер продажу. Заповніть:

• Партнер — покупець (хто оплачує; для роздрібу можна загального).
• Прайс-лист — обовʼязковий.
• Кількості по типах квитків (напр. Повний ×3, Пільговий ×2).
• Тип оплати «Оплата гіду» + Куди сплачують — каса гіда, якщо гроші збирає гід на місці готівкою. Саме так надходження потрапляють у гаманець гіда для подальшого розрахунку.

3Бюджет одразу оновлюється

Вкладка «Бюджет» показує матрицю в трьох станах. Числа круглі, бо компанія без ПДВ:

• Заплановано (на 20 місць): дохід 8 000, витрати 3 700 (автобус 2 000 + вхідні 60×20 + гонорар 500), баланс +4 300.
• Записано (5 фактичних): дохід 1 600, витрати 2 800 (вхідні 60×5=300), баланс −1 200.
• Оплачено: 1 600 надійшло, баланс +1 600.

10. Концепція оплати гіду та взаєморозрахунок

Це найтонша частина. Ідея: гід має власний «гаманець» (каса), у який падають готівкові оплати з його екскурсій, і з якого оплачуються його витрати й гонорар. Після туру рахується, хто кому винен, і робиться один підсумковий переказ.

10.1 Гаманець гіда

Кожному гіду автоматично заводиться окрема каса («Готівка в <ім'я>») — щойно партнера позначено «Виконавець». Окремо її створювати не треба. Баланс каси = скільки готівки «на руках» у гіда. Позитивний — гід має нашу готівку; відʼємний — компанія винна гіду.

10.2 Вкладка «Розрахунки з гідом» (одна екскурсія)

На події вкладка показує чотири блоки:

Підсумок події:

net = Надходження − Винні_гіду − Раніше_переказано
Гід винен компанії = max(net, 0)
Компанія винна гіду = max(−net, 0)
Розраховано?        = усі «До сплати» = 0  І  net = 0

10.3 Взаєморозрахунок по кількох екскурсіях

Кнопка «Розрахувати» у списку подій відкриває майстер (kw.event.guide.multi.settlement.wizard), що зводить гіда одразу по кількох турах, пулячи його гаманець:

1. Обираєте гіда (зі списку гідів з касою).
2. Підтягуються всі нерозраховані тури цього гіда.
3. Кожен тур показує «гід винен компанії» або «компанія винна гіду»; галочкою обираєте, які звести.
4. Майстер рахує net по всіх обраних — прибуткова екскурсія перекриває збиткову.
5. По кожній події гасяться рахунки з гаманця, фіксується kw_settlement_transferred, і робиться один підсумковий переказ пулового net.

10.4 Кольори списку турів

11. REST API

Модуль kw_events_api дає REST-ендпоінти /kw_api/* для інтеграції із зовнішнім сайтом (WordPress/WooCommerce): створення подій, реєстрація учасників, продаж і оплата квитків. Автентифікація — токенна.

11.1 Автентифікація

Спершу отримуєте токен, далі передаєте його у заголовку Authorization: Bearer <token> (або access_token). Токен живе 24 год (налаштовується).

POST /kw_api/event_auth

// запит
{ "db": "event19", "login": "admin", "password": "admin" }

// відповідь
{ "status":"200", "result":"OK",
  "data": { "uid":2, "access_token":"abc123…", "expires_in":"2026-07-01 12:30:45" } }

11.2 Створення події

POST /kw_api/create_event  (потрібен токен)

Створює подію з каталогу. Ідемпотентно за ключем слоту (catalog_id, date_begin, date_end) — повторний виклик не плодить дублі.

curl -X POST https://HOST/kw_api/create_event \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "event_name": "Оглядова Старим Києвом — 15.08",
    "start_datetime": "2026-08-15T11:00:00",
    "end_datetime":   "2026-08-15T13:30:00",
    "catalog_id": 5,
    "seats_max": 25,
    "base_ticket_price": 400
  }'
// → { "data": { "event_id": 42 } }

11.3 Реєстрація / продаж квитків

POST /kw_api/create_registration

Створює один або кілька квитків-реєстрацій. Ідемпотентно за order (advisory-lock проти подвійного спрацювання). Кожен квиток — у власному savepoint.

curl -X POST https://HOST/kw_api/create_registration \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "event_id": 42,
    "order": "WP-2026-08-001",
    "tickets": [ { "ticket_id": 1, "price": 400 } ],
    "name": "Олена Коваль", "email": "olena@example.com",
    "phone": "+380501234567", "is_paid": true, "journal_id": 6, "payment_status": 2
  }'
// → { "data": { "event_id":42, "registrations":[123], "order":"WP-2026-08-001" } }

11.4 Інші ендпоінти

11.5 Формат відповіді

{
  "status":  "200",          // код HTTP рядком
  "result":  "OK",           // OK | error
  "error":   "",             // код помилки: auth_error | parameters_missing | validation_error
  "message": "",             // повідомлення для користувача
  "data":    { ... },        // корисне навантаження
  "count":   1               // к-сть полів у data
}

11.6 Повний приклад (Python)

import requests
BASE = "https://HOST"

# 1. токен
tok = requests.post(f"{BASE}/kw_api/event_auth",
    json={"db":"event19","login":"admin","password":"admin"}
).json()["data"]["access_token"]
H = {"Authorization": f"Bearer {tok}"}

# 2. подія
ev = requests.post(f"{BASE}/kw_api/create_event", headers=H, json={
    "event_name":"Оглядова Старим Києвом — 15.08",
    "start_datetime":"2026-08-15T11:00:00",
    "end_datetime":"2026-08-15T13:30:00",
    "catalog_id":5, "seats_max":25, "base_ticket_price":400
}).json()["data"]["event_id"]

# 3. продаж квитка + оплата
requests.post(f"{BASE}/kw_api/create_registration", headers=H, json={
    "event_id":ev, "order":"WP-2026-08-001",
    "tickets":[{"ticket_id":1,"price":400}],
    "name":"Олена Коваль","email":"olena@example.com",
    "is_paid":True,"journal_id":6,"payment_status":2
})