MintOffice¶

MintOffice est le portail Brand Partner de mintbot.ai. Il vous permet de revendre mintbot sous votre propre marque : votre domaine, votre bot, votre liste de clients — mintbot se chargeant du déploiement, des rails de facturation et de l'infrastructure par agent en coulisses.

Le portail partenaire en production se trouve à l'adresse mint.mintbot.ai.

Ce guide vous accompagne de « je viens d'entendre parler de MintOffice » à « mon premier agent en marque blanche est en ligne sur mon propre domaine ». Les parties techniques (enregistrements DNS, dépôt GitHub, token de bot) sont mieux gérées par un agent mintbot en votre nom — voir Laissez un agent vous configurer avant de commencer.

Vous construisez l'intégration vous-même ?

Pour le versant développeur — quels dépôts vous possédez, comment le flux de déploiement se déroule de bout en bout, et comment l'agent customization repo + la vitrine s'articulent — voir MintOffice — Technique.

Ce que vous obtenez¶

Revendez chaque forfait mintbot (Trial, Starter, Pro, Max) sous votre propre domaine — vos clients voient agent1.yourbrand.com, pas *.mintbot.ai.
Utilisez votre propre bot Telegram (@yourbrand_bot) pour le trafic de chat, ou empruntez le bot de mintbot pendant que vous testez encore.
Choisissez vos prix destinés aux clients et empochez la différence entre ce que vous leur facturez et ce que mintbot vous facture (le plancher de gros MintOffice).
Une Brand Partner API pour la création programmatique de commandes, le statut du cycle de vie et les webhooks vers vos propres systèmes.
Un tableau de bord affichant les commandes clients actives, la santé des liens de bot, les prix, les versements et la livraison des webhooks.

Tarification — frais d'inscription Brand Partner¶

S'inscrire pour un compte de portail d'essai gratuit est, eh bien, gratuit — mais l'inscription Brand Partner est le seul paiement qui le transforme en véritable compte brand-partner. Vous réglez les frais d'inscription uniques sur reception.mintbot.ai/mintoffice (ou reception.mintbot.dev/mintoffice pour l'environnement de dev/test) et le même paiement débloque les deux portails :

Palier	Prix	Ce qui est inclus
Essai gratuit (par défaut pour tout nouveau partenaire)	€0	10 déploiements DEV jetables pour tester votre portail + template
Brand Partner — promo de lancement	€49 unique + €10/mois	20 déploiements DEV (€1 de crédit agent chacun), premier mois de gestion de compte inclus, statut Brand Partner sur `mint.mintbot.ai` + `mint.mintbot.dev`, guide de configuration détaillé (un agent peut piloter tout l'assistant pour vous)
Brand Partner — standard	€99 unique + €10/mois	Identique au lancement — sans la promo

Inscription en bêta

Le paiement Brand Partner est actuellement ouvert sur l'environnement de dev/test (reception.mintbot.dev/mintoffice). Le paiement en ligne sur .ai ouvre prochainement.

Ce que couvrent les frais d'inscription :

20 déploiements DEV, chacun un VPS de test jetable de 24 heures provisionné avec €1 de crédit agent — de quoi exercer votre portail et votre template de personnalisation de bout en bout.
Votre premier mois de gestion de compte (les frais de €10/mois ci-dessous) — le premier mois est donc déjà payé.
Le statut Brand Partner sur mint.mintbot.ai et mint.mintbot.dev.

Les frais de gestion de compte de €10/mois :

À partir du deuxième mois, le compte Brand Partner est assorti de frais de gestion de compte de €10/mois. La façon la plus simple de les régler est un abonnement Stripe ou PayPal (recommandé — il se renouvelle tout seul) ; les frais d'inscription uniques peuvent aussi être payés par carte ou en crypto (BTC, XMR et de nombreuses cryptos via CCPayment).

Si les frais mensuels ne sont plus payés, votre compte MintOffice passe en pause : vous ne pouvez plus déployer de nouveaux agents, mais vos agents clients existants continuent de fonctionner. Nous vous contacterons avant tout arrêt afin que vous puissiez reprendre.

Ce qui se passe après le paiement :

Reception traite le paiement d'inscription sur reception.mintbot.ai/mintoffice (ou .dev si vous êtes sur l'environnement de test) — carte / Apple Pay / Google Pay, ou crypto.
Reception envoie immédiatement une autorisation signée à la fois à mint.mintbot.ai et mint.mintbot.dev, faisant passer votre compte au statut Brand Partner sur les deux portails.
Vous recevez un e-mail de bienvenue de pigeon@mintbot.ai (ou pigeon@mintbot.dev si vous avez acheté sur l'environnement de test) contenant les deux liens de connexion et un pointeur vers ce guide.
Connectez-vous au portail de votre choix pour commencer. Si la propagation cross-env a manqué l'un des portails pour une raison quelconque, la première connexion sur ce portail demande à reception « cet e-mail a-t-il payé ? » et applique l'autorisation sur-le-champ.

La promo de lancement est activée par défaut pendant que nous déployons MintOffice ; elle est contrôlée par le flag serveur MINTOFFICE_SETUP_PROMO, donc le prix que vous voyez au paiement est le prix que vous paierez.

Remboursements

Fenêtre de remboursement de 14 jours, sans poser de questions — si le palier n'en vaut pas la peine pour votre cas d'usage, écrivez à support@mintbot.ai et nous vous rembourserons les frais.

La tarification de gros par agent (le tarif que mintbot vous facture pour chaque commande client que vous créez) est indépendante des frais d'inscription et se trouve dans Étape 5 — Tarification ci-dessous.

Laissez un agent vous configurer¶

La plupart du travail technique — acheter un domaine, configurer le DNS, créer un bot Telegram, forker le dépôt template — est mécanique. Vous pouvez le faire à la main, mais le chemin le plus fluide est de le déléguer à un agent mintbot.

Chemin recommandé

Lancez un agent mintbot et demandez-lui : « Configure-moi comme brand partner MintOffice sous le domaine yourbrand.com — guide-moi à travers l'assistant d'onboarding et remplis tout ce que tu peux en mon nom. »

L'agent a accès à un terminal, un navigateur, une API DNS, l'authentification GitHub, et la connaissance de ce guide. Il vous dira exactement quelle étape nécessite votre intervention (par ex. cliquer sur la confirmation de BotFather dans Telegram) et gérera le reste.

Votre propre Hermes, une installation OpenCode / OpenClaw, le mode agent de Cursor, ou tout autre agent de codage fonctionne tout aussi bien — donnez-lui cette page comme contexte et indiquez-lui l'objectif.

Si vous préférez piloter l'assistant vous-même, les étapes ci-dessous sont exactement ce que l'agent ferait.

Étape 0 — Créez votre compte¶

Ouvrez mint.mintbot.ai.
Saisissez l'adresse e-mail que vous voulez utiliser comme identifiant opérateur.
Cliquez sur Send me a sign-in link.
Ouvrez l'e-mail de pigeon@mintbot.ai et cliquez sur le lien magique (valable 24 h, à usage unique).

Il n'y a aucun mot de passe — chaque connexion ultérieure est un nouveau lien magique. C'est intentionnel : les mots de passe fuient, pas les liens magiques, et ils sont faciles à automatiser pour un agent plus tard si vous configurez l'accès e-mail.

Étape 1 — Domaine¶

La première question de l'assistant est où vivront vos agents. Vous avez deux choix :

Utiliser mon propre domaine (recommandé)Utiliser un sous-domaine mintbot.ai

Les agents vivent sur des sous-domaines d'un domaine que vous possédez — par ex. agent1.yourbrand.com, agent2.yourbrand.com, … C'est l'expérience de marque que vos clients voient.

Il vous faudra :

Domaine apex — un domaine nu enregistré (pas de https://, pas de sous-domaine) : yourbrand.com.
Fournisseur DNS — actuellement seul Zone.ee a un backend fonctionnel. Cloudflare et les modes manuels sont sur la feuille de route.
Clé API + nom d'utilisateur Zone.ee — émis depuis my.zone.eu → Account settings → API keys → Create new key. L'agent l'utilise pour créer automatiquement des enregistrements A lorsque vous provisionnez un agent.

Style de numérotation des sous-domaines

Préfixe texte + numéro (par défaut) — agent1.yourbrand.com, agent2.yourbrand.com, … Le plus lisible.
Numérique uniquement — 1.yourbrand.com, 2.yourbrand.com, … Court.
Numérique, complété par des zéros — 001.yourbrand.com, … Largeur stable.

Le choix est purement cosmétique — le worker de déploiement gère les trois sans problème.

Les agents vivent sur *.mintbot.ai — aucune configuration, aucun DNS, mais l'URL ne porte pas votre marque. Utile pour faire des essais ; passez à votre propre domaine avant le lancement client.

Étape 2 — Bot¶

Chaque agent dispose d'une surface de chat. Les valeurs par défaut supposent Telegram — Discord et Slack sont ébauchés mais pas encore raccordés.

Apporter mon propre bot Telegram (recommandé)Emprunter le bot de mintbotPas encore de bot

Vos clients discutent avec @yourbrand_bot, ce qui préserve la marque.

Ouvrez @BotFather dans Telegram.
Envoyez /newbot. Donnez au bot un nom d'affichage et un nom d'utilisateur (doit se terminer par bot).
BotFather renvoie un token de la forme 123456789:AA… (au moins 40 caractères).
Collez ce token dans l'assistant.

Voir le tutoriel bot de Telegram si vous voulez la version plus détaillée.

Les clients discutent avec @mintbot_dev_bot. Rapide pour une démo, mais sans marque. Basculez vers votre propre bot avant le lancement.

Ignorez complètement Telegram. Les clients accèdent aux agents uniquement via le panneau web. Vous pouvez ajouter un bot plus tard depuis Settings.

Étape 3 — Agent customization repo¶

Chaque agent est déployé sur une base standard et sans marque par mintbot lui-même. Pour y apposer votre marque — persona, thème du panneau, textes, tout outillage supplémentaire — vous pointez l'assistant vers un agent customization repo : un dépôt GitHub que le VPS de l'agent lui-même clone et exécute après le déploiement standard. Vous décidez de l'apparence ; vous possédez le code.

Comment fonctionne l'agent customization repo

La racine du dépôt contient deux scripts :

install.sh — s'exécute une seule fois sur le VPS de l'agent, après que le déploiement standard est terminé et que l'agent est sain. C'est là que vous appliquez votre personnalisation : thème, ajustements de persona, outils supplémentaires, toute configuration spécifique au client.
update.sh — optionnel ; s'exécute après chaque mise à jour du package de base, pour que vous puissiez réappliquer votre couche par-dessus la base fraîchement mise à jour.

Mintbot n'exécute jamais votre dépôt — seul le VPS de l'agent lui-même le fait, sur la propre machine du client. Collez l'URL HTTPS GitHub de votre dépôt dans l'assistant ; laissez-le vide et vous obtenez la base nue sans marque.

Pointer vers mon propre agent customization repo (recommandé)Laisser vide

Créez un dépôt avec un install.sh (et un update.sh optionnel) à sa racine qui applique votre CSS / vos chaînes / votre persona, puis collez l'URL HTTPS GitHub du dépôt. Le VPS de l'agent le clone après le déploiement et exécute vos scripts pour superposer votre marque sur la base.

Un script cassé ne peut pas casser l'agent de votre client

Vos scripts sont isolés des défaillances. Si install.sh ou update.sh est manquant, échoue ou s'exécute lentement, le déploiement réussit quand même, la mise à jour du package de base n'est jamais bloquée ni annulée, et l'agent reste sain. L'échec est journalisé sur le VPS et vous est remonté — jamais au client final. Le seul inconvénient d'un script cassé est que l'agent reste sur la base nue au lieu de votre couche de marque, alors testez d'abord votre dépôt sur un déploiement DEV.

Style de base et persona nus, sans marque — pas d'agent customization repo. Vous pouvez ajouter une URL de dépôt plus tard depuis Settings.

Étape 4 — API¶

La Brand Partner API vous permet d'orchestrer la création d'agents depuis votre propre backend au lieu d'utiliser le tableau de bord. L'assistant ignore la configuration de l'API par défaut — laissez-la pour plus tard sauf si vous êtes prêt à intégrer maintenant.

Quand vous êtes prêt :

Depuis le tableau de bord, ouvrez Settings → API access.
Cliquez sur Generate key. Le texte en clair est affiché une seule fois — stockez-le dans votre gestionnaire de secrets.
(Optionnel) Configurez une URL de webhook pour recevoir les événements de cycle de vie.
(Optionnel) Générez un secret de signature de webhook une fois que votre récepteur est prêt à vérifier les signatures.

Voir la référence Brand Partner API pour la liste complète des endpoints et les formes de payload des webhooks.

L'URL de webhook et le secret de signature sont optionnels

Aucun des deux n'est requis pour commencer à vendre — le tableau de bord et l'API fonctionnent très bien sans. Le champ URL de webhook reste vide jusqu'à ce que vous ayez un récepteur pointé vers https://<your-host>/... ; le secret de signature n'est utile qu'une fois cette URL définie et que vous voulez vérifier l'en-tête X-Mintbot-Signature. Les deux peuvent être ajoutés (ou renouvelés) à tout moment depuis Settings → API access.

Laissez un agent d'intégration découvrir la configuration

Une fois que vous avez une clé API, un agent peut appeler GET /api/v1/settings pour lire toute votre configuration non secrète d'un coup — domaine, fournisseur DNS, bot, agent customization repo, motif de sous-domaine, tarification, état de préparation. Aucun secret n'est jamais renvoyé (les tokens et clés n'apparaissent que sous forme de booléens *_set), donc la clé peut être partagée en toute sécurité avec l'agent qui installe votre configuration en marque blanche sur un serveur vierge.

Évitez le boilerplate — forkez le portail de référence

Une vitrine d'exemple complète et exécutable se trouve à mintbot-ai/partner-portal-example. Voir Portail de référence ci-dessous pour la présentation complète.

Étape 5 — Tarification¶

La dernière étape de l'assistant concerne ce que vos clients paient par forfait. MintOffice divise la tarification en deux modes — vous pouvez changer plus tard sous Settings → Pricing :

Utiliser la tarification par défaut (recommandé)Définir des prix personnalisés par palier

Les clients voient le prix recommandé par mintbot pour chaque palier (Trial, Starter, Pro, Max). Vous réalisez la marge partenaire entre ce prix recommandé et le plancher de gros — zéro configuration. Choisissez ceci si vous voulez simplement commencer à vendre.

Vous fixez le prix que chaque client paie pour chaque palier. Vous empochez chaque centime au-dessus du plancher de gros. Choisissez ceci quand vous avez une stratégie de marge délibérée.

Le plancher de gros est ce que mintbot vous facture par commande — c'est le minimum absolu que vous pouvez facturer. Votre part partenaire est customer_price − wholesale_floor par commande. L'assistant prévisualise les marges calculées par palier avant que vous ne validiez.

La tarification personnalisée peut être partielle

Même en mode personnalisé, vous n'avez pas à remplacer chaque palier — laissez un palier sur la valeur par défaut et il hérite du prix recommandé par mintbot. Modifiez uniquement ceux qui vous importent.

Mise en ligne¶

Après l'assistant, le tableau de bord affiche une bannière listant toute information requise encore manquante. Les trois champs requis sont :

Token de bot Telegram (ou un autre fournisseur de bot)
Clé API DNS (par ex. clé + nom d'utilisateur Zone.ee)
Domaine apex

L'URL de l'agent customization repo est optionnelle — laissez-la vide et vos agents se déploient sur la base nue sans marque.

Une fois les champs requis remplis et la vérification du fournisseur DNS réussie, le bouton Go Live s'active. Cliquer dessus fait passer votre statut de partenaire de onboarding → live, et la Brand Partner API commence à accepter les requêtes de création de commande.

L'activation est une poignée de main à sens unique

Votre compte reste en onboarding jusqu'à ce que vous cliquiez sur Go Live. Pendant l'onboarding, l'API rejette les écritures avec un 403 (les lectures restent ouvertes pour que vous puissiez inspecter l'état). N'activez pas avant que le DNS de votre domaine soit vérifié dans Zone.ee et (si vous en utilisez un) que vous ayez testé votre dépôt de personnalisation sur un déploiement DEV.

Après Go Live : les paramètres de domaine + bot Telegram se verrouillent

Une fois votre statut de partenaire live, les sections Domaine et Bot Telegram de Settings deviennent en lecture seule. Les agents clients existants pointent déjà vers votre domaine apex et discutent via votre bot — un changement silencieux les orphelinerait en pleine vie. Les autres sections restent modifiables :

Section	Modifiable en `live` ?
Domaine / DNS / motif de sous-domaine	Non — contactez le support si vous devez migrer
Bot Telegram	Non — contactez le support si vous devez migrer
Agent customization repo	Oui — les nouveaux agents clonent la nouvelle URL de dépôt ; les agents existants la réexécutent via `update.sh` à leur prochaine mise à jour de base
Clé API / webhook	Oui — renouvelez à tout moment
Tarification	Oui — s'applique aux futures commandes

Le verrouillage est appliqué à la fois dans l'UI (fieldset désactivé, bannière expliquant pourquoi) et sur le serveur (les POST vers /settings avec section=domain ou section=bot renvoient 403).

Webhooks + versements¶

Livraisons de webhooks — chaque événement de cycle de vie (commande créée, activée, expirée) est posté vers l'URL de webhook que vous définissez dans Settings. La puce Webhook health par partenaire du tableau de bord affiche le taux de succès de livraison sur les dernières 24 h.
Registre des revenus — chaque commande payée écrit une ligne avec votre brut, votre part et la part de mintbot. Le tableau de bord fait apparaître les totaux cumulés et le solde impayé.
Versements — s'accumulent. L'équipe mintbot les verse manuellement selon l'accord partenaire ; le tableau de bord suit le statut payé vs impayé.

Portail de référence¶

Si vous ne voulez pas construire une vitrine de zéro, forkez l'exemple officiel : mintbot-ai/partner-portal-example. C'est du FastAPI + SQLite + Docker sous licence MIT, livré avec une marque fictive « AcmeAI » que vous pouvez remplacer, et il couvre la boucle complète de bout en bout :

page d'accueil avec cartes de forfaits,
formulaire /buy → POST /api/v1/orders → redirection Stripe Checkout,
pages de retour remerciement / annulation,
POST /webhooks/mintoffice avec le vérificateur de signature HMAC,
navigateur d'événements /admin protégé par HTTP Basic auth,
sonde de vivacité /healthz.

Présentation de la configuration¶

Forkez le dépôt pour pouvoir conserver vos changements de marque dans git :

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

Remplissez .env avec les valeurs de votre tableau de bord MintOffice :

Variable	Ce qui va ici
`PARTNER_BRAND`	Nom de marque visible par le client (aussi utilisé comme libellé de ligne Stripe).
`MINTOFFICE_API_URL`	`https://mint.mintbot.ai` pour la production, `https://mint.mintbot.dev` pour les tests.
`MINTOFFICE_API_KEY`	Clé API depuis Settings → API access (format `mo_live_…`).
`MINTOFFICE_WEBHOOK_SECRET`	Secret de signature de webhook affiché une seule fois à la création dans le même tableau de bord.
`PUBLIC_BASE_URL`	L'URL HTTPS sur laquelle votre portail vivra (utilisée pour construire `success_url` / `cancel_url` Stripe).
`ADMIN_USERNAME` / `ADMIN_PASSWORD`	Barrière Basic-auth sur `/admin`. Utilisez un mot de passe long et aléatoire.

Lancez-le — Docker est le chemin le plus simple ; le bare-metal fonctionne aussi :
DockerPython local
docker compose up --build
pip install -e . uvicorn app.main:app --reload
Exposez-le en HTTPS — MintOffice rejette http:// à la fois pour les URL de redirection Stripe et l'URL de webhook (les IP privées et localhost sont bloquées par la protection SSRF). Pour le développement local, utilisez Cloudflare Tunnel, Tailscale Funnel ou ngrok. Pour la production, déployez sur votre propre hôte.
Pointez votre ligne partenaire vers le portail — de retour dans le tableau de bord :
- Définissez l'URL de webhook sur https://<your-host>/webhooks/mintoffice.
- C'est tout. Passez une commande de test depuis /buy, et regardez les événements arriver dans /admin.

Changement de marque¶

Les templates par défaut prétendent être AcmeAI. Trois points de contact :

PARTNER_BRAND dans .env — alimente Stripe, en-têtes, pieds de page.
app/templates/base.html — variables CSS pour les couleurs / la teinte d'accent.
app/templates/*.html — textes et mise en page par page. Les traductions (estonien, espagnol, …) vivent comme des forks de ces fichiers.

Déploiement rapide sur le même VPS que vos agents

Le portail d'exemple est assez petit pour tourner aux côtés de votre agent de déploiement MintOffice. Si vous avez déjà un VPS d'agent mintbot, demandez-lui : « Déploie partner-portal-example comme récepteur de webhook sous https://portal.<my-domain>/, remplis MINTOFFICE_API_KEY et MINTOFFICE_WEBHOOK_SECRET depuis GET /api/v1/settings, et définis l'URL de webhook sur ma ligne partenaire. » L'agent a la documentation et le chemin de la clé API pour faire cela de bout en bout.

Brand Partner API¶

Pour la création programmatique d'agents, le polling de statut et les événements de webhook, voir la référence Brand Partner API. Pour l'architecture plus large (comment votre vitrine, l'API, le worker de déploiement et le VPS d'agent de chaque client s'articulent), voir MintOffice — Technique.