API-Dokumentation

Die timum API ermöglicht die vollständige programmatische Integration von Terminbuchungen in Ihre Plattform. Diese Dokumentation richtet sich an Entwickler, die timum als White-Label-Lösung integrieren möchten.

Base URL

Alle API-Anfragen werden an folgende Basis-URL gesendet:

API Base URLtext

https://www.timum.de

HTTPS erforderlich

HTTP-Anfragen werden automatisch auf HTTPS umgeleitet. Verwenden Sie immer HTTPS. Stellen Sie außerdem sicher, dass Sie www. in der URL verwenden - Anfragen ohne www. können zu Redirect-Problemen führen.

Authentifizierung

Alle API-Anfragen müssen mit Ihrem API-Key authentifiziert werden. Der Key wird im HTTP-Header X-TIMUM-CLIENT-ID übermittelt:

Authentifizierung via Headerbash

curl -X GET "https://www.timum.de/crms/{crmId}/resources" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json"

API-Key erhalten

Ihren API-Key (auch "directUseSecret" genannt) erhalten Sie von timum bei der Einrichtung Ihrer Integration. Der Key ist an Ihre CRM-ID gebunden und ermöglicht den Zugriff auf alle Ressourcen innerhalb Ihres CRM-Kontexts.

CRM-ID

Die crmId ist Ihre eindeutige Kennung als timum-Partner. Sie wird bei der Integration einmalig vergeben und bleibt konstant. Alle API-Pfade enthalten diese ID als Pfad-Parameter.

Referenz-Format

timum verwendet ein einheitliches Referenz-Format, um Entitäten eindeutig zu identifizieren. Referenzen bestehen aus zwei Teilen, getrennt durch @:

Referenz-Formattext

{uniqueId}@{platformName}

Beispiele:
- 12345@yourCrmUser          (User-Referenz)
- abc-def-123@yourCrmAccount (Account-Referenz)
- property-42@yourCrmResource (Ressourcen-Referenz)

Bestandteile

Teil	Beschreibung
`uniqueId`	Die ID, unter der Sie diese Entität in Ihrem System führen
`platformName`	Ihr Plattform-Suffix, das bei der Integration vereinbart wurde (z.B. "yourCrm", "is24")

Referenzen speichern

Verwenden Sie Ids die Sie bereits haben oder generieren können. Andernfalls speichern Sie die Referenzen, die Sie bei der Erstellung von Entitäten verwenden. Sie benötigen sie für alle nachfolgenden Operationen auf diesen Entitäten.

API-Bereiche

Die API ist nach Anwendungsfällen strukturiert:

1. Einrichtung

Initial Setup

Users, Accounts, Providers, Staff - Grundstruktur aufbauen

2. Konfiguration

Configure Offerings

Resources, Products, Contact Profiles - Angebot definieren

3. Terminplanung

Scheduling

Timeslots, Appointments, Participations, Customers

4. Buchung

Booking Flow

Consumer-facing Endpunkte für die Terminbuchung

Response Format

Alle API-Responses sind im JSON-Format. Jede Antwort enthält ein api-info Objekt mit Versionsinformationen:

Erfolgreiche Response (Beispiel: User erstellt)json

{
  "api-info": {
    "version": "1"
  },
  "user": {
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": null,
    "mobile": null
  }
}

Fehler-Response

Bei Fehlern enthält die Response ein errors Array mit Fehlercodes und Meldungen:

Fehler Responsejson

{
  "api-info": {
    "version": "1"
  },
  "errors": [
    {
      "errorCode": "201",
      "message": "Das überlappt mit einem anderen Termin."
    }
  ]
}

HTTP Status Codes

Code	Bedeutung	Typische Situation
`200`	OK	Anfrage erfolgreich, existierende Entität zurückgegeben
`201`	Created	Neue Entität erfolgreich erstellt
`202`	Accepted	Update erfolgreich angenommen
`204`	No Content	Erfolgreich, aber keine Daten zurückzugeben (z.B. Kunde nicht gefunden)
`400`	Bad Request	Pflichtfeld fehlt, ungültiges Format, falsche Referenz
`404`	Not Found	Referenzierte Entität existiert nicht
`409`	Conflict	Duplikat erkannt (z.B. Email oder Username bereits vergeben)
`412`	Precondition Failed	Termin bereits gebucht, Kapazität erschöpft

Häufige Fehler-Codes

errorCode	Bedeutung
`201`	Zeitliche Überschneidung mit bestehendem Termin

CORS

Die API unterstützt Cross-Origin Resource Sharing (CORS) für Browser-basierte Integrationen. Preflight-Requests werden automatisch beantwortet.

CORS Headertext

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Auth-Token

Nächste Schritte

Initial Setup - Beginnen Sie mit der Erstellung von Users und Accounts
Configure Offerings - Definieren Sie Ressourcen und Produkte
Scheduling - Erstellen Sie Verfügbarkeiten und Termine
Booking Flow - Integrieren Sie die Terminbuchung

Für Anwender

War diese Seite hilfreich?