SUPERINTELLIGENTHUB DOKUMENTATION

Abos, Botkäufe und Kontaktformular einrichten

SuperIntelligentHub bietet wiederkehrende Abos und einmalige Botkäufe über Stripe Checkout. Zahlungsdaten werden auf der Stripe-Seite eingegeben; SIHub speichert Bestellungen, Zahlungsstatus, Abos und Botzuordnungen in MariaDB. Das Kontaktformular speichert Anfragen ebenfalls in MariaDB und stellt sie per SMTP an deine feste Kontaktadresse zu; offene Zustellungen übernimmt der getrennte Mailworker.

Die Integration ist im Repository vorbereitet. Neue Kaufabschlüsse bleiben zunächst mit SIHUB_COMMERCE_ENABLED=0 ausgeschaltet. Deine tatsächlichen Preise, Stripe-Schlüssel und das SMTP-Passwort ergänzt du in der privaten Betreiberdatei. Es sind keine Verkaufspreise vorgegeben.

SIHUB_COMMERCE_ENABLED=0 sperrt neue Kaufabschlüsse. Bereits bestehende Stripe-Abos laufen weiter, bis sie im Kundenportal oder Stripe-Dashboard wirksam gekündigt werden. Bei weiterhin konfigurierten Zahlungszugängen bleibt das Kundenportal für bestehende Kunden erreichbar.

1. Die richtige Betreiberdatei bearbeiten

Betrieb	Datei	Anwendung der Änderung
Apache + systemd	`/etc/sihub/sihub.env`	`sudo systemctl restart sihub`
Docker	`/var/www/SIHub/deploy/.env.production`	Appcontainer neu erzeugen, siehe Schritt 6
Lokale Pythoninstallation	`/var/www/SIHub/.env`	App neu starten

Bewahre Schlüssel und Passwörter ausschließlich in dieser geschützten Datei auf. Trage sie weder in Apache-VirtualHosts noch in das Git-Repository oder einen Chat ein. Die Beispiel-Dateien enthalten nur bekannte Serverwerte und leere Schlüsselfelder. Bestehende Betreiberdateien werden beim Update beibehalten; ergänze die neuen Variablen dort selbst. DATABASE_URL und vorhandene Telefonieschlüssel bleiben deine bestehenden Betreiberwerte.

2. Stripe zuerst in der Testumgebung vorbereiten

Öffne dein Stripe-Dashboard und wähle die Testumgebung bzw. deine Sandbox.
Hinterlege die öffentliche Marke SuperIntelligentHub, deine tatsächlichen Unternehmensdaten und die Supportadresse kontakt@sihub.at.
Übernimm den geheimen Test-API-Schlüssel in SIHUB_STRIPE_SECRET_KEY. Ein Secret Key beginnt typischerweise mit sk_test_; der öffentliche pk_-Schlüssel wird für diese gehostete Checkoutintegration nicht benötigt. Test- und Liveschlüssel greifen auf getrennte Daten zu. Stripe-API-Schlüssel
Lass SIHUB_COMMERCE_ENABLED=0, bis Produkte, Webhook und Portal eingerichtet sind.

3. Deine Abopreise und Botprodukte anlegen

Erstelle im Stripe-Produktkatalog die folgenden Produkte mit deinen eigenen EUR-Beträgen. Verwende bei Abos einen wiederkehrenden Preis mit monatlicher oder jährlicher Abrechnung und bei Bots einen einmaligen Preis. Kopiere jeweils die Preis-ID price_…, nicht die Produkt-ID prod_…. Stripe-Produkte und Preise

SIHub-Angebot	Stripe-Preistyp	Variable in deiner Betreiberdatei
SuperIntelligentHub Starter	Wiederkehrend, EUR	`SIHUB_STRIPE_PRICE_STARTER`
SuperIntelligentHub Team	Wiederkehrend, EUR	`SIHUB_STRIPE_PRICE_TEAM`
Service-Bot	Einmalig, EUR	`SIHUB_STRIPE_PRICE_BOT_SERVICE`
Empfangs-Bot	Einmalig, EUR	`SIHUB_STRIPE_PRICE_BOT_RECEPTION`
Lead-Bot	Einmalig, EUR	`SIHUB_STRIPE_PRICE_BOT_LEADS`

AIHUB_PUBLIC_URL=https://sihub.at
SIHUB_COMMERCE_ENABLED=0
SIHUB_STRIPE_SECRET_KEY=
SIHUB_STRIPE_WEBHOOK_SECRET=
SIHUB_STRIPE_PRICE_STARTER=
SIHUB_STRIPE_PRICE_TEAM=
SIHUB_STRIPE_PRICE_BOT_SERVICE=
SIHUB_STRIPE_PRICE_BOT_RECEPTION=
SIHUB_STRIPE_PRICE_BOT_LEADS=
SIHUB_STRIPE_PORTAL_CONFIGURATION=
SIHUB_STRIPE_AUTOMATIC_TAX=0

SIHub liest die angezeigten Preise aus den zugeordneten Stripe-Preisobjekten. Eine leere Preis-ID macht das betreffende Angebot nicht kaufbar. Der Shop steht unter https://sihub.at/shop; Arbeitsbereichsbetreiber verwalten Bestellungen, Abostatus und den Zugang zum Stripe-Kundenportal unter https://sihub.at/account/billing. Ein gekaufter Bot wird einmal je Angebot und Arbeitsbereich als bearbeitbarer Agentenentwurf angelegt. Anbieterzugänge, Wissen und Veröffentlichung richtest du anschließend für deinen konkreten Einsatz ein; Livekanäle und Anrufe werden durch einen Kauf nicht automatisch aktiviert. Der Botpreis ersetzt keine laufenden Telefonie-/KI-Kosten.

Definiere vor dem Verkauf deine tatsächlichen Leistungsbeschreibungen, Vertragsbedingungen und Steuerdarstellung. Die mitgelieferten rechtlichen Seiten sind Betreibervorlagen. Die optionale Variable SIHUB_STRIPE_AUTOMATIC_TAX=1 verwendest du erst, wenn deine Stripe-Tax-Einstellungen und erforderlichen Registrierungen eingerichtet sind; ohne diese Einrichtung bleibt sie 0. Stripe Tax mit Checkout

4. Den Zahlungswebhook einrichten

Die HTTPS-Seite muss öffentlich erreichbar sein. Öffne in Stripe Workbench → Webhooks → Ereignisziel erstellen, wähle Dein Konto und das Format Snapshot. Verwende die API-Version 2025-02-24.acacia, auf die diese Integration ausgelegt ist. Zieladresse:

https://sihub.at/hooks/stripe

Wähle genau diese Ereignisse:

checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
checkout.session.expired
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed
charge.refunded

Übernimm den Signaturschlüssel dieses Ziels (whsec_…) in SIHUB_STRIPE_WEBHOOK_SECRET. Ein Testziel, ein Liveziel und ein lokaler Stripe-CLI-Listener haben jeweils eigene Signaturschlüssel. SIHub prüft die Signatur und verarbeitet Ereignisse wiederholbar, damit erneute Zustellungen keinen zweiten Bot erzeugen. Stripe-Webhooks einrichten

Die Bestätigungsseite allein schaltet keine Bestellung frei. Maßgeblich ist die bestätigte Zahlung; bei verzögerten Zahlungsmethoden bleibt sie bis zur Erfolgsbestätigung offen. Stripe stellt fehlgeschlagene Webhookzustellungen erneut zu; kontrolliere den Zustellstatus im Stripe-Dashboard. Checkoutbestellungen automatisch erfüllen

5. Abos selbst verwalten lassen

Aktiviere in Stripe Einstellungen → Billing → Kundenportal die Aktualisierung von Zahlungsmethoden, Rechnungsübersicht und Abokündigung. Lege ausdrücklich fest, ob eine Kündigung zum Ende des bezahlten Zeitraums erfolgt. Die wiederkehrende Zahlung läuft bis zur wirksamen Kündigung nach deiner Stripe-Konfiguration weiter. Hinterlege dein Branding und Links auf deine ausgefüllten Vertrags-/Datenschutzseiten. Stripe-Kundenportal konfigurieren

SIHUB_STRIPE_PORTAL_CONFIGURATION bleibt leer, wenn SIHub die Standardkonfiguration des Stripe-Kontos nutzen soll. Für eine bestimmte Portalkonfiguration trägst du deren bpc_…-ID ein. Lass Preis-/Planwechsel im Kundenportal ausgeschaltet: Die bestehende Bestellung ist an ihre Preis-ID gebunden. Für einen Tarifwechsel kündigst du das aktuelle Abo und kaufst den neuen Tarif nach dessen wirksamem Ende. Die Portaloptionen werden in Stripe verwaltet. Eine Erstattung allein beendet kein Stripe-Abo; die Kündigung erfolgt separat. Bei einem vollständig erstatteten Botkauf wird dessen Lizenz aufgehoben, vorhandene Agenten und eigene Bearbeitungen bleiben erhalten.

6. App aktualisieren und einen Testkauf durchführen

Nach dem Repository-Update ergänzt der normale Schemaabgleich die neuen MariaDB-Tabellen automatisch. Im direkten Apachebetrieb:

cd /var/www/SIHub
sudo bash apache2/install.sh prepare
sudoedit /etc/sihub/sihub.env
# Nur mit vollständigen Testschlüsseln/Preisen: SIHUB_COMMERCE_ENABLED=1 setzen.
sudo bash apache2/install.sh manage check-config
sudo systemctl restart sihub
sudo bash apache2/install.sh manage schema-status

Im Dockerbetrieb ergänzt du dieselben Variablen in deploy/.env.production. Die Voiceworker brauchen keine Stripe-/SMTP-Schlüssel. Neue Codeabhängigkeiten und Umgebungswerte werden so übernommen:

cd /var/www/SIHub
sudoedit deploy/.env.production
sudo docker compose --env-file deploy/.env.production -f deploy/compose.yml up -d --build --force-recreate app
sudo docker compose --env-file deploy/.env.production -f deploy/compose.yml run --rm --no-deps app python manage.py schema-status

Ein bloßes docker compose restart übernimmt keine geänderten Umgebungswerte. Melde dich mit einem regulären Betreiberkonto des zu kaufenden Arbeitsbereichs an, öffne /shop, durchlaufe mit den Testschlüsseln einen Abokauf und einen Botkauf und kontrolliere danach den Webhookstatus, die Bestellung unter /account/billing und den angelegten Botentwurf. Nutze ausschließlich Stripe-Testzahlungsdaten aus der offiziellen Testanleitung. Prüfe auch Abbruch, Kündigung und eine erneute Zustellung desselben Ereignisses. SIHub speichert den tatsächlichen Abostatus; eigene Tarifgrenzen oder Telefoniekontingente werden durch diese Integration nicht automatisch festgelegt.

Für den Liveverkauf legst du Produkte/Preise und das Ereignisziel separat im Livemodus an. Ersetze Test-Key, alle price_…-IDs und Webhooksignaturschlüssel durch die entsprechenden Livewerte und aktiviere SIHUB_COMMERCE_ENABLED=1. Ab diesem Zeitpunkt führt ein erfolgreicher Kauf echte Zahlungen aus. Stripe übernimmt den Zahlungseinzug; SMTP ist davon unabhängig.

7. Kontaktformular und Mailversand konfigurieren

Die folgenden bekannten Werte sind bereits in den Beispiel-Dateien gesetzt:

SIHUB_CONTACT_ENABLED=1
SIHUB_CONTACT_TO=kontakt@sihub.at
AIHUB_SMTP_HOST=mail.heartfrequency.solutions
AIHUB_SMTP_PORT=587
AIHUB_SMTP_STARTTLS=1
AIHUB_SMTP_SSL=0
AIHUB_SMTP_USER=office@sihub.at
AIHUB_SMTP_PASSWORD=
AIHUB_SMTP_FROM=kontakt@sihub.at

Trage das SMTP-Passwort ausschließlich in deine private Betreiberdatei ein. Port 587 verwendet STARTTLS, nicht implizites SSL. Das Mailkonto office@sihub.at muss beim Mailserver als Absender kontakt@sihub.at senden dürfen. Richte dafür bei Bedarf die entsprechende Alias-/Absenderfreigabe und ein tatsächlich empfangendes Postfach für kontakt@sihub.at ein. Das Kontaktformular steht unter https://sihub.at/contact. Der dort angegebene Besucher wird als Antwortadresse verwendet; SIHub sendet ihm keine automatische Nachricht.

Kontrolliere die für sihub.at vom Mailanbieter vorgegebenen SPF-/DKIM-Einträge, damit Nachrichten mit diesem Absender zugestellt werden können. Übernimm dessen konkrete DNS-Werte. Apache, Certbot und SIHub erzeugen diese Mail-DNS-Werte nicht.

Die Formularbestätigung bedeutet: Anfrage wurde gespeichert. Mit vollständiger SMTP-Konfiguration versucht SIHub direkt nach dem Speichern einen Versand. Fehlt das Passwort oder ist die Zustellung noch offen, bleibt die Anfrage in der Versandwarteschlange; der Mailworker übernimmt sichere Wiederholungen. Ein unklarer Zustellstatus wird bewusst nicht automatisch erneut versendet. Du kannst das Kontaktformular bei Bedarf mit SIHUB_CONTACT_ENABLED=0 ausschalten. Der Empfang von Kontaktanfragen erfordert keine Stripekonfiguration und keine Telefonie-Livefreigabe.

SMTP-Diagnose im SIHub-Apache-Fehlerlog

Im direkten Apachebetrieb schreiben SIHub und der Mailworker die Versanddiagnose in /var/log/sihub/error.log, das auch als ErrorLog der SIHub-VirtualHosts verwendet wird. Für eine vorhandene Installation aktivierst du diese gemeinsame Ausgabe nach dem Codeupdate einmal:

cd /var/www/SIHub
sudo bash apache2/install.sh logging
sudo tail -F /var/log/sihub/error.log

Danach kannst du eine eigene Kontaktanfrage abschicken und im selben Log den Versandversuch verfolgen. Die Diagnose enthält SMTP-Verbindungs- und Versandstatus, die fehlende Konfiguration oder einen Fehler mit seiner Versandphase. Passwörter, Authentifizierungsdaten und Kontaktinhalte werden nicht ausgegeben. Eine erfolgreiche SMTP-Übergabe bedeutet, dass der Mailserver die Nachricht angenommen hat; die weitere Zustellung prüfst du beim Mailanbieter und im Zielpostfach. Vorherige Apache-Fehler bleiben in /var/log/apache2/sihub-error.log erhalten. Details zu Rechten, Rotation und Dienstneustart stehen in der Apache-Anleitung.

Der Mailworker verwendet bei systemd automatisch dieselbe Logdatei. In Docker oder bei lokaler Ausführung findest du die SMTP-Einträge in der Standardfehlerausgabe; mit SIHUB_LOG_FILE kannst du zusätzlich eine für den jeweiligen Anwendungsbenutzer beschreibbare Datei wählen.

Bei einer Ablehnung protokolliert SIHub zusätzlich das SMTP-Kommando und einen aus bekannten Servermeldungen abgeleiteten reason_hint. smtp_command=rcpt bedeutet, dass der Mailserver den Empfänger beim SMTP-Versand abgelehnt hat. Dabei kann er auch Regeln für den Absender prüfen. Die Hinweise helfen bei der Eingrenzung:

`reason_hint`	Prüfung beim Mailanbieter
`relay_denied`	Darf das angemeldete Konto an die Zieldomain senden? Ist die Domain auf dem richtigen Mailserver eingerichtet?
`sender_unauthorized`	Darf `office@sihub.at` als `kontakt@sihub.at` senden? Ist die Alias-/Absenderfreigabe eingerichtet?
`recipient_unknown`	Existiert `kontakt@sihub.at` als Postfach oder empfangender Alias?
`sender_rejected`	Welche Absenderprüfung wurde abgelehnt? Die Meldung allein beweist keine fehlende Aliasfreigabe.
`access_policy` oder `unknown`	Vollständige Ablehnung im Mailserverlog prüfen; die Serverantwort enthält keinen sicher erkannten genaueren Grund.

553 / 5.7.1 nach erfolgreichem auth ... smtp_status=235 zeigt eine Versandablehnung trotz erfolgreicher Anmeldung. Der erweiterte Code bezeichnet eine fehlende Zustellberechtigung und kann durch Absender-, Host- oder Empfängerregeln ausgelöst werden; er beweist kein fehlendes Postfach. SMTP-Statuscodes, RFC 3463 Abschnitt 3.8 SIHub gibt nur feste Diagnosewerte aus, nicht den Rohtext der Serverantwort. Nach Behebung des Mailserverproblems muss eine als failed gespeicherte Anfrage ausdrücklich über contact-retry erneut vorgemerkt werden; Abschnitt 9 zeigt die Befehle.

8. Mailworker aktivieren und Zustellung prüfen

Führe nach dem Eintragen des SMTP-Passworts einen eigenen Formulartest mit einer kontrollierten Antwortadresse durch. Prüfe die gespeicherte Anfrage und starte den Worker einmal:

cd /var/www/SIHub
sudo bash apache2/install.sh manage check-config --mail
sudo bash apache2/install.sh manage contact-list
sudo bash apache2/install.sh manage notify-worker --limit 20
sudo bash apache2/install.sh manage contact-list

Für den regelmäßigen Versand im direkten Apachebetrieb installierst du den mitgelieferten Minuttimer. Der interne Dienstname aihub-notifications bleibt aus Kompatibilitätsgründen bestehen; Dienstbenutzer, Arbeitsordner, Pythonumgebung und Betreiberdatei verwenden SIHub:

sudo install -m 0644 apache2/aihub-notifications.service /etc/systemd/system/aihub-notifications.service
sudo install -m 0644 apache2/aihub-notifications.timer /etc/systemd/system/aihub-notifications.timer
sudo systemctl daemon-reload
sudo systemctl enable --now aihub-notifications.timer
sudo systemctl list-timers aihub-notifications.timer
sudo journalctl -u aihub-notifications.service -n 50 --no-pager

Der Worker verarbeitet Kontaktanfragen und die vorhandene Benachrichtigungs-Outbox. Im Dockerbetrieb verwendest du stattdessen den Composeworker und dessen Timer:

cd /var/www/SIHub
sudo docker compose --env-file deploy/.env.production -f deploy/compose.yml run --rm --no-deps notifications
sudo install -m 0644 deploy/systemd/aihub-compose-notifications.service /etc/systemd/system/aihub-compose-notifications.service
sudo install -m 0644 deploy/systemd/aihub-compose-notifications.timer /etc/systemd/system/aihub-compose-notifications.timer
sudo systemctl daemon-reload
sudo systemctl enable --now aihub-compose-notifications.timer
sudo systemctl list-timers aihub-compose-notifications.timer

Nutze den Timer deines gewählten Betriebswegs. Eine erfolgreiche SMTP-Übergabe ist noch keine Garantie für den Postfacheingang; prüfe das Zielpostfach und gegebenenfalls den Mailserverzustellbericht. Der Mailworker ruft deinen SMTP-Server tatsächlich auf und kann E-Mails versenden.

9. Eine fehlgeschlagene Kontaktzustellung bearbeiten

contact-list zeigt Anfrage-ID, Zeit, Status und Versuchsanzahl ohne Nachrichteninhalt. Eine bestimmte Anfrage kannst du bewusst anzeigen und nach Fehlerbehebung erneut vormerken:

sudo bash /var/www/SIHub/apache2/install.sh manage contact-show --id ANFRAGE_ID
sudo bash /var/www/SIHub/apache2/install.sh manage contact-retry --id ANFRAGE_ID
sudo bash /var/www/SIHub/apache2/install.sh manage notify-worker --limit 20

Bei unklarem SMTP-Ergebnis (unknown) prüfst du zuerst beim Mailanbieter, ob die Nachricht bereits angenommen wurde. Erst wenn eine erneute Zustellung sinnvoll ist, erlaubt contact-retry --id ANFRAGE_ID --confirm-unknown die bewusste Wiederholung. So vermeidest du versehentliche Doppelzustellungen nach einem Verbindungsabbruch.

Bei Docker ersetzt du den Verwaltungspräfix durch sudo docker compose --env-file deploy/.env.production -f deploy/compose.yml run --rm --no-deps app python manage.py. Kontaktinhalte können personenbezogene Daten enthalten; leite vollständige CLI-Ausgaben nicht in öffentliche Logs weiter. Regelmäßige Datenbanksicherungen umfassen auch diese Anfragen und die Kauf-/Abodaten.

← Alle Artikel OpenAPI-Spezifikation ↗