Assistent: Tagesüberblick, Termine anlegen, Kundenakte

Ein Assistent kann dir Termine, freie Zeiten und Kundendaten nennen. Diese Seite erklärt die dafür vorgesehenen Aufrufe und das Anlegen mit Vorschau.

Begriffe: API bedeutet Schnittstelle für andere Programme. Ein Endpunkt ist eine bestimmte Abrufadresse. JSON ist das Textformat der Antworten; eine Kennung (id) bezeichnet einen Eintrag.

Die Antworten sind kurz: Namen statt Kennungen, nur gefüllte Felder. Du kannst die Aufrufe auch aus jedem anderen Programm nutzen.

Lesen

Jede Antwort beginnt mit heute (Datum, Wochentag, Uhrzeit). Termine tragen den Wochentag im Feld tag. Datum gibst du immer als JJJJ-MM-TT an, Uhrzeiten als HH:MM. Texte, die Kunden selbst geschrieben haben (Anfragetexte, Kommentare), kommen hier nie mit — nur Namen, Zahlen, Daten und Zustände.

So legst du einen Termin mit Vorschau an

1. Ermittle zuerst Kunde, Leistung und gegebenenfalls Tier sowie Mitarbeiter.
2. Sende den Aufruf ohne ausfuehren.
3. Prüfe Datum, Uhrzeit, Zahlweg und Konflikte in der Antwort.
4. Wiederhole erst nach deiner Bestätigung den Aufruf mit "ausfuehren": true.

Sechs Aktionen legen an oder ändern etwas: POST /api/v1/coachingappointments/anlegen (Einzeltermin), POST /api/v1/coachingappointments/{id}/verschieben, POST /api/v1/coachingappointments/{id}/serie (wiederkehrende Termine), POST /api/v1/groupappointments/anlegen (Gruppentermin), POST /api/v1/contacts/anlegen (Kunde) und POST /api/v1/pets/anlegen (Tier).

Alle folgen demselben Muster. Ohne "ausfuehren": true passiert nichts — du bekommst die aufgelöste Zusammenfassung zurück und siehst, was angelegt würde:

Was macht das? Dieser Aufruf zeigt nur eine Vorschau für einen Einzeltermin. Darunter steht eine beispielhafte Antwort.

POST /api/v1/coachingappointments/anlegen
{ "id_customer": 4711, "id_service": 55, "datum": "2026-09-15", "uhrzeit": "10:00" }

→ { "probelauf": true, "gespeichert": false,
    "termin": { "tag": "Di 15.09.2026", "von": "10:00", "bis": "11:00",
                "leistung": "Physio", "kunde": "Meier, Anna", "tier": "Bello",
                "mitarbeiter": "Muster, Maxine", "ort": "Praxis",
                "zahlweg": "Stempelkarte „Physio 10er“ (noch 4 von 10, nach dem Termin 3)" },
    "naechster_schritt": "Zum Speichern denselben Aufruf mit \"ausfuehren\": true wiederholen." }

Derselbe Aufruf mit "ausfuehren": true legt den Termin an — genau so, wie es das Formular in der Software täte: Terminart und Dauer kommen aus der Leistung, der Zahlweg läuft über Abo, Stempelkarte oder Rechnungsposition, Kalender werden nachgezogen. Was dabei nicht passiert: Es geht keine Terminbestätigung an den Kunden. Wenn du eine willst, verschickst du sie aus der Software.

Ein paar Regeln, die dir Arbeit abnehmen:

• Hat der Kunde genau ein Tier, wird es genommen. Hat er mehrere, bekommst du ohne id_pet eine Rückfrage mit der Liste. Gib dann id_pet für das erste Tier an. Weitere Tiere desselben Kunden ergänzt du mit "weitere_tiere": [12, 13]. Die Abrechnung richtet sich weiterhin nach dem ersten Tier.
• Der Mitarbeiter ist, wenn du nichts angibst, der Inhaber des Schlüssels.
• Überschneidungen (Mitarbeiter, Ort), Urlaub und Sperrzeiten stehen unter konflikte. Beim Ausführen blocken sie mit dem Fehler 409 — außer du gibst "trotzdem": true mit.
• Ein zweiter Aufruf mit gleichem Kunden, gleicher Leistung und gleichem Zeitpunkt legt keinen zweiten Termin an, sondern meldet den vorhandenen.
• Bei Kunde und Tier prüft der Probelauf auf Dubletten (gleicher Name, gleiche E-Mail).

So gibst du die passenden Bereiche frei

Die fünf allgemeinen Abfragen /_ueberblick, /_termine, /_freie_zeiten, /_belegung und /_anfragen brauchen bei eingeschränkten Schlüsseln assistent. Für Aktionen unter contacts, pets, services, coachingappointments oder groupappointments prüft PetWorkers stattdessen die Freigabe des jeweiligen Bereichs. Dafür ist der Scope assistent nicht erforderlich.

Bereichsfreigaben heißen auch Scopes. Sie ersetzen weder das Rollenrecht noch die Freigabe zum Schreiben. Allgemeine Abfragen brauchen mindestens Beratung, Training & Betreuung; Finanzangaben mindestens BackOffice (Büro & Buchhaltung).