skills/westudy/references/course-tariffs.md

# Тарифи курсу та склад матеріалів

## Команди

| Команда | Призначення |
| --- | --- |
| get_course_tariffs | Прочитати всі тарифи, їхні налаштування, валюту, платність і прапорець тарифного режиму. |
| create_course_tariff | Створити один тариф за revision списку. |
| update_course_tariff | Змінити лише передані налаштування одного тарифу за revision цього тарифу. |
| get_course_tariff_materials | Прочитати матеріали всіх типів, їхні батьківські розділи й явні прив’язки до тарифів. Без дизайну та студентів. |
| update_course_tariff_materials | Додати або прибрати один тариф для вибраних матеріалів, зберігаючи всі інші прив’язки. |

Працюй із курсами нової версії підключеної школи. Курс шукай через search_courses,
UUID тарифів і матеріалів бери з відповідей. За неоднозначної назви уточни вибір.
Читання потребує courses:read, запис — courses:write. Нового дозволу на тарифи немає.
Недостатні права пояснюй за загальними правилами навички; не обходь їх іншими API.

## Платність і тарифний режим

Спочатку get_course. Зміна isPaid/hasPaymentPlans — через update_course за revision
налаштувань курсу, не через редагування тарифу. У create_course ці прапорці також доступні.

- Безкоштовний курс: isPaid=false. Ціна курсу очищається, тарифний режим вимикається.
  Тарифні сутності, їхні ціни й прив’язки матеріалів зберігаються. Студенти не видаляються.
- Платний із однією ціною: isPaid=true, hasPaymentPlans=false, додатна ціла price.
  При вимкненні тарифів можна використати вже наявну додатну ціну курсу; якщо її немає,
  потрібна задана користувачем ціна. Не вигадуй її.
- Платний із тарифами: isPaid=true, hasPaymentPlans=true. Не передавай price,
  hasAccessRules/accessDays курсу: їх налаштовують окремо для кожного тарифу.
  Безкоштовний варіант усередині тарифного курсу — тариф із isFree=true.
- Вимкнення тарифного режиму не видаляє тарифів і не очищає склад матеріалів;
  повторне ввімкнення використовує збережені прив’язки.

Для вже активного курсу поясни, що зміна режиму діє одразу. У тарифному режимі
студенту потрібен призначений тариф; ці команди не призначають і не змінюють його.
Не обіцяй, що всі поточні студенти автоматично отримають новий тариф.
Якщо користувач хоче запровадити нові тарифи, спочатку підготуй тарифи та їхній склад,
потім увімкни режим за дорученням. Не вмикай його лише через створення одного тарифу.
Це дозволяє налаштувати тарифні сутності до активації; публікація курсу не змінюється.

## Налаштування тарифу

lang — мова назви й опису; типово мова курсу. Це не зміна основної мови курсу.
Якщо не просять переклад, зберігай мову курсу. Інші переклади не перезаписуються.

settings: name (1–255 символів), description (до 1000, null очищає), price, isFree,
isHidden, hasAccessRules, accessDays, limitCertificates, productId (до 500, null очищає).
Непередані поля залишаються. limitCertificates — наявне обмеження сертифікатів тарифу;
воно не створює, не видає й не редагує дизайн сертифіката.

Для платного тарифу потрібна додатна ціла price у повернутій currency, у звичайних
одиницях платформи; не множ на 100. Для нового безкоштовного тарифу достатньо
isFree=true — збережеться технічна price=0. Зміна наявного тарифу на безкоштовний
не обов’язково очищає його попередню ціну: isFree визначає оплату, ціна може
залишатися неактивною. При поверненні до платного перевір ціну й намір користувача.
За hasAccessRules=true потрібні додатні accessDays. hasAccessRules=false вимикає
обмеження; accessDays=null явно очищає збережену тривалість.

Для створення: get_course_tariffs → create_course_tariff із revision всього списку.
Перед створенням наступного тарифу перечитай список. Для редагування використовуй
revision вибраного items[]. Не підставляй revision списку, курсу або іншого тарифу.
Однакова назва не означає оновлення: create завжди створює окремий тариф.

Тариф не має чернетки: ціна, видимість, тривалість і обмеження діють одразу,
незалежно від publish_course. Перед записом коротко назви курс, тариф і запитану
зміну. Чітке доручення вже є дозволом; повторне підтвердження не потрібне.
Видалення тарифів недоступне. Якщо треба приховати тариф, поясни дію isHidden=true;
не називай це видаленням і не змінюй цим студентські тарифи.

## Матеріали тарифів

get_course_tariff_materials повертає tariffs та items із elementUuid, name, type,
parentUuid, isPublished, tariffUuids. Це явна таблиця прив’язок, не повна перевірка
студентського доступу: на доступ також впливають публікація, розклад та інші правила.
При ввімкнених тарифах студентський перелік відбирає матеріали з прив’язкою до
тарифу студента. Порожній tariffUuids не означає «входить у всі тарифи».
Щоб матеріал входив у всі тарифи, додай кожен потрібний тариф окремо.

update_course_tariff_materials:

- courseUuid, tariffUuid, requestId, expectedRevision з get_course_tariff_materials;
- elementUuids — 1–200 різних UUID за виклик;
- included=true додає цей тариф, false прибирає лише його;
- includeDescendants=true застосовує дію також до всіх вкладених матеріалів
  вибраних розділів, включно з вкладеними розділами, як прапорець у платформі.
  false або відсутнє поле змінює лише явно передані UUID.

Для «включи весь розділ» використовуй includeDescendants=true. Для одного уроку
не змінюй інші уроки. Перевір тарифні прив’язки всіх батьківських розділів:
вкладений матеріал без потрібного розділу може не з’явитися в студентському переліку.
Батьківські розділи автоматично не додаються; за потреби коротко поясни проблему
й узгодь розширення складу, якщо воно не входить у доручення.

Прив’язки можна змінювати для наявних test/certificate та інших типів, навіть якщо
їхній контент ще не підтримується командами редагування. Шаблони та матеріали
інших курсів не є цілями. Операція не змінює дизайн, оцінювання, публікацію, розклад,
файли, їхні scopes або студентів. Інші тарифи й непередані матеріали зберігаються.
Запис повертає актуальну таблицю, revision та changedElementUuids; порожній
changedElementUuids означає, що потрібні прив’язки вже були в запитаному стані.

Щоб замінити один тариф іншим, спочатку додай потрібний, потім прибери попередній
лише для визначених матеріалів; використовуй нову revision після кожного запису.
Не прибирай усі прив’язки для побудови таблиці заново. Понад 200 цілей розділяй
на послідовні пакети або використовуй явне доручення для всього розділу.

## Конфлікти й результат

Усі записи використовують requestId. Зберігай його та executionId після таймауту.
QUEUED/RUNNING — читай get_execution; UNKNOWN не означає відсутність запису.
Не повторюй невизначену операцію з новим requestId. При CONFLICT перечитай
відповідні налаштування/таблицю й застосуй тільки намір користувача до актуального
стану. Не перенось старий повний об’єкт під нову revision.

Після SUCCEEDED підтвердь фактичну дію та її область. За потреби перевір
get_course/get_course_tariffs/get_course_tariff_materials. Не обіцяй оновлення
студентських тарифів, сповіщення, публікацію матеріалів або видалення файлів.