Scheduling

Verwalten Sie Verfügbarkeiten (Timeslots), Termine (Appointments), Teilnahmen (Participations) und Kunden (Customers). Diese Endpunkte bilden das Herzstück der Terminplanung.

Konzeptübersicht

Timeslot (Verfügbarkeit): Zeitfenster, in dem Buchungen möglich sind
Appointment (Termin): Gebuchter Zeitslot mit Teilnehmern
Participation (Teilnahme): Verknüpfung zwischen Customer und Appointment
Customer (Kunde): Kontaktdaten eines Buchenden

Timeslots (Verfügbarkeiten)

Ein Timeslot definiert, dass eine Resource für einen Zeitraum verfügbar ist. Der Zeitraum wird durch ein Raster in buchbare Slots unterteilt.

Raster-Konzept

Beispiel: Ein Konferenzraum ist von 8:00 bis 18:00 verfügbar (Timeslot). Buchungen sind in 30-Minuten-Blöcken möglich (Raster = 30). Das ergibt 20 buchbare Slots à 30 Minuten.

Create Timeslots

Erstellt einen oder mehrere Timeslots für eine Resource.

POST /crms/:crmId/provider/:providerRef/timeslotsbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "timeslots": [
      {
        "reference": "tsl-2024-01-15@yourCrm",
        "resourceReference": "res-musterstr1@yourCrm",
        "start": "2024-01-15T09:00",
        "end": "2024-01-15T17:00",
        "raster": 30,
        "defaultCapacity": 1,
        "defaultAcceptBookings": true,
        "address": {
          "city": "Berlin",
          "zip": "10115",
          "country": "DE",
          "street": "Musterstraße",
          "number": "1"
        },
        "state": "BOOKABLE"
      }
    ]
  }'

Request Body

Feld	Typ	Pflicht	Beschreibung
`timeslots`	array	Ja	Array von Timeslot-Objekten

Timeslot-Objekt Felder

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Nein	Eindeutige Timeslot-Referenz (generiert falls nicht angegeben)
`resourceReference`	string	Ja	Referenz der zugehörigen Resource
`start`	datetime	Nein	Beginn des Timeslots (ISO 8601)
`end`	datetime	Ja	Ende des Timeslots (ISO 8601)
`raster`	number	Ja	Dauer eines Buchungs-Slots in Minuten. Teilt den Timeslot in buchbare Einheiten.
`defaultCapacity`	number	Ja	Maximale Teilnehmer pro erstelltem Appointment
`defaultAcceptBookings`	boolean	Ja	`true`: Öffentlich buchbar.`false`: Appointment wird privat (weitere Buchungen nur durch Provider).
`address`	object \| string	Nein	Adresse für Appointments. Kann ein Objekt oder ein String sein (z.B. "Zoom: https://zoom.us/j/123")
`state`	string	Ja	`CREATED`: Versteckt (Planungsphase).`BOOKABLE`: Öffentlich sichtbar und buchbar.

Adresse als String (z.B. für Video-Calls)bash

{
  "address": "Zoom-Meeting: https://zoom.us/j/123456789"
}

Get Timeslots

Ruft alle Timeslots einer Resource in einem Zeitraum ab.

GET /crms/:crmId/provider/:providerRef/resource/:resourceRef/timeslotsbash

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resource/res-musterstr1@yourCrm/timeslots?from=2024-01-15T00:00&to=2024-01-22T00:00" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
`from`	datetime	Ja	Startdatum (ISO 8601)
`to`	datetime	Ja	Enddatum (ISO 8601)

Appointments inklusive

Die Response enthält auch Appointment-Daten, falls ein Timeslot bereits gebuchte Termine hat.

Update Timeslot

Aktualisiert einen existierenden Timeslot. Nur übergebene Felder werden geändert.

PUT /crms/:crmId/provider/:providerRef/timeslots/:timeslotRefbash

curl -X PUT "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots/tsl-2024-01-15@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-15T10:00",
    "end": "2024-01-15T16:00",
    "raster": 30,
    "defaultCapacity": 2,
    "defaultAcceptBookings": true,
    "state": "BOOKABLE"
  }'

Delete Timeslot

Löscht einen Timeslot.

DELETE /crms/:crmId/provider/:providerRef/timeslots/:timeslotRefbash

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots/tsl-2024-01-15@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Voraussetzung

Schlägt fehl, wenn der Timeslot ein nicht-storniertes Appointment hat. Löschen oder stornieren Sie zuerst das Appointment.

Appointments (Termine)

Appointments sind gebuchte Termine. Sie können einzeln, als Sequenz oder als Serie über mehrere Tage erstellt werden.

Get Appointments

Ruft Appointments eines Providers ab. Enthält aktive und stornierte Termine.

GET /crms/:crmId/provider/:providerRef/appointmentsbash

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments?productRef=prod-besichtigung@yourCrm&resourceRef=res-musterstr1@yourCrm&includeArchived=false" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query-Parameter

Parameter	Typ	Beschreibung
`productRef`	string	Filterung nach Produkt (optional)
`resourceRef`	string	Filterung nach Resource (optional)
`includeArchived`	boolean	Archivierte Appointments einschließen (Default: false)

Response

200 OKjson

[
  {
    "reference": "apt-001@yourCrm",
    "acceptBookings": true,
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    },
    "archived": false,
    "capacity": 1,
    "contactReference": "user-123@yourCrm",
    "description": "Besichtigung",
    "start": "2024-01-15T10:00:00Z",
    "end": "2024-01-15T10:30:00Z",
    "notes": null,
    "participations": [
      {
        "reference": "part-001@yourCrm",
        "email": "kunde@example.com",
        "mobile": "+49 170 9876543",
        "name": "Max Kunde",
        "note": "",
        "state": "BOOKED",
        "messages": null
      }
    ],
    "price": null,
    "productReference": "prod-besichtigung@yourCrm",
    "resourceReference": "res-musterstr1@yourCrm",
    "seriesId": null,
    "state": "ACTIVE"
  }
]

Create Appointments

Erstellt Appointments. Unterstützt einzelne Termine, Sequenzen und Serien.

POST /crms/:crmId/provider/:providerRef/appointments - Einzelterminbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "apt-001@yourCrm",
    "start": "2024-01-15T10:00",
    "end": "2024-01-15T11:00",
    "capacity": 1,
    "acceptBookings": true,
    "resourceReference": "res-musterstr1@yourCrm",
    "productReference": "prod-besichtigung@yourCrm",
    "productName": "Besichtigung",
    "contactReference": "user-123@yourCrm",
    "address": {
      "city": "Berlin",
      "zip": "10115",
      "country": "DE",
      "street": "Musterstraße",
      "number": "1"
    },
    "participations": [
      {
        "reference": "part-001@yourCrm",
        "name": "Max Kunde",
        "email": "kunde@example.com",
        "mobile": "+49 170 9876543",
        "note": "Interessiert an 3-Zimmer-Wohnung",
        "state": "BOOKED"
      }
    ],
    "price": {
      "value": 0.00,
      "currency": "EUR"
    }
  }'

Request Body (Einzeltermin)

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja*	*Pflicht für Einzeltermin, ignoriert bei Serie
`start`	datetime	Ja	Beginn (ISO 8601)
`end`	datetime	Ja	Ende (ISO 8601)
`capacity`	number	Nein	Max. Teilnehmer (Default: 0)
`acceptBookings`	boolean	Nein	Öffentlich buchbar (Default: false)
`resourceReference`	string	Ja	Resource-Referenz
`productReference`	string	Ja	Produkt-Referenz
`productName`	string	Nein	Überschreibt Produktname
`contactReference`	string	Nein	Verantwortlicher Staff
`address`	object \| string	Nein	Adresse (Default: Resource-Adresse)
`participations`	array	Nein	Teilnehmer des Termins
`price`	object	Nein	Preis (value, currency: EUR/CHF)

Participation-Objekt

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja*	*Pflicht für Einzeltermin
`name`	string	Ja	Name des Teilnehmers
`email`	string	Ja	E-Mail des Teilnehmers
`mobile`	string	Nein	Mobilnummer
`note`	string	Nein	Notiz zum Teilnehmer
`state`	string	Ja	RESERVED, REQUESTED, BOOKED, CANCELED, DELETED

RESERVED-Status

Participations mit Status RESERVED werden nach 3 Minuten automatisch gelöscht!

Serie erstellen

POST /crms/:crmId/provider/:providerRef/appointments - Seriebash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-15T09:00",
    "to": "2024-01-15T17:00",
    "capacity": 1,
    "acceptBookings": true,
    "resourceReference": "res-musterstr1@yourCrm",
    "productReference": "prod-besichtigung@yourCrm",
    "series_data": {
      "from": "2024-01-15T09:00",
      "to": "2024-01-19T17:00",
      "raster": 30,
      "weekdays": ["1", "2", "3", "4", "5"]
    }
  }'

series_data Objekt

Feld	Typ	Pflicht	Beschreibung
`from`	datetime	Ja	Start der Serie (ISO 8601)
`to`	datetime	Ja	Ende der Serie (ISO 8601)
`raster`	number	Ja	Slot-Dauer in Minuten
`weekdays`	string[]	Nein*	*Pflicht bei mehr als 1 Tag. Array von Wochentagen: "1"=Mo bis "7"=So

Delete Appointments (ohne Benachrichtigung)

Löscht Appointments ohne Teilnehmer zu benachrichtigen. Für administrative Korrekturen.

DELETE /crms/:crmId/provider/:providerRef/appointments/withoutNotificationbash

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments/withoutNotification" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentReference": "apt-001@yourCrm"
  }'

Request Body

Feld	Typ	Beschreibung
`appointmentReference`	string	Referenz des zu löschenden Appointments
`seriesId`	string	ODER: ID einer Serie (löscht alle Appointments der Serie)

Keine Benachrichtigung

Teilnehmer werden nicht über die Löschung informiert! Verwenden Sie dies nur für administrative Korrekturen.

Cancel Appointments

Storniert Appointments und benachrichtigt alle Teilnehmer per E-Mail.

DELETE /crms/:crmId/provider/:providerRef/appointmentsbash

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments?message=Der%20Termin%20muss%20leider%20abgesagt%20werden" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentReference": "apt-001@yourCrm"
  }'

Query-Parameter

Parameter	Typ	Beschreibung
`message`	string	Nachricht an Teilnehmer (in Stornierungs-E-Mail)

Verhalten

Setzt Appointment-State auf CANCELLED
Setzt alle Participation-States auf CANCELLED
Sendet Stornierungs-E-Mails an alle Teilnehmer
Appointment ist nicht mehr buchbar

Participations (Teilnahmen)

Participations verbinden Customers mit Appointments. Jede Participation hat einen Status, der den Buchungsprozess abbildet.

Participation States

State	Beschreibung
`RESERVED`	Temporär reserviert. Wird nach 3 Minuten automatisch gelöscht.
`REQUESTED`	Anfrage gestellt, wartet auf Bestätigung durch Provider.
`BOOKED`	Bestätigt und gebucht.
`CANCELED`	Vom Customer oder Provider storniert.
`DELETED`	Administrativ gelöscht (ohne Benachrichtigung).

Create Participation

Fügt einen Customer zu einem Appointment hinzu.

POST /crms/:crmId/provider/:providerRef/participationsbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/participations?ignoreCapacity=false&onDuplicateRaise=false&sendMails=true" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "part-002@yourCrm",
    "appointmentReference": "apt-001@yourCrm",
    "customerReference": "cust-001@yourCrm",
    "state": "BOOKED",
    "message": "Bestätigung Ihrer Terminbuchung"
  }'

Query-Parameter

Parameter	Typ	Default	Beschreibung
`ignoreCapacity`	boolean	false	Participation auch bei voller Kapazität hinzufügen
`onDuplicateRaise`	boolean	false	Bei existierender Referenz: true=Fehler, false=Update
`sendMails`	boolean	true	Benachrichtigungs-E-Mails senden

Request Body

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Participation-Referenz
`appointmentReference`	string	Ja	Appointment-Referenz
`customerReference`	string	Ja	Customer-Referenz
`state`	string	Ja	RESERVED, REQUESTED, BOOKED, CANCELED, DELETED
`message`	string	Nein	Nachricht in der E-Mail an den Customer

Update Participation

Ändert den Status einer Participation.

POST /crms/:crmId/provider/:providerRef/participations/:participationRefbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/participations/part-002@yourCrm?sendMails=true" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CANCELED",
    "message": "Leider müssen wir Ihren Termin stornieren."
  }'

State-Übergänge mit E-Mail-Versand

Übergang	E-Mail?
RESERVED → BOOKED	✓ Ja
REQUESTED → BOOKED	✓ Ja
REQUESTED → CANCELED	✓ Ja
BOOKED → CANCELED	✓ Ja
RESERVED → CANCELED	✗ Nein
DELETED → CANCELED	✗ Nein
BOOKED → DELETED	✗ Nein (!)

Nicht unterstützte Übergänge

Übergänge zu RESERVED oder REQUESTED sind nicht möglich. Erstellen Sie stattdessen eine neue Participation.

Customers (Kunden)

Customers sind Personen, die Termine buchen. Sie gehören zu einem Provider und können in mehreren Appointments teilnehmen.

Get Customer

Ruft einen Customer anhand seiner Referenz ab.

GET /crms/:crmId/provider/:providerRef/customers/:customerRefbash

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Response

200 OKjson

{
  "api-info": {
    "version": "1"
  },
  "customer": {
    "customerReference": "cust-001@yourCrm",
    "email": "kunde@example.com",
    "note": "Interessiert an 3-Zimmer-Wohnungen",
    "userName": "Max Kunde",
    "mobile": "+49 170 9876543",
    "language": "de",
    "providerReference": "prov-001@yourCrm"
  }
}

Status Codes

Code	Bedeutung
`200`	Customer gefunden
`204`	Kein Customer mit dieser Referenz gefunden

Create Customer

Erstellt einen neuen Customer für einen Provider.

POST /crms/:crmId/provider/:providerRef/customersbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "cust-001@yourCrm",
    "providerReference": "prov-001@yourCrm",
    "userName": "Max Kunde",
    "email": "kunde@example.com",
    "mobile": "+49 170 9876543",
    "note": "Interessiert an 3-Zimmer-Wohnungen",
    "language": "de"
  }'

Request Body

Feld	Typ	Pflicht	Beschreibung
`customerReference`	string	Ja	Eindeutige Customer-Referenz
`providerReference`	string	Ja	Provider-Referenz
`userName`	string	Ja	Name des Kunden
`email`	string	Nein	E-Mail-Adresse
`mobile`	string	Nein	Mobilnummer (mit Ländercode)
`note`	string	Nein	Interne Notiz (max. 1023 Zeichen)
`language`	string	Nein	Sprachcode (de, en, etc.)

Status Codes

Code	Bedeutung
`201`	Neuer Customer erstellt
`200`	Customer existiert bereits

Update Customer

Aktualisiert einen existierenden Customer.

PUT /crms/:crmId/provider/:providerRef/customers/:customerRefbash

curl -X PUT "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "cust-001-new@yourCrm",
    "email": "neue-email@example.com",
    "userName": "Max Neukunde",
    "mobile": "+49 170 1111111",
    "note": "Aktualisierte Notiz"
  }'

Referenz ändern

Sie können auch die customerReference ändern. userName und customerReference können nicht auf null/leer gesetzt werden.

Delete Customer

Löscht einen Customer.

DELETE /crms/:crmId/provider/:providerRef/customers/:customerRefbash

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm?ignoreFutureAppointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query-Parameter

Parameter	Beschreibung
`ignoreFutureAppointments`	Wenn gesetzt: Entfernt Customer aus allen zukünftigen Appointments. Customer wird per E-Mail benachrichtigt (falls konfiguriert).

Zukünftige Appointments

Ohne ignoreFutureAppointments schlägt die Anfrage fehl, wenn der Customer in zukünftigen Appointments teilnimmt.

DSGVO

Das Löschen eines Customers entfernt alle personenbezogenen Daten gemäß DSGVO. Die Buchungshistorie wird anonymisiert beibehalten.

Nächste Schritte

Booking Flow - Consumer-facing Endpunkte für Buchungen

Scheduling

Timeslots (Verfügbarkeiten)

Create Timeslots

Request Body

Timeslot-Objekt Felder

Get Timeslots

Query-Parameter

Update Timeslot

Delete Timeslot

Appointments (Termine)

Get Appointments

Query-Parameter

Response

Create Appointments

Request Body (Einzeltermin)

Participation-Objekt

Serie erstellen

series_data Objekt

Delete Appointments (ohne Benachrichtigung)

Request Body

Cancel Appointments

Query-Parameter

Verhalten

Participations (Teilnahmen)

Participation States

Create Participation

Query-Parameter

Request Body

Update Participation

State-Übergänge mit E-Mail-Versand

Customers (Kunden)

Get Customer

Response

Status Codes

Create Customer

Request Body

Status Codes

Update Customer

Delete Customer

Query-Parameter

Nächste Schritte

Verwandte Themen