MintOffice¶

MintOffice — це портал для брендових партнерів mintbot.ai. Він дозволяє перепродавати mintbot під вашим власним брендом: ваш домен, ваш бот, ваш список клієнтів — тоді як mintbot бере на себе розгортання, платіжні механізми та інфраструктуру окремих агентів під капотом.

Робочий партнерський портал розташований за адресою mint.mintbot.ai.

Цей посібник проведе вас від «я щойно почув про MintOffice» до «мій перший white-label агент працює на моєму власному домені». Технічні частини (DNS-записи, GitHub-репозиторій, токен бота) найкраще доручити агенту mintbot за вас — див. Let an agent set you up, перш ніж почати.

Будуєте інтеграцію самостійно?

Щодо боку для розробників — які репозиторії вам належать, як виконується процес розгортання від початку до кінця та як agent customization repo + вітрина поєднуються разом — див. MintOffice — Technical.

Що ви отримуєте¶

Перепродавайте кожен пакет mintbot (Trial, Starter, Pro, Max) під вашим власним доменом — ваші клієнти бачать agent1.yourbrand.com, а не *.mintbot.ai.
Використовуйте власного Telegram-бота (@yourbrand_bot) для чат-трафіку або позичте бота mintbot, поки ще тестуєте.
Обирайте ціни для ваших клієнтів і залишайте собі різницю між тим, що ви берете з них, і тим, що mintbot бере з вас (оптова нижня межа MintOffice).
Brand Partner API для програмного створення замовлень, статусу життєвого циклу та вебхуків назад у ваші власні системи.
Панель керування, що показує активні замовлення клієнтів, стан зв'язку з ботом, ціни, виплати та доставку вебхуків.

Ціни — плата за налаштування Brand Partner¶

Реєстрація безкоштовного пробного облікового запису порталу, ну, безкоштовна — але плата за реєстрацію Brand Partner — це єдиний платіж, який перетворює його на справжній обліковий запис брендового партнера. Ви платите один раз на reception.mintbot.ai/mintoffice (або reception.mintbot.dev/mintoffice для середовища розробки/тестування), і той самий платіж розблоковує обидва портали:

Рівень	Ціна	Що включено
Безкоштовна пробна версія (за замовчуванням для кожного нового партнера)	$0	10 одноразових DEV-розгортань для тестування вашого порталу + шаблону
Brand Partner — промо до запуску	$49 одноразово	42 одноразові DEV-розгортання, статус Brand Partner на обох `mint.mintbot.ai` + `mint.mintbot.dev`, докладний посібник із налаштування (агент може провести весь майстер за вас)
Brand Partner — стандарт	$99 одноразово	Те саме, що й промо, — але без знижки

Що відбувається після оплати:

Stripe обробляє платіж на reception.mintbot.ai/mintoffice (або .dev, якщо ви в тестовому середовищі) — той самий процес із карткою / Apple Pay / Google Pay, що й для звичайних замовлень рівнів mintbot.
Reception одразу надсилає підписаний грант на обидва mint.mintbot.ai та mint.mintbot.dev, перемикаючи ваш обліковий запис на статус Brand Partner на обох порталах.
Ви отримуєте вітальний лист від pigeon@mintbot.ai (або pigeon@mintbot.dev, якщо ви купили в тестовому середовищі), що містить обидва посилання для входу та вказівник на цей посібник.
Увійдіть на тому порталі, з якого хочете почати. Якщо міжсередовищна передача з якоїсь причини не дійшла до котрогось із порталів, перший вхід на цьому порталі запитає reception «чи оплатив цей email?» і застосує грант на місці.

Плата є одноразовим платежем, а не підпискою. Промо до запуску ввімкнене за замовчуванням, поки ми розгортаємо MintOffice; воно контролюється серверним прапорцем MINTOFFICE_SETUP_PROMO, тож ціна, яку ви бачите на оформленні, — це ціна, яку ви заплатите.

Повернення коштів

14-денне вікно повернення коштів без зайвих питань — якщо рівень не вартий того для вашого випадку використання, напишіть на support@mintbot.ai, і ми повернемо плату.

Оптові ціни за агента (ставка, яку mintbot бере з вас за кожне замовлення клієнта, яке ви створюєте) не залежать від плати за налаштування і описані в Step 5 — Pricing нижче.

Доручіть налаштування агенту¶

Більшість технічної роботи — купівля домену, налаштування DNS, створення Telegram-бота, форк репозиторію шаблону — механічна. Ви можете зробити це вручну, але найзручніший шлях — делегувати це агенту mintbot.

Рекомендований шлях

Запустіть агента mintbot і попросіть його: «Налаштуй мене як брендового партнера MintOffice під доменом yourbrand.com — проведи мене через майстер онбордингу і заповни все, що зможеш, за мене.»

Агент має доступ до терміналу, браузера, DNS API, автентифікації GitHub та знає цей посібник. Він точно скаже, який крок потребує вашого втручання (наприклад, натискання підтвердження BotFather у Telegram), і впорається з рештою.

Ваш власний Hermes, встановлення OpenCode / OpenClaw, режим агента Cursor чи будь-який інший кодувальний агент працюють так само добре — передайте йому цю сторінку як контекст і вкажіть мету.

Якщо ви волієте керувати майстром самостійно, кроки нижче — це саме те, що зробив би агент.

Крок 0 — Створіть обліковий запис¶

Відкрийте mint.mintbot.ai.
Введіть адресу електронної пошти, яку хочете використовувати як логін оператора.
Натисніть Send me a sign-in link.
Відкрийте лист від pigeon@mintbot.ai і натисніть магічне посилання (дійсне 24 год, одноразове).

Тут немає пароля — кожен наступний вхід — це ще одне магічне посилання. Це навмисно: паролі витікають, магічні посилання — ні, і їх легко автоматизувати агенту згодом, якщо ви налаштуєте доступ до пошти.

Крок 1 — Домен¶

Перше питання майстра — де житимуть ваші агенти. У вас є два варіанти:

Використати власний домен (рекомендовано)Використати піддомен mintbot.ai

Агенти живуть на піддоменах домену, який належить вам — наприклад, agent1.yourbrand.com, agent2.yourbrand.com, … Це брендований досвід, який бачать ваші клієнти.

Вам знадобиться:

Апекс-домен — зареєстрований «голий» домен (без https://, без піддомену): yourbrand.com.
DNS-провайдер — наразі лише Zone.ee має робочий бекенд. Cloudflare та ручні режими в планах.
API-ключ Zone.ee + ім'я користувача — видаються в my.zone.eu → Account settings → API keys → Create new key. Агент використовує це для автоматичного створення A-записів під час провізіювання агента.

Стиль нумерації піддоменів

Текстовий префікс + число (за замовчуванням) — agent1.yourbrand.com, agent2.yourbrand.com, … Найбільш зручний для читання.
Лише числа — 1.yourbrand.com, 2.yourbrand.com, … Коротко.
Числа з провідними нулями — 001.yourbrand.com, … Стала ширина.

Вибір суто косметичний — воркер розгортання влаштовують усі три.

Агенти живуть на *.mintbot.ai — без налаштування, без DNS, але URL не несе вашого бренду. Корисно для перших спроб; перейдіть на власний домен перед запуском для клієнтів.

Крок 2 — Бот¶

Кожен агент отримує чат-поверхню. Типові налаштування передбачають Telegram — Discord та Slack підготовлені каркасно, але ще не підключені.

Підключити власного Telegram-бота (рекомендовано)Позичити бота mintbotПоки що без бота

Ваші клієнти спілкуються з @yourbrand_bot, що зберігає бренд незмінним.

Відкрийте @BotFather у Telegram.
Надішліть /newbot. Дайте боту відображуване ім'я та ім'я користувача (має закінчуватися на bot).
BotFather повертає токен у форматі 123456789:AA… (щонайменше 40 символів).
Вставте цей токен у майстер.

Див. туторіал по ботах Telegram, якщо хочете розгорнутішу версію.

Клієнти спілкуються з @mintbot_dev_bot. Швидко для демо, але без брендингу. Перемкніться на власного бота перед запуском.

Повністю пропустіть Telegram. Клієнти отримують доступ до агентів лише через вебпанель. Бота можна додати пізніше в Settings.

Крок 3 — Agent customization repo¶

Кожен агент розгортається на стандартній, небрендованій базі самим mintbot. Щоб накласти зверху ваш бренд — персону, тему панелі, тексти, будь-який додатковий інструментарій — ви вказуєте майстру agent customization repo: GitHub-репозиторій, який власний VPS агента клонує та запускає після стандартного розгортання. Ви вирішуєте, який вигляд; ви володієте кодом.

Як працює agent customization repo

Корінь репозиторію містить два скрипти:

install.sh — запускається один раз на VPS агента, після того як стандартне розгортання завершилося і агент справний. Саме тут ви застосовуєте свою кастомізацію: тему, налаштування персони, додаткові інструменти, будь-яке налаштування під конкретного клієнта.
update.sh — необов'язковий; запускається після кожного оновлення базового пакета, щоб ви могли повторно накласти свій шар поверх щойно оновленої бази.

Mintbot ніколи не запускає ваш репозиторій — лише власний VPS агента, на власній машині клієнта. Вставте GitHub HTTPS URL вашого репозиторію в майстер; залиште його порожнім — і ви отримаєте просту небрендовану базу.

Вказати на власний agent customization repo (рекомендовано)Залишити порожнім

Створіть репозиторій з install.sh (та необов'язковим update.sh) у його корені, що застосовує ваш CSS / рядки / персону, а потім вставте GitHub HTTPS URL репозиторію. VPS агента клонує його після розгортання та запускає ваші скрипти, щоб накласти ваш бренд поверх бази.

Зламаний скрипт не може зламати агента вашого клієнта

Ваші скрипти ізольовані від збоїв. Якщо install.sh чи update.sh відсутній, завершується з помилкою або працює повільно, розгортання все одно вдається, оновлення базового пакета ніколи не блокується і не відкочується, а агент лишається справним. Збій реєструється на VPS і доводиться до вас — ніколи до кінцевого клієнта. Єдиний недолік зламаного скрипта в тому, що агент лишається на простій базі замість вашого брендованого шару, тож спершу протестуйте свій репозиторій на DEV-розгортанні.

Проста небрендована базова стилізація та персона — без agent customization repo. URL репозиторію можна додати пізніше в Settings.

Крок 4 — API¶

Brand Partner API дозволяє вам оркеструвати створення агентів з вашого власного бекенду замість використання панелі керування. Майстер за замовчуванням пропускає налаштування API — залиште його на потім, якщо ви не готові інтегруватися зараз.

Коли будете готові:

У панелі керування відкрийте Settings → API access.
Натисніть Generate key. Відкритий текст показується один раз — збережіть його у вашому менеджері секретів.
(Необов'язково) Налаштуйте webhook URL для отримання подій життєвого циклу.
(Необов'язково) Згенеруйте секрет підпису вебхука, щойно ваш приймач буде готовий перевіряти підписи.

Див. Brand Partner API reference для повного переліку ендпоінтів і форм корисного навантаження вебхуків.

Webhook URL і секрет підпису необов'язкові

Жоден з них не потрібен, щоб почати продавати — панель керування та API чудово працюють без них. Поле webhook URL лишається порожнім, поки у вас немає приймача, спрямованого на https://<your-host>/...; секрет підпису корисний лише після того, як ви встановили цей URL і хочете перевіряти заголовок X-Mintbot-Signature. Обидва можна додати (або змінити) будь-коли в Settings → API access.

Дозвольте інтеграційному агенту виявити налаштування

Щойно у вас з'явиться API-ключ, агент може викликати GET /api/v1/settings, щоб прочитати всю вашу несекретну конфігурацію за один раз — домен, DNS-провайдер, бот, agent customization repo, шаблон піддомену, ціни, готовність. Жоден секрет ніколи не повертається (токени та ключі з'являються лише як булеві *_set), тож ключ безпечно передати агенту, який встановлює ваше white-label налаштування на свіжому сервері.

Пропустіть шаблонний код — форкніть еталонний портал

Повний, готовий до запуску приклад вітрини розташований за адресою mintbot-ai/partner-portal-example. Див. Reference portal нижче для повного покрокового опису.

Крок 5 — Ціни¶

Останній крок майстра — те, скільки ваші клієнти платять за пакет. MintOffice розділяє ціноутворення на два режими — ви можете перемкнутися пізніше в Settings → Pricing:

Використати ціни за замовчуванням (рекомендовано)Встановити власні ціни за рівнями

Клієнти бачать рекомендовану mintbot ціну за рівень (Trial, Starter, Pro, Max). Ви заробляєте партнерську маржу між цією рекомендованою ціною та оптовою нижньою межею — без налаштування. Оберіть це, якщо просто хочете почати продавати.

Ви встановлюєте ціну, яку кожен клієнт платить за кожен рівень. Ви залишаєте собі кожен цент понад оптову нижню межу. Оберіть це, коли у вас є продумана стратегія націнки.

Оптова нижня межа — це те, що mintbot бере з вас за замовлення — це абсолютний мінімум, який ви можете брати. Ваша партнерська частка — це customer_price − wholesale_floor за замовлення. Майстер показує попередній розрахунок маржі за кожен рівень перед тим, як ви надішлете.

Власне ціноутворення може бути частковим

Навіть у режимі custom вам не обов'язково перевизначати кожен рівень — залиште рівень на значенні за замовчуванням, і він успадкує рекомендовану mintbot ціну. Редагуйте лише ті, що вас цікавлять.

Запуск¶

Після майстра панель керування показує банер зі списком будь-якої досі відсутньої обов'язкової інформації. Три обов'язкові поля:

Токен Telegram-бота (або іншого провайдера ботів)
DNS API-ключ (наприклад, ключ Zone.ee + ім'я користувача)
Апекс-домен

URL agent customization repo необов'язковий — залиште його порожнім, і ваші агенти розгортатимуться на простій небрендованій базі.

Щойно обов'язкові поля заповнено і перевірка DNS-провайдера пройдена, активується кнопка Go Live. Натискання на неї перемикає ваш партнерський статус із onboarding → live, і Brand Partner API починає приймати запити на створення замовлень.

Активація — це одностороннє рукостискання

Ваш обліковий запис лишається в стані onboarding, доки ви не натиснете Go Live. Під час онбордингу API відхиляє записи з 403 (читання лишається відкритим, щоб ви могли оглядати стан). Не активуйте, доки DNS вашого домену не перевірено в Zone.ee і (якщо ви її використовуєте) ви не протестували свій репозиторій кастомізації на DEV-розгортанні.

Після Go Live: налаштування домену + Telegram-бота блокуються

Щойно ваш партнерський статус стає live, розділи Domain та Telegram bot у Settings стають доступними лише для читання. Наявні агенти клієнтів уже вказують на ваш апекс-домен і спілкуються через вашого бота — тиха зміна осиротила б їх посеред життя. Інші розділи лишаються редагованими:

Розділ	Редаговано в стані `live`?
Домен / DNS / шаблон піддомену	Ні — зверніться до підтримки, якщо потрібно мігрувати
Telegram-бот	Ні — зверніться до підтримки, якщо потрібно мігрувати
Agent customization repo	Так — нові агенти клонують новий URL репозиторію; наявні агенти повторно запускають його через `update.sh` під час наступного оновлення бази
API-ключ / вебхук	Так — змінюйте будь-коли
Ціни	Так — застосовуються до майбутніх замовлень

Блокування забезпечується як в інтерфейсі (вимкнений fieldset, банер із поясненням причини), так і на сервері (POST-запити до /settings з section=domain чи section=bot повертають 403).

Вебхуки + виплати¶

Доставки вебхуків — кожна подія життєвого циклу (замовлення створено, активовано, прострочено) надсилається на webhook URL, який ви встановили в Settings. Чип Webhook health для кожного партнера в панелі керування показує частку успішних доставок за останні 24 год.
Реєстр доходів — кожне оплачене замовлення записує рядок із вашим валовим доходом, вашою часткою та часткою mintbot. Панель керування показує сумарні підсумки за весь час і несплачений баланс.
Виплати — накопичуються. Команда mintbot виплачує їх вручну згідно з партнерською угодою; панель керування відстежує статус сплачено / несплачено.

Еталонний портал¶

Якщо ви не хочете будувати вітрину з нуля, форкніть офіційний приклад: mintbot-ai/partner-portal-example. Це FastAPI + SQLite + Docker під ліцензією MIT, постачається з вигаданим брендингом «AcmeAI», який ви можете замінити, і покриває весь цикл від початку до кінця:

цільова сторінка з картками планів,
форма /buy → POST /api/v1/orders → перенаправлення на оформлення Stripe,
сторінки подяки / повернення при скасуванні,
POST /webhooks/mintoffice з перевіряльником підпису HMAC,
браузер подій /admin з HTTP-Basic-автентифікацією,
проба живучості /healthz.

Покроковий опис налаштування¶

Форкніть репозиторій, щоб тримати зміни брендингу в git:

git clone https://github.com/mintbot-ai/partner-portal-example.git
cd partner-portal-example
cp .env.example .env

Заповніть .env значеннями з вашої панелі керування MintOffice:

Змінна	Що сюди вписати
`PARTNER_BRAND`	Видима клієнту назва бренду (також використовується як підпис позиції в Stripe).
`MINTOFFICE_API_URL`	`https://mint.mintbot.ai` для робочого середовища, `https://mint.mintbot.dev` для тестування.
`MINTOFFICE_API_KEY`	API-ключ із Settings → API access (формат `mo_live_…`).
`MINTOFFICE_WEBHOOK_SECRET`	Секрет підпису вебхука, показаний один раз під час створення в тій самій панелі керування.
`PUBLIC_BASE_URL`	HTTPS URL, на якому житиме ваш портал (використовується для побудови `success_url` / `cancel_url` Stripe).
`ADMIN_USERNAME` / `ADMIN_PASSWORD`	Захист `/admin` через Basic-auth. Використовуйте довгий випадковий пароль.

Запустіть — Docker найпростіший шлях; bare-metal теж працює:
DockerЛокальний Python
docker compose up --build
pip install -e . uvicorn app.main:app --reload
Виставте його на HTTPS — MintOffice відхиляє http:// як для URL перенаправлення Stripe, так і для webhook URL (приватні IP та localhost блокуються захистом від SSRF). Для локальної розробки використовуйте Cloudflare Tunnel, Tailscale Funnel або ngrok. Для продакшену розгорніть на власному хості.
Спрямуйте свій партнерський рядок на портал — назад у панелі керування:
- Встановіть Webhook URL на https://<your-host>/webhooks/mintoffice.
- Ось і все. Зробіть тестове замовлення з /buy і спостерігайте, як події надходять у /admin.

Зміна брендингу¶

Типові шаблони прикидаються AcmeAI. Три точки дотику:

PARTNER_BRAND у .env — потрапляє в Stripe, заголовки, підвали.
app/templates/base.html — CSS-змінні для кольорів / акценту.
app/templates/*.html — тексти та компонування кожної сторінки. Переклади (естонська, іспанська, …) живуть як форки цих файлів.

Швидке розгортання на тому самому VPS, що й ваші агенти

Приклад порталу достатньо малий, щоб працювати поряд із вашим агентом розгортання MintOffice. Якщо у вас уже є VPS агента mintbot, попросіть його: «Розгорни partner-portal-example як приймач вебхуків під https://portal.<my-domain>/, заповни MINTOFFICE_API_KEY та MINTOFFICE_WEBHOOK_SECRET з GET /api/v1/settings і встанови webhook URL у моєму партнерському рядку.» Агент має документацію та шлях до API-ключа, щоб зробити це від початку до кінця.

Brand Partner API¶

Для програмного створення агентів, опитування статусу та подій вебхуків див. Brand Partner API reference. Щодо ширшої архітектури (як ваша вітрина, API, воркер розгортання та VPS агента кожного клієнта поєднуються разом), див. MintOffice — Technical.