> Усі статті WIKI Helomi: /wiki/llms.txt

# Kasta

Інтеграція з Kasta приймає замовлення маркетплейсу Kasta в «Угоди» за офіційним API постачальника і передає назад на Kasta статус замовлення та ТТН. Підключається одним натиском: ввести токен і натиснути «Підключити Kasta». ТТН для замовлень Kasta створюються лише через кабінет hub.kasta.ua — для цього є окрема картка «Kasta hub» у «Перевізниках».

## Можливості
- Потік змін замовлень Kasta: CRM читає його за курсором, перше опитування — замовлення за останні два дні (старіших Kasta не віддає).
- Угода з назвою = № замовлення Kasta, клієнт за телефоном, позиції за артикулом постачальника, доставка службою «Kasta».
- «Пов'язані статуси»: статус Kasta → етап угоди.
- «Передавати статус і ТТН на Kasta»: менеджер рухає угоду — статус на Kasta змінюється сам, з ТТН угоди на кроці «Зареєстровано у кур'єрській службі».
- Блок «Kasta» в картці угоди: статус замовлення, статус доставки, запит покупця на відміну, історія, кнопки дій.
- Кілька магазинів Kasta зі своїми токенами.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Kasta» → вкладка «Підключення».

1. Рядок «API токен» → «Ввести» → вставте токен → «Зберегти ключ». Токен береться в кабінеті Kasta: «Налаштування → Загальні → API». Зберігається зашифрованим, показуються лише останні символи.
2. «Перевірити» читає одне замовлення з потоку Kasta (лише читання).
3. Рядок «Потік замовлень» показує «читається · останній раз …» або «ще не почато». «Почати заново» скидає курсор (якщо щось пішло не так).
4. Вкладка «Налаштування продажів»: «Основне» («Увімкнути інтеграцію», «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Пов'язані статуси» з перемикачем «Передавати статус і ТТН на Kasta», «Фід для маркетплейсу» («Фід каналу з прайс-листа» `/feed/channel/kasta.xml` — його з 14.10 читає ШІ Єлизавета замість фіду KeepinCRM: залишки — зі складу Helomi, ціни — з прайс-листа; і фід усього складу). Блоку «Автоматична відправка ТТН» тут нема: ТТН Kasta — лише через hub.kasta.ua. Блок «Передача ТТН на маркетплейс» — статуси, після яких ТТН приймається (типово «Упаковано»), і «спершу перевести»: в угоді «⋮» рядка ТТН → «Передати ТТН на Kasta» = статус «Зареєстровано у кур'єрській службі» з номером; бракує «Підтверджено»/«Упаковано» — Helomi передає їх першими (як блок «Kasta» в угоді).
5. Для ТТН підключіть картку «Kasta hub» у вкладці «Перевізники» ([стаття](int-kasta-hub.md)). ТТН, уже створену в кабінеті hub.kasta.ua вручну, записують в угоду так: блок «Доставка» → «вручну» (або «+» → «Додати ТТН») → номер → «Записати ТТН». Номер лягає в наявний рядок доставки Kasta з замовлення (другого рядка не буде), далі статус оновлюється сам, і ТТН можна передати на Kasta.

Дані замовлення пишуться в додаткові поля угоди (`kasta_order_id` та інші); поля налаштовуються в «Налаштування → Типи даних → Угоди». Юрособа угод Kasta — правилом «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити одним натиском
1. Введіть «API токен».
2. Рядок «Одним натиском» → «Підключити Kasta» → підтвердіть.
3. CRM ставить налаштування як у KeepinCRM: джерело «Kasta», головний відповідальний, товари за артикулом, пов'язані статуси (воронка «Продажі Каста»: Необроблені, Передано на збірку, Зібрано, Відправлено; воронка «Продажі»: Отримано, Угода скасована), статус і ТТН назад на Kasta; потім вмикає приймання і робить перше опитування.
4. Під кнопкою — що застосовано і що пропущено (наприклад, етапу з такою назвою нема). Пропущене допишіть вручну в «Пов'язаних статусах».

Набір «одним натиском» узято з компанії власника. Повторно — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Kasta в KeepinCRM, інакше замовлення прийдуть двічі.

## 3. Приймати замовлення в угоди
Коли інтеграцію ввімкнено, CRM кожні 5 хвилин читає потік змін. Статус замовлення береться з його історії (Створено → Підтверджено → Упаковано → Зареєстровано у кур'єрській службі → Доставлено; або Відмінено). Нове замовлення стає угодою на етапі з «Пов'язаних статусів»; повтор оновлює статус і, якщо статус є в мапі, рухає угоду. Справжній перевізник посилки записується в поле угоди, а служба доставки — «Kasta». Що сталося — «Стан роботи» і «Журнал подій» картки.

«Адреса доставки» угоди: Нова Пошта — як дає Kasta («Київ, Відділення №88 (до 30 кг): вул. …»), Укрпошта — «Київ, 01001, просп. …, 4» (індекс окремо, не в дужках).

## 4. Статус і ТТН назад на Kasta
Увімкніть «Передавати статус і ТТН на Kasta» у «Пов'язаних статусах». Коли менеджер переводить угоду на етап з мапи:
- пропущені проміжні «Підтверджено» й «Упаковано» CRM надішле сама («Упаковано» — з позиціями й сумою);
- на «Зареєстровано у кур'єрській службі» — з ТТН угоди;
- «Відмінено» — з причиною зі списку Kasta.

Помилки Kasta пишуться в журнал картки людською мовою.

## 5. Блок «Kasta» в угоді
У картці угоди з Kasta є блок «Kasta»: статус замовлення пігулкою, статус доставки, запит покупця на відміну (червоним), історія статусів. Дії: «Підтвердити», «Упаковано», «Передати ТТН» (з полем номера), «Відмінити…» з «Причиною відміни», «Оновити». Якщо бракує проміжних статусів, кнопка підказує, що саме буде передано першим.

Над ним — блок «Kasta (<джерело>)» з даними замовлення: ID, «Сума замовлення», «Статус замовлення», «Історія статусу замовлення», «Спосіб оплати», «Статус оплати» («Оплачено» карткою на Kasta, «Післяплата», «Очікує оплати»), «ТТН», «Спосіб доставки» (Нова Пошта / Укрпошта), отримувач, телефон, «Адреса доставки», «Вартість доставки», «Коментар». Назва блоку й ID — посилання на замовлення в кабінеті hub.kasta.ua: поки посилку не відправлено — вкладка «Нові» (`hub.kasta.ua/customer-orders/new?order=…`), далі — «Відправлені» (`…/sent?order=…`). Номер замовлення в заголовку блоку «Kasta» теж відкриває його в кабінеті. Коли блок «Kasta» відкривається, свіжі дані замовлення одразу лягають в угоду (поля блоку, джерело вітрини, ТТН і статус посилки) — етап при цьому не рухається. «?» у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі.

## 6. Другий магазин Kasta (акаунти)
Картка «Kasta» → «Підключення» → «Акаунти» → «+ Додати акаунт» → «Назва» і «API токен» → «Додати акаунт». Новий акаунт вимкнений: перевірте токен і ввімкніть (або «Підключити Kasta» в його картці). У акаунта свої токен, потік, налаштування продажів і журнал.

## 7. Укрпошта Маркет і доставка Укрпоштою (22.10)
«Укрпошта Маркет» (маркетплейс у застосунку Укрпошти) працює через Kasta: продавець — той самий кабінет hub.kasta.ua, замовлення приходять тим самим потоком, статуси й ТТН — як у звичайної Kasta. Щоб продажі рахувались окремо, такі угоди отримують своє джерело. Його обирають у картці «Kasta» → «Налаштування продажів» → «Основне» → «Джерело «Укрпошта Маркет»»; типово — джерело з назвою «Укрпошта Маркет» (великі й малі літери не важливі), а якщо його нема — створюється. Угода, яку вже прийняли з джерелом «Kasta», переходить на джерело вітрини при наступній зміні замовлення або коли відкрити блок «Kasta»; джерело, яке людина змінила вручну, не чіпається. У блоці «Kasta» в угоді вітрину видно жовтою пігулкою «Укрпошта Маркет».

Kasta возить і Укрпоштою. ТТН для таких замовлень, як і раніше, створюється лише в кабінеті hub.kasta.ua; Helomi сам бере номер із замовлення в рядок ТТН угоди. Хто везе, видно за номером: ШК Укрпошти — 13 цифр (`0505737109865`), ЕН Нової Пошти — 14. У списку угод і в блоці «Доставка» стоїть перевізник («УП» / «НП») і статус посилки, а не «Kasta». Статус оновлює трекінг тієї служби (для Укрпошти потрібен токен відстеження в картці «Укрпошта» у «Перевізниках»); поки служба статусу не дала, у рядку ТТН — статус від самої Kasta («Створено, не відправлено», «Відправлено», «Прибув у відділення», «Доставлено»). Статус служби, щойно він є, головніший — Kasta його не перетирає.

## Усі замовлення, не лише нові (14.10)
Приймання читає потік змін Kasta від збереженого курсора; «Вивантажити замовлення» за N днів у картці каналу скидає курсор і читає потік заново від дати (повтор не дублює).

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Kasta у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Kasta» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Kasta» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: 25 % від суми угоди. Виплата Kasta на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Kasta ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «Транзит · Kasta», дохід — коли угода виграна (усі угоди: Kasta сама доставляє й збирає гроші), комісія 21,6 % одразу при замовленні з «Баланс · Kasta» (кабінет) — це звірка; витрата на Kasta — передоплата гарантійного рахунку (списання «kastaua_3pl» — «Комісія Каста», власник 21.10). Виплати «ФК «Артуа»» і бонуси «Маркасон» (опис містить «kastaua_3pl») — переказ із транзиту сам, «комiсiя N грн» з призначення — «Комісія Каста». Розрахункові 21,6 % щодня (і кнопкою «Підтягнути з API за 7 днів» у шторці правила каналу) замінює реальна комісія з «Звіту по транзакціях рахунку» Kasta (колонка «Гарантійний рахунок, роялті» по кожному замовленню); поповнення гарантійного рахунку, штрафи й виплати бонусів — у підсумку як «інше». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): KASTA_API_TOKEN» | Токен не введено | «Підключення» → «API токен» → «Ввести» |
| «Нема токена Kasta в картці інтеграції» | Дія в угоді без токена | Введіть токен у картці Kasta |
| «Угода не з Kasta (нема номера замовлення Kasta)» | В угоді нема `kasta_order_id` | Дія доступна лише для угод з Kasta |
| «В угоді нема ТТН — створіть ТТН (блок «Доставка») і передайте ще раз» | «Передати ТТН» без номера | Створіть ТТН через hub.kasta.ua і повторіть |
| «Доставлене замовлення відмінити не можна — оформіть повернення на Kasta» | Замовлення вже доставлено | Оформіть повернення в кабінеті Kasta |
| «Замовлення вже відмінено на Kasta» | Повторна відміна | Нічого робити не треба |
| «Kasta: ТТН створюються лише через кабінет hub.kasta.ua (служба «kasta»)» | Для Kasta вибрано іншу службу ТТН | Оберіть службу «Kasta (hub.kasta.ua)» |
| Замовлення прийшло двічі | Kasta ще підключена до KeepinCRM | Вимкніть Kasta в KeepinCRM |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Kasta», додаткове поле `kasta_order_id` і акаунт, з якого прийшла угода (`crm_integration`). Кнопок блоку «Kasta» в інструментах нема — статус на Kasta міняє людина або етап угоди за мапою. Статтю ШІ читає інструментом `help("int-kasta")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Kasta hub](int-kasta-hub.md), [Доставки і ТТН](shipping.md).