Перейти к содержанию

MintOffice

MintOffice — это портал Brand Partner для mintbot.ai. Он позволяет вам перепродавать mintbot под собственным брендом: ваш домен, ваш бот, ваш список клиентов — а mintbot берёт на себя деплой, биллинговые рельсы и инфраструктуру под каждого агента под капотом.

Живой партнёрский портал находится по адресу mint.mintbot.ai.

Это руководство проведёт вас от «я только что услышал о MintOffice» до «мой первый white-label-агент работает на моём собственном домене». Технические части (DNS-записи, GitHub-репозиторий, токен бота) лучше всего доверить агенту mintbot от вашего имени — смотрите Поручите настройку агенту, прежде чем начать.

Строите интеграцию сами?

Про сторону для разработчиков — какими репозиториями вы владеете, как сквозно работает поток деплоя и как agent customization repo и магазин стыкуются друг с другом — смотрите MintOffice — Технический раздел.

Что вы получаете

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

Цены — стоимость настройки Brand Partner

Регистрация бесплатного триального аккаунта портала, ну, бесплатна — а вот регистрация Brand Partner — это тот самый единственный платёж, который превращает его в настоящий аккаунт brand-партнёра. Разовую стоимость настройки вы оплачиваете на reception.mintbot.ai/mintoffice (или reception.mintbot.dev/mintoffice для dev/тестового окружения), и тот же платёж открывает оба портала:

Уровень Цена Что включено
Бесплатный триал (по умолчанию для каждого нового партнёра) €0 10 одноразовых DEV-деплоев для тестирования вашего портала + шаблона
Brand Partner — стартовое промо €49 разово + €10/месяц 20 DEV-деплоев (по €1 кредита агента на каждый), первый месяц управления аккаунтом включён, статус Brand Partner на обоих mint.mintbot.ai + mint.mintbot.dev, подробное руководство по настройке (агент может прогнать весь мастер за вас)
Brand Partner — стандарт €99 разово + €10/месяц То же, что и в промо — без промо

Регистрация в бете

Оформление Brand Partner сейчас открыто в dev/тестовом окружении (reception.mintbot.dev/mintoffice). Живое оформление на .ai откроется в ближайшее время.

Что покрывает стоимость настройки:

  • 20 DEV-деплоев, каждый — одноразовый тестовый VPS на 24 часа с €1 кредита агента на борту — этого достаточно, чтобы сквозно прогнать ваш портал и шаблон кастомизации.
  • Ваш первый месяц управления аккаунтом (плата €10/месяц, описанная ниже) — так что первый месяц уже оплачен.
  • Статус Brand Partner на обоих mint.mintbot.ai и mint.mintbot.dev.

Плата €10/месяц за управление аккаунтом:

Начиная со второго месяца аккаунт Brand Partner несёт плату €10/месяц за управление аккаунтом. Удобнее всего платить её подпиской Stripe или PayPal (рекомендуется — она продлевается сама); разовую стоимость настройки можно также оплатить картой или криптовалютой (BTC, XMR и многие монеты через CCPayment).

Если ежемесячная плата прекращается, ваш аккаунт MintOffice переходит в статус приостановлен: вы не можете деплоить новых агентов, но ваши существующие клиентские агенты продолжают работать. Мы свяжемся с вами до того, как что-либо остановится, чтобы вы могли возобновить.

Что происходит после оплаты:

  1. Reception обрабатывает платёж за настройку на reception.mintbot.ai/mintoffice (или .dev, если вы в тестовом окружении) — карта / Apple Pay / Google Pay или криптовалюта.
  2. Reception немедленно отправляет подписанный грант на оба mint.mintbot.ai и mint.mintbot.dev, переключая ваш аккаунт в статус Brand Partner на обоих порталах.
  3. Вы получаете приветственное письмо от pigeon@mintbot.ai (или pigeon@mintbot.dev, если купили на тестовом окружении), содержащее обе ссылки для входа и указатель на это руководство.
  4. Войдите на том портале, с которого хотите начать. Если кросс-окруженческий push по какой-то причине промахнулся мимо одного из порталов, первый вход на этом портале спрашивает reception «этот email оплатил?» и применяет грант на месте.

Стартовое промо включено по умолчанию, пока мы раскатываем MintOffice; оно управляется серверным флагом MINTOFFICE_SETUP_PROMO, поэтому цена, которую вы видите на оформлении, — это цена, которую вы заплатите.

Возвраты

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

Оптовое ценообразование за агента (ставка, которую mintbot берёт с вас за каждый клиентский заказ, который вы создаёте) не зависит от стоимости настройки и описано в Шаг 5 — Ценообразование ниже.

Поручите настройку агенту

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

Рекомендуемый путь

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

У агента есть доступ к терминалу, браузеру, DNS API, авторизации GitHub и знание этого руководства. Он точно скажет вам, какой шаг требует вашего вмешательства (например, нажать подтверждение BotFather в Telegram), и сделает остальное.

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

Если вы предпочитаете вести мастер сами, шаги ниже — ровно то, что сделал бы агент.

Шаг 0 — Создание аккаунта

  1. Откройте mint.mintbot.ai.
  2. Введите email-адрес, который хотите использовать как операторский логин.
  3. Нажмите Send me a sign-in link.
  4. Откройте письмо от pigeon@mintbot.ai и нажмите magic link (действует 24 ч, одноразовая).

Пароля нет — каждый последующий вход — это очередная magic link. Это сделано намеренно: пароли утекают, magic links — нет, и их легко автоматизировать агенту позже, если вы настроите доступ к почте.

Шаг 1 — Домен

Первый вопрос мастера — где будут жить ваши агенты. У вас есть два варианта:

Агенты живут на поддоменах домена, которым владеете вы — например, agent1.yourbrand.com, agent2.yourbrand.com, … Это брендированный опыт, который видят ваши клиенты.

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

  • Apex-домен — зарегистрированный голый домен (без 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 заскаффолжены, но ещё не подключены.

Ваши клиенты общаются с @yourbrand_bot, что сохраняет бренд нетронутым.

  1. Откройте @BotFather в Telegram.
  2. Отправьте /newbot. Дайте боту отображаемое имя и username (должен заканчиваться на bot).
  3. BotFather возвращает токен вида 123456789:AA… (минимум 40 символов).
  4. Вставьте этот токен в мастер.

Смотрите туториал по ботам 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 вашего репозитория в мастер; оставьте пустым — и получите простую небрендированную базу.

Создайте репозиторий с 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 по умолчанию — оставьте на потом, если только вы не готовы интегрироваться прямо сейчас.

Когда будете готовы:

  1. В панели откройте Settings → API access.
  2. Нажмите Generate key. Plaintext показывается один раз — сохраните его в своём менеджере секретов.
  3. (Необязательно) Настройте webhook URL для получения событий жизненного цикла.
  4. (Необязательно) Сгенерируйте секрет подписи webhook, когда ваш получатель будет готов проверять подписи.

Смотрите справочник Brand Partner API для полного списка эндпоинтов и форм payload webhook.

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. Смотрите Референсный портал ниже для полного разбора.

Шаг 5 — Ценообразование

Последний шаг мастера — сколько ваши клиенты платят за пакет. MintOffice делит ценообразование на два режима — переключиться можно позже в Settings → Pricing:

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

Вы задаёте цену, которую каждый клиент платит за каждый уровень. Вы кладёте в карман каждый цент сверх оптового минимума. Выберите это, когда у вас есть продуманная стратегия наценки.

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

Кастомное ценообразование может быть частичным

Даже в кастомном режиме вам не обязательно переопределять каждый уровень — оставьте уровень на значении по умолчанию, и он наследует рекомендованную mintbot цену. Редактируйте только те, что вам важны.

Запуск

После мастера панель показывает баннер, перечисляющий любую всё ещё недостающую обязательную информацию. Три обязательных поля:

  1. Токен Telegram-бота (или другой провайдер бота)
  2. DNS API-ключ (например, ключ Zone.ee + имя пользователя)
  3. Apex-домен

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 становятся только для чтения. Существующие клиентские агенты уже указывают на ваш apex-домен и общаются через вашего бота — тихое изменение осиротило бы их посреди жизни. Остальные разделы остаются редактируемыми:

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

Блокировка обеспечивается и в UI (fieldset отключён, баннер объясняет причину), и на сервере (POST на /settings с section=domain или section=bot возвращают 403).

Webhooks + выплаты

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

Референсный портал

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

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

Разбор настройки

  1. Форкните репозиторий, чтобы держать изменения брендинга в git:

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

  2. Заполните .env значениями из панели MintOffice:

    Переменная Что сюда идёт
    PARTNER_BRAND Видимое клиенту название бренда (также используется как метка line-item в Stripe).
    MINTOFFICE_API_URL https://mint.mintbot.ai для live, https://mint.mintbot.dev для тестирования.
    MINTOFFICE_API_KEY API-ключ из Settings → API access (формат mo_live_…).
    MINTOFFICE_WEBHOOK_SECRET Секрет подписи webhook, показываемый один раз при создании в той же панели.
    PUBLIC_BASE_URL HTTPS URL, на котором будет жить ваш портал (используется для построения Stripe success_url / cancel_url).
    ADMIN_USERNAME / ADMIN_PASSWORD Basic-auth защита на /admin. Используйте длинный случайный пароль.

  3. Запустите — Docker самый простой путь; bare-metal тоже работает:

    docker compose up --build

    pip install -e .
uvicorn app.main:app --reload

  4. Выставьте на HTTPS — MintOffice отклоняет http:// как для URL редиректа Stripe, так и для webhook URL (приватные IP и localhost блокируются SSRF-защитой). Для локальной разработки используйте Cloudflare Tunnel, Tailscale Funnel или ngrok. Для продакшена разверните на собственном хосте.

  5. Нацельте партнёрскую строку на портал — обратно в панели:

    • Задайте 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 как получатель webhook под https://portal.<my-domain>/, заполни MINTOFFICE_API_KEY и MINTOFFICE_WEBHOOK_SECRET из GET /api/v1/settings и задай webhook URL в моей партнёрской строке». У агента есть документация и путь к API-ключу, чтобы сделать это от начала до конца.

Brand Partner API

Для программного создания агентов, опроса статуса и событий webhook смотрите справочник Brand Partner API. Для более широкой архитектуры (как ваш магазин, API, деплой-воркер и VPS агента каждого клиента стыкуются друг с другом) смотрите MintOffice — Технический раздел.