Verbinde deinen Assistenten mit bexio.

Was das bringt

«Wie viele Rechnungen sind noch offen?»

Voraussetzungen

• Ein Assistent, der auf deine Dateien zugreifen und Programme ausführen darf. Welche App du dafür nutzt, spielt keine Rolle. Ein Chat ohne Zugriff auf deine Dateien reicht nicht.
• Ein bexio-Konto. Zum Erstellen des Zugangs brauchst du Administratorrechte.

Was du danach kannst

Grenzen, ehrlich

• Das Personal Access Token läuft nach 60 Tagen ab und muss dann neu erstellt werden. Mit OAuth musst du nicht alle 60 Tage ein neues Personal Access Token anlegen. Der OAuth-Zugang kann trotzdem widerrufen werden oder aus anderen Gründen ausfallen.
• Versand-Operationen verweigert das Programm ohne --force. Das ist Absicht: verschicken bleibt ein bewusster Entscheid.
• Dein Assistent macht Fehler wie ein neuer Mitarbeiter. Darum gilt: anlegen ja, aber du gibst frei.

Anleitung für deinen Assistenten

1. 1

   Im Assistenten einrichten

   Dieser Workflow gehört zum Thema Finanzen. Er liegt danach in 01_finanzen/workflows/bexio/, bei jeder Person am selben Ort.

   1. Prüfe, ob du in einem Assistenten arbeitest. Im geöffneten Ordner liegen AGENTS.md und CONTEXT.md, und in CONTEXT.md steht eine Tabelle mit der Kopfzeile | Aufgabe | Ordner | Status |. Fehlt das, sag der Person, dass der Gratis-Starter von wirdrei.digital diesen Rahmen einrichtet: https://wirdrei.digital/assistent. Frag sie, ob sie zuerst den Starter einrichten oder ohne ihn weitermachen will. Ohne Starter legst du einen neuen, leeren Unterordner an, dessen Namen die Person bestätigt, und arbeitest nur darin: Alle Pfade dieser Anleitung liegen dann in diesem Unterordner, nichts ausserhalb wird angefasst. Weg fallen dabei die Router-Zeilen und der Eintrag in CHANGELOG.md (Punkte 2 und 3), die Vorlagen aus dem Skill workflow-builder, _setup/werkzeuge.md, support.md und die Pflege. Die CONTEXT.md aus Schritt 2 schreibst du selbst, und was sonst in _setup/werkzeuge.md stünde (installierte Pakete und Skripte, Ort von Python), hältst du dort unter «Quellen» fest. Wo diese Anleitung auf support.md verweist, nennst du https://wirdrei.digital/kontakt.

   2. Bereich anlegen, falls er fehlt. Kopiere assets/bereich-CONTEXT.md aus dem Skill workflow-builder deines Assistenten nach 01_finanzen/CONTEXT.md und fülle {{BEREICH}} mit 01_finanzen und {{THEMA}} mit Finanzen. Wo der Skill liegt, steht im Haupt-Router CONTEXT.md in der Zeile «Eigenen Workflow bauen». Trag den Bereich direkt unter der letzten Zeile der Tabelle im Haupt-Router ein:

      | Finanzen | `01_finanzen/` | eingerichtet |
      

   3. Workflow anlegen. Gibt es 01_finanzen/workflows/bexio/ schon, frag, ob du ihn ergänzen sollst, und überschreib nichts. Sonst kopierst du assets/workflow-CONTEXT.md aus demselben Skill nach 01_finanzen/workflows/bexio/CONTEXT.md. Den Inhalt liefert Schritt 2. Trag den Workflow direkt unter der letzten Zeile der Tabelle von 01_finanzen/CONTEXT.md ein, mit der Aufgabe in den Worten der Person:

      | <Aufgabe> | `workflows/bexio/` | eingerichtet |
      

      Halte die Einrichtung zuoberst in CHANGELOG.md fest: Datum, was, warum und der Rückweg (den Ordner 01_finanzen/workflows/bexio/ und seine Router-Zeilen löschen).

   4. Gemeinsames liegt an einem Ort. Schreibstil steht nur in _marke/voice.md, Firmendaten nur in _marke/firmendaten.md. Braucht dieser Workflow eine davon und sie fehlt, kopierst du assets/marke-voice.md oder assets/marke-firmendaten.md aus dem Skill workflow-builder dorthin. Sie bleiben ENTWURF, bis die Person zustimmt. Python-Pakete installierst du nur, wenn dieser Workflow sie nennt, prüfst vorher in _setup/werkzeuge.md, ob sie schon da sind, und trägst sie dort ein. Dort stehen auch die Pfade von uv, Python und dem Laufzeitordner: Wo diese Anleitung "<uv>", "<python>" oder "<laufzeitordner>" schreibt, setzt du den Pfad von dort ein, immer in Anführungszeichen, denn er enthält oft Leerzeichen. In PowerShell steht & vor dem ersten Pfad eines Befehls. Schlüssel und Passwörter gehören nie in den Assistenten-Ordner und nie in den Chat. Braucht dieser Workflow einen, legst du die Datei "<laufzeitordner>/secrets/<dienst>.env" mit leeren Werten an und öffnest sie für die Person, ohne auf das Schliessen des Editors zu warten: auf dem Mac mit open -e "<datei>", auf Windows in Git Bash mit start "" notepad "<datei>" und in PowerShell mit Start-Process notepad "<datei>". Sie trägt die Werte ein und speichert, du liest sie nie in den Chat. Programme mit eigener Anmeldung behalten den Zugang in ihrem eigenen Speicher, wenn dieser Workflow das so vorsieht.

   5. Zum Schluss kommt der Test mit echten Daten, danach bietest du den Skill pflege an (letzter Schritt).

2. 2

   Vertrag ausfüllen

   Füll die CONTEXT.md so aus. Was in eckigen Klammern steht, klärst du mit der Person:

   # bexio-Anbindung
   
   **Status: eingerichtet** (aktiv erst nach einem sauberen echten Durchlauf)
   **Auslöser:** Die Person fragt nach Rechnungen, Offerten, Kontakten oder Projekten in bexio.
   Pfade in diesem Vertrag liegen in `01_finanzen/workflows/bexio/`, ausser sie beginnen mit `_marke/`, `_setup/` oder einer Bereichsnummer.
   
   ## Zweck
   
   [Wofür vor allem: Rechnungen, Offerten, Kontakte?] Gelesen und vorbereitet wird über das
   Programm `bexio` (bexio-cli von wirdrei.digital).
   
   ## So arbeitest du
   
   1. Lesen geht ohne Rückfrage: `"<bexio>" commands --json` zeigt alle Befehle.
   2. Anlegen und Ändern: erst den Entwurf im Chat zeigen, dann auf ein ausdrückliches Ja
      warten, dann ausführen.
   3. Versand-Operationen (zum Beispiel eine Rechnung verschicken) verweigert das Programm
      ohne `--force`. `--force` setzt du nur nach einem eigenen Ja für genau diesen Versand.
   4. Meldet das Programm einen abgelaufenen Zugang, sag es der Person und lass sie `"<bexio>" init`
      im Terminal neu ausführen.
   
   ## Quellen
   
   | Was                                                | Wo                 | Zugriff                      |
   | -------------------------------------------------- | ------------------ | ---------------------------- |
   | Kontakte, Rechnungen, Offerten, Aufträge, Projekte | bexio über `bexio` | lesen, anlegen nach Freigabe |
   
   Der Zugang liegt im eigenen Speicher des Programms (`"<bexio>" init`, Dateirechte 0600),
   nie hier und nie im Chat.
   
   ## Ausgabe
   
   Antworten im Chat, Entwürfe im Chat und nach Freigabe die Einträge in bexio.
   
   ## Grenzen
   
   - Schreibt nicht in den Assistenten-Ordner, ausser in diese `CONTEXT.md`.
   - Beträge und Kundendaten stammen aus bexio oder von der Person, nie geschätzt.
   - Senden, Löschen und Bezahlen braucht jedes Mal ein eigenes Ja.
   - Zugang: [Personal Access Token, gültig bis JJJJ-MM-TT, oder OAuth]
   
   ## Test
   
   [Datum des ersten sauberen Lese-Aufrufs]
   

   Frag die Person nach dem Zweck und lass sie die Regeln bestätigen, bevor du den Zugang einrichtest.

3. 3

   Programm installieren

   Lade von https://github.com/wir-drei-digital/bexio-cli/releases/latest das Archiv für das System dieses Computers (macOS und Linux als .tar.gz für amd64 und arm64, Windows als .zip). Prüfe den Download gegen checksums.txt und entpacke das Archiv in einen leeren Ordner "<laufzeitordner>/downloads/bexio/". Kopiere daraus nur das Programm bexio (auf Windows bexio.exe) nach "<laufzeitordner>/bin/", wo auch uv liegt. Trag den vollen Pfad in _setup/werkzeuge.md ein, etwa "<laufzeitordner>/bin/bexio". Das ist ab jetzt "<bexio>": Du rufst das Programm immer mit diesem Pfad in Anführungszeichen auf und änderst keine Systemeinstellungen.

   Alternative, falls eine Go-Toolchain da ist: GOBIN="<laufzeitordner>/bin" go install github.com/wir-drei-digital/bexio-cli/cmd/bexio@latest (in PowerShell setzt du vorher $env:GOBIN="<laufzeitordner>\bin").

   Prüfe die Installation mit "<bexio>" --version und trag Programm und Version in _setup/werkzeuge.md ein.

4. 4

   Zugang wählen

   Frag die Person, welcher Zugang passt:

   • Personal Access Token In bexio erstellt und 60 Tage gültig. Gut für einen zeitlich begrenzten Test.
   • OAuth Verlangt eine App-Registrierung auf https://developer.bexio.com. Das Programm erneuert den Zugriff mit dem Refresh-Token, solange bexio diesen Zugang nicht widerruft. Die nötigen Redirect-URLs stehen im README des Programms.

   Wichtig: Die Person tippt ihr Token nie in den Chat. "<bexio>" init fragt es direkt im Terminal ab und speichert es lokal mit Dateirechten 0600.

5. 5

   Zugang speichern

   Lass die Person "<bexio>" init im Terminal ausführen. Gib ihr dafür den Befehl mit dem vollen Pfad aus _setup/werkzeuge.md, in PowerShell mit & davor. Der Einrichtungsdialog sammelt den Zugang ein und prüft ihn gleich mit einem einzigen Lese-Aufruf.

   Beim Personal Access Token: Trag das Ablaufdatum (heute plus 60 Tage) unter «Grenzen» in der CONTEXT.md ein. Weise bei späteren Aufrufen darauf hin, sobald weniger als sieben Tage bleiben.

6. 6

   Mit einem Lese-Aufruf testen

   Mach einen Lese-Aufruf und zeig der Person das Ergebnis:

   "<bexio>" contacts list --limit 10
   

   Kommt eine Liste zurück, steht die Anbindung.

7. 7

   Abschliessen

   Lief der Test sauber, setzt du den Status auf aktiv: in 01_finanzen/workflows/bexio/CONTEXT.md, in der Zeile von 01_finanzen/CONTEXT.md und beim Bereich im Haupt-Router, falls dort noch eingerichtet steht. Halte das Datum des Durchlaufs im Abschnitt «Test» fest. Lief er nicht sauber, bleibt der Status eingerichtet, und du korrigierst die Regel in der CONTEXT.md, nicht nur das einzelne Ergebnis.

   Frag danach: «Soll ich kurz prüfen, ob alles sauber eingehängt ist?» Sagt die Person ja, startest du den Skill pflege. Ohne Assistenten-Rahmen (siehe Schritt 1) entfallen Router und Pflege.