Configure Offerings

Definieren Sie, was Sie anbieten: Produkte (Services), Ressourcen (buchbare Objekte) und Kontaktprofile (öffentliche Kontaktdaten).

Konfigurationsreihenfolge

Products erstellen - Die Services, die Sie anbieten
Resources erstellen - Die buchbaren Objekte (Immobilien, Räume, Mitarbeiter)
Contact Profiles erstellen (optional) - Öffentliche Kontaktdaten

Products (Produkte/Services)

Ein Product definiert einen Service-Typ, den Sie anbieten (z.B. "Besichtigung", "Beratungsgespräch"). Products haben Zeitvorgaben (min/max Dauer) und können mit Ressourcen verknüpft werden.

Create Product

Erstellt ein neues Produkt für einen Provider.

POST /crms/:crmId/provider/:providerRef/productsbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/products" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung mit unserem Experten",
    "minDuration": 30,
    "maxDuration": 45
  }'

Pfad-Parameter

Parameter	Typ	Beschreibung
`crmId`	string	Ihre CRM-Kennung
`providerRef`	string	Provider-Referenz

Request Body

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Produkt-Referenz
`name`	string	Ja	Anzeigename des Produkts
`description`	string	Nein	Beschreibung für Kunden (z.B. Hinweise zum Termin)
`minDuration`	number	Nein	Minimale Dauer in Minuten
`maxDuration`	number	Nein	Maximale Dauer in Minuten

Response

201 Createdjson

{
  "api-info": {
    "version": "1"
  },
  "product": {
    "uuid": "92867f70-4836-11e5-bc04-021a52c25043",
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung mit unserem Experten",
    "minDuration": 30,
    "maxDuration": 45,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  }
}

Lead/Follow-Up Time

leadTimeMinutes und followUpTimeMinutes definieren Pufferzeiten vor und nach dem Termin. Diese können über die timum-Oberfläche konfiguriert werden.

Get Products

Listet alle Produkte eines Providers auf.

GET /crms/:crmId/provider/:providerRef/productsbash

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

Response

200 OKjson

[
  {
    "uuid": "92867f70-4836-11e5-bc04-021a52c25043",
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung",
    "minDuration": 30,
    "maxDuration": 45,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  },
  {
    "uuid": "0bb978c0-5740-11eb-8b95-024759471364",
    "reference": "prod-beratung@yourCrm",
    "name": "Beratungsgespräch",
    "description": "Individuelle Beratung",
    "minDuration": 15,
    "maxDuration": 30,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  }
]

Resources (Ressourcen)

Eine Resource repräsentiert ein buchbares Objekt - typischerweise eine Immobilie, ein Raum, ein Fahrzeug oder ein Mitarbeiter. Resources werden mit Products verknüpft, um anzugeben, welche Services an dieser Resource angeboten werden.

Create Resource

Erstellt eine neue Resource oder aktualisiert eine existierende (falls onDuplicateRaise=false).

POST /crms/:crmId/provider/:providerRef/resourcesbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resources?onDuplicateRaise=false" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "res-musterstr1@yourCrm",
    "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
    "internalName": "Objekt 4711 - Musterstraße",
    "description": "Schöne 3-Zimmer-Wohnung mit Balkon im 2. OG",
    "products": ["prod-besichtigung@yourCrm", "prod-beratung@yourCrm"],
    "contact": "user-123@yourCrm",
    "contactProfileReference": "profile-1@yourCrm",
    "website": "https://example.com/objekt/4711",
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    }
  }'

Query-Parameter

Parameter	Typ	Default	Beschreibung
`onDuplicateRaise`	boolean	false	Wenn true: Request schlägt mit 400 fehl, falls Referenz existiert. Wenn false: Existierende Resource wird aktualisiert.

Request Body

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Resource-Referenz
`publicName`	string	Ja	Name, der Kunden angezeigt wird
`internalName`	string	Ja	Interner Name für den Provider
`description`	string	Nein	Beschreibung der Resource
`products`	string[]	Nein	Array von Produkt-Referenzen. Die Produkte müssen bereits existieren. Definiert, welche Services an dieser Resource angeboten werden.
`contact`	string	Nein*	User-Referenz als Kontaktperson. *Pflicht, wenn contactProfileReference angegeben wird.
`contactProfileReference`	string	Nein	Referenz eines Contact Profiles. Muss zum Contact-User gehören.
`website`	string	Nein	URL zur Resource-Webseite
`address`	object	Nein	Adresse der Resource. countryCode ist optional (Default: "DE"). Alle anderen Felder (city, zip, street, number) sind pflicht, wenn address angegeben wird.

Response

201 Createdjson

{
  "reference": "res-musterstr1@yourCrm",
  "uuid": "264de7b0-0e4a-11ea-988f-fa1e49f3d761",
  "provider": "prov-001@yourCrm",
  "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
  "internalName": "Objekt 4711 - Musterstraße",
  "description": "Schöne 3-Zimmer-Wohnung mit Balkon im 2. OG",
  "contact": "user-123@yourCrm",
  "archived": false,
  "products": ["prod-besichtigung@yourCrm", "prod-beratung@yourCrm"],
  "address": {
    "city": "Berlin",
    "countryCode": "DE",
    "street": "Musterstraße",
    "number": "1",
    "zip": "10115"
  }
}

Update Resource

Aktualisiert eine existierende Resource. Nur die übergebenen Felder werden geändert.

POST /crms/:crmId/provider/:providerRef/resources/:resourceRefbash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resources/res-musterstr1@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "publicName": "Musterstraße 1 - Traumwohnung mit Balkon",
    "products": ["prod-besichtigung@yourCrm"],
    "archived": false
  }'

Zusätzliches Feld für Update

Feld	Typ	Beschreibung
`archived`	boolean	Setzt die Resource auf archiviert (true) oder aktiv (false). Archivierte Resources sind für Kunden nicht mehr buchbar.

Response

Gibt die aktualisierte Resource zurück (wie bei Create). Status: 202 Accepted.

Get Resources

Listet alle Resources eines Providers auf.

GET /crms/:crmId/provider/:providerRef/resourcesbash

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

Response

200 OKjson

[
  {
    "reference": "res-musterstr1@yourCrm",
    "uuid": "264de7b0-0e4a-11ea-988f-fa1e49f3d761",
    "provider": "prov-001@yourCrm",
    "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
    "internalName": "Objekt 4711 - Musterstraße",
    "description": "Schöne 3-Zimmer-Wohnung",
    "contact": "user-123@yourCrm",
    "archived": false,
    "products": ["prod-besichtigung@yourCrm"],
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    }
  }
]

Delete Resource

Löscht eine Resource. Schlägt fehl, wenn es zukünftige Termine gibt (es sei denn, ignoreFutureAppointments=true).

DELETE /crms/:crmId/provider/:providerRef/resources/:resourceRefbash

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

Query-Parameter

Parameter	Typ	Beschreibung
`ignoreFutureAppointments`	boolean	Wenn true: Resource wird auch bei zukünftigen Terminen gelöscht. Alle Teilnehmer werden über die Stornierung informiert und die Termine werden archiviert.

Irreversibel

Das Löschen einer Resource ist unwiderruflich. Verwenden Sie archived: true im Update-Endpoint, wenn Sie die Resource nur deaktivieren möchten.

Contact Profiles (Kontaktprofile)

Contact Profiles definieren, wie ein User öffentlich dargestellt wird. Sie enthalten Kontaktkanäle (Telefon, E-Mail, Video-Links etc.), die Kunden sehen.

Allgemeines vs. Provider-spezifisches Profil

General Profile: Standardprofil eines Users, verwendet wenn kein spezifisches Profil zugewiesen ist
Provider Profile: Spezifisches Profil für einen bestimmten Provider

Get General Profile

Ruft das allgemeine Kontaktprofil eines Users ab.

GET /crms/:crmId/user/:userRef/generalContactProfilebash

curl -X GET "https://www.timum.de/crms/{crmId}/user/user-123@yourCrm/generalContactProfile" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Response

200 OKjson

{
  "name": "Max Mustermann - Immobilienexperte",
  "contactChannels": [
    {
      "label": "Mobil",
      "type": "mobile",
      "value": "+49 170 1234567"
    },
    {
      "label": "Email",
      "type": "email",
      "value": "max@example.com"
    },
    {
      "label": "Telefon",
      "type": "phone",
      "value": "+49 30 12345678"
    }
  ]
}

Update General Profile

Aktualisiert das allgemeine Kontaktprofil eines Users.

PUT /crms/:crmId/user/:userRef/generalContactProfilebash

curl -X PUT "https://www.timum.de/crms/{crmId}/user/user-123@yourCrm/generalContactProfile" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Max Mustermann - Ihr Immobilienexperte",
    "contactChannels": [
      {
        "label": "Mobil",
        "type": "mobile",
        "value": "+49 170 1234567"
      },
      {
        "label": "Email",
        "type": "email",
        "value": "max@example.com"
      },
      {
        "label": "Telefon",
        "type": "phone",
        "value": "+49 30 12345678"
      },
      {
        "label": "Video-Call",
        "type": "video",
        "value": "https://meet.example.com/max"
      }
    ]
  }'

Request Body

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Öffentlicher Name. Kann vom Login-Namen abweichen (z.B. Firmenname).
`contactChannels`	array	Ja	Array von Kontaktkanälen

Contact Channel Felder

Feld	Typ	Pflicht	Beschreibung
`label`	string	Nein	Anzeigelabel für den Kanal
`type`	string	Ja	Kanaltyp. Erlaubte Werte: `mobile` - Mobilnummer (kundenöffentlich) `phone` - Festnetz (kundenöffentlich) `email` - E-Mail (kundenöffentlich, für Transaktions-Mails) `video` - Video-Call Link `messenger` - Messenger `link` - Allgemeiner Link `location` - Adresse/Ort
`value`	string	Ja	Wert des Kanals (Nummer, E-Mail, URL, Adresse)

Algorithmus für contactChannels

Neuer Typ im Array: Neuer Kanal wird erstellt
Existierender Typ im Array: Kanal wird aktualisiert
Typ fehlt im Array: Kanal wird entfernt

Ein Kanal pro Typ

Aktuell kann nur ein Kanal pro Typ existieren. Mehrere Telefonnummern erfordern verschiedene Typen (z.B. phone und mobile).

Get Profile (Provider-spezifisch)

Ruft ein provider-spezifisches Kontaktprofil ab.

GET /crms/:crmId/provider/:providerRef/contactProfile/:profileRefbash

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

Fehler

Status	Ursache
`404`	Profil mit dieser Referenz nicht gefunden

Create or Update Profile (Provider-spezifisch)

Erstellt oder aktualisiert ein provider-spezifisches Kontaktprofil.

POST /crms/:crmId/provider/:providerRef/contactProfilebash

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/contactProfile" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "profile-1@yourCrm",
    "userReference": "user-123@yourCrm",
    "providerReference": "prov-001@yourCrm",
    "name": "Mustermann Immobilien - Vertrieb",
    "contactChannels": [
      {
        "label": "Hotline",
        "type": "phone",
        "value": "+49 30 12345678"
      },
      {
        "label": "Vertrieb",
        "type": "email",
        "value": "vertrieb@mustermann-immo.de"
      },
      {
        "label": "Büro",
        "type": "location",
        "value": "Musterstraße 28, 10115 Berlin"
      }
    ]
  }'

Request Body

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Profil-Referenz
`userReference`	string	Ja	Referenz des Users, zu dem dieses Profil gehört
`providerReference`	string	Ja	Referenz des Providers, für den dieses Profil gilt
`name`	string	Ja	Öffentlicher Anzeigename
`contactChannels`	array	Ja	Array von Kontaktkanälen (siehe Update General Profile)

Verwendung in Resources/Appointments

Um ein Profil zu verwenden, setzen Sie beim Erstellen einer Resource oder eines Appointments:

contact: User-Referenz
contactProfileReference: Profil-Referenz

Das Profil muss zum Contact-User gehören und muss für den Provider gültig sein, in dem die Resource/Appointment erstellt wird.

Fallback

Wenn kein contactProfileReference angegeben wird, wird das General Profile des Contact-Users verwendet. Wenn kein Contact angegeben wird, werden die Provider-Infos angezeigt.

Nächste Schritte

Mit konfigurierten Offerings können Sie nun:

Scheduling einrichten - Timeslots, Appointments, Participations, Customers
Booking Flow integrieren - Consumer-facing Buchungs-Endpunkte

Configure Offerings

Products (Produkte/Services)

Create Product

Pfad-Parameter

Request Body

Response

Get Products

Response

Resources (Ressourcen)

Create Resource

Query-Parameter

Request Body

Response

Update Resource

Zusätzliches Feld für Update

Response

Get Resources

Response

Delete Resource

Query-Parameter

Contact Profiles (Kontaktprofile)

Get General Profile

Response

Update General Profile

Request Body

Contact Channel Felder

Algorithmus für contactChannels

Get Profile (Provider-spezifisch)

Fehler

Create or Update Profile (Provider-spezifisch)

Request Body

Verwendung in Resources/Appointments

Nächste Schritte

Verwandte Themen