Toolbox-Anleitung fuer Peter

1. Worum es geht

Die Toolbox ist das zentrale Betriebssystem von Kandlen IT: Kunden, Projekte, Tickets, Angebote, Rechnungen, Verträge, Zeitbuchungen, Wissensbibliothek und Lagebuch liegen dort in einer Datenbank. Sie läuft unter https://toolbox.kandlen-it.dev.

Peter ist als virtueller Mitarbeiter #7 im System hinterlegt und hat einen eigenen API-Token mit Leserechten. Damit kann Peter den aktuellen Stand des Betriebs selbst nachsehen, statt Jakob danach zu fragen — schreiben darf er nicht.

Grundregel Lesen ja, Ändern nein. Alles was in der Toolbox verändert werden soll, läuft über ein Ticket an Klaus oder über Jakob.

2. Zugang

Basis-URL	`https://toolbox.kandlen-it.dev/api/v1`
Authentifizierung	HTTP-Header `Authorization: Bearer kit_pat_…`
Token-Name	`peter-chatgpt-2026-08-17c`
Berechtigung	scope = read — nur GET
Gültig bis	15.11.2026
Antwortformat	JSON, UTF-8

Der Token steht bewusst nicht auf dieser Seite Jakob gibt ihn separat weiter. Er gehört in die Konfiguration des Zugriffs, nicht in einen Chatverlauf, nicht in ein Dokument und nicht in ein Repository. Wenn der Token abhandenkommt: sofort Jakob oder Klaus Bescheid geben, dann wird er widerrufen und ein neuer erzeugt.

Erste Prüfung: Wer bin ich?

curl -s -H "Authorization: Bearer kit_pat_DEIN_TOKEN" \
     https://toolbox.kandlen-it.dev/api/v1/me

Antwort, wenn alles stimmt:

{
  "id": 7,
  "vorname": "Peter",
  "kuerzel": "PET",
  "virtuell": true,
  "model_name": "gpt-5",
  "tool": "ChatGPT Web",
  "anbieter": "OpenAI",
  "plan": "Business",
  "aktiv": true
}

3. Was gelesen werden kann

Alle Endpunkte hängen an https://toolbox.kandlen-it.dev/api/v1 und werden per GET aufgerufen.

Betrieb und Arbeit

Endpunkt	Inhalt
`/me`	Eigenes Mitarbeiterprofil, Token-Prüfung
`/tickets`	Ticketliste, filterbar
`/tickets/{id}`	Einzelnes Ticket mit Details
`/projekte`, `/projekte/{id}`	Projekte
`/projekte/{id}/tickets`	Tickets eines Projekts
`/arbeitsprotokoll`	Arbeitsprotokoll-Einträge
`/arbeitsschritte`	Arbeitsschritte
`/buchungen`, `/buchungen/{id}`	Zeit- und Leistungsbuchungen
`/kalender`	Termine
`/erinnerungen`	Erinnerungen

Geschäftsdaten

Endpunkt	Inhalt
`/kunden`, `/kunden/{id}`	Kundenstammdaten
`/leads`	Leads / Interessenten
`/angebote`	Angebote
`/auftragsbestaetigungen`	Auftragsbestätigungen
`/rechnungen`	Rechnungen
`/vertraege`	Verträge und Abos
`/ausgaben`	Ausgaben
`/leistungen`, `/pakete`	Leistungskatalog, Pakete

Struktur und Wissen

Endpunkt	Inhalt
`/wissen`	Wissensbibliothek, Liste
`/wissen/kategorien`	Kategorien der Bibliothek
`/wissen/{slug}`	Einzelner Wissenseintrag
`/lagebuch/heute`	Team-Funk des laufenden Tages
`/lagebuch/{thread}`	Einzelner Lagebuch-Thread
`/mitarbeiter`, `/mitarbeiter/{id}`	Team, menschlich und virtuell
`/rollen`, `/kategorien`	Rollen, Ticketkategorien
`/bueros`, `/inventar`	Arbeitsumgebungen, Inventar
`/projekt-typen`, `/auftrag-arten`	Stammdaten-Listen
`/dokument-bloecke`	Textbausteine für Dokumente
`/projekt-anhaenge`, `/ticket-anhaenge`	Anhänge, Metadaten
`/key-inventar`	gesperrt nur für Schreib-Token

4. Beispiele

Offene Tickets ansehen

curl -s -H "Authorization: Bearer kit_pat_DEIN_TOKEN" \
     "https://toolbox.kandlen-it.dev/api/v1/tickets?status=neu&per_page=20"

{
  "data": [
    {
      "id": 1055,
      "nummer": 1017,
      "titel": "DRINGEND: Offener Adminer auf ...",
      "status": "neu",
      "prioritaet": "dringend",
      "projekt": "Website: ...",
      "zugewiesen_an": "Jakob"
    }
  ]
}

Wichtig bei Tickets: id ist der Datenbankschlüssel, nummer ist die Nummer, die in der Oberfläche und in der Kommunikation benutzt wird. In Texten immer die nummer nennen.

Blättern

Listen sind seitenweise. Steuerung über ?page=2 und ?per_page=50.

Wissenseintrag lesen

curl -s -H "Authorization: Bearer kit_pat_DEIN_TOKEN" \
     https://toolbox.kandlen-it.dev/api/v1/wissen/begleitmail-angebot

Tagesstand des Teams

curl -s -H "Authorization: Bearer kit_pat_DEIN_TOKEN" \
     https://toolbox.kandlen-it.dev/api/v1/lagebuch/heute

5. Fehlermeldungen

Code	Meldung	Bedeutung
`401`	Bearer kit_pat_… erforderlich	Header fehlt oder ist falsch geschrieben
`401`	Token ungültig oder widerrufen	Token abgelaufen, widerrufen oder vertippt — bei Jakob melden
`403`	Token hat nur Lesezugriff (scope=read)	Es wurde POST, PATCH oder DELETE versucht. Erwartetes Verhalten.
`403`	Mitarbeiter inaktiv	Der Mitarbeiterdatensatz wurde stillgelegt
`404`	—	Datensatz existiert nicht oder Endpunkt falsch geschrieben

6. Regeln für die Arbeit mit den Daten

Kein Kundenkontakt. Virtuelle Mitarbeiter treten nicht nach außen auf. Nach außen kommuniziert ausschließlich Jakob.
Keine Kundendaten weitertragen. Namen, Adressen, Verträge, Rechnungsdaten bleiben im Arbeitszusammenhang. Sie gehören nicht in Beispiele, nicht in geteilte Dokumente und nicht in andere Systeme.
Änderungen laufen über Tickets. Wenn etwas in der Toolbox angepasst werden soll: Ticket beschreiben und an Klaus geben, nicht selbst versuchen.
Ticketnummer statt Datenbank-ID in jeder Kommunikation.
Deutsch mit korrekten Umlauten, keine Emojis — gilt für alles, was ins System zurückfließt.
Stand prüfen statt raten. Die API liefert den Live-Stand. Was älter als der letzte Abruf ist, kann überholt sein.

Bekannte Einschränkung Der Lesezugriff ist derzeit nicht nach Bereichen begrenzt: ein Lese-Token sieht alle über die API v1 erreichbaren Geschäftsdaten. Eine feinere Bereichssperre ist geplant. Bis dahin gilt Zurückhaltung: nur abrufen, was für die jeweilige Aufgabe gebraucht wird.

7. Hilfe

Token funktioniert nicht, Endpunkt fehlt, Antwort sieht falsch aus: Ticket an Klaus (Mitarbeiter #2) oder Jakob direkt ansprechen.
Neuer Token nötig: nur Jakob oder Klaus erzeugen Tokens, niemals aus einem Chat heraus.
Diese Seite wird bei Änderungen an der API nachgezogen. Änderungsstand steht unten.