Scheduling

L'API timum gère les disponibilités (Timeslots), les rendez-vous (Appointments), les participations et les clients – le cœur de la planification des rendez-vous.

Timeslots (Disponibilités)

Un Timeslot définit qu'une ressource est disponible pendant une période donnée. Cette période est divisée en créneaux réservables par une grille.

Create Timeslots

Crée un ou plusieurs Timeslots pour une ressource.

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

Champs de l'objet Timeslot

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

Get Timeslots

Récupère tous les Timeslots d'une ressource sur une période donnée.

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"

Paramètres de requête

Update Timeslot

Met à jour un Timeslot existant. Seuls les champs transmis sont modifiés.

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

Supprime un Timeslot.

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"

Appointments (Rendez-vous)

Les Appointments sont des rendez-vous réservés. Ils peuvent être créés individuellement, sous forme de séquence ou de série sur plusieurs jours.

Get Appointments

Récupère les Appointments d'un fournisseur. Inclut les rendez-vous actifs et annulés.

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"

Paramètres de requête

Response

[
  {
    "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

Crée des Appointments. Prend en charge les rendez-vous individuels, les séquences et les séries.

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 (Rendez-vous unique)

Objet Participation

Créer une série

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"]
    }
  }'

Objet series_data

Delete Appointments (sans notification)

Supprime des Appointments sans notifier les participants. Pour les corrections administratives.

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

Cancel Appointments

Annule les Appointments et notifie tous les participants par e-mail.

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"
  }'

Paramètres de requête

Comportement

• Définit l'état de l'Appointment sur CANCELLED
• Définit tous les états de Participation sur CANCELLED
• Envoie des e-mails d'annulation à tous les participants
• L'Appointment n'est plus réservable

Participations

Les Participations relient les Customers aux Appointments. Chaque Participation a un statut qui reflète le processus de réservation.

Participation States

Create Participation

Ajoute un Customer à un Appointment.

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"
  }'

Paramètres de requête

Request Body

Update Participation

Modifie le statut d'une Participation.

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."
  }'

Transitions d'état avec envoi d'e-mail

Customers (Clients)

Les Customers sont des personnes qui réservent des rendez-vous. Ils appartiennent à un fournisseur et peuvent participer à plusieurs Appointments.

Get Customer

Récupère un Customer à partir de sa référence.

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

{
  "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

Create Customer

Crée un nouveau Customer pour un fournisseur.

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

Status Codes

Update Customer

Met à jour un Customer existant.

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"
  }'

Delete Customer

Supprime un Customer.

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"

Paramètres de requête

Étapes suivantes

• Booking Flow - Endpoints orientés consommateur pour les réservations

Sujets connexes

• Aperçu de l'API
• Initial Setup
• Configure Offerings
• Comprendre les disponibilités
• Configurer les horaires de travail