Scheduling

L'API timum gestisce le disponibilità (Timeslots), gli appuntamenti (Appointments), le partecipazioni (Participations) e i clienti: il cuore della pianificazione degli appuntamenti.

Timeslots (Disponibilità)

Un Timeslot definisce che una risorsa è disponibile per un periodo di tempo. Il periodo viene suddiviso in slot prenotabili tramite una griglia.

Create Timeslots

Crea uno o più Timeslot per una risorsa.

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

Campi dell'oggetto Timeslot

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

Get Timeslots

Recupera tutti i Timeslot di una risorsa in un determinato periodo.

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"

Parametri di query

Update Timeslot

Aggiorna un Timeslot esistente. Vengono modificati solo i campi forniti.

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

Elimina 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 (Appuntamenti)

Gli Appointment sono appuntamenti prenotati. Possono essere creati singolarmente, come sequenza o come serie su più giorni.

Get Appointments

Recupera gli Appointment di un fornitore. Include appuntamenti attivi e annullati.

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"

Parametri di query

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

Crea Appointment. Supporta appuntamenti singoli, sequenze e serie.

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 (Appuntamento singolo)

Oggetto Participation

Creare una serie

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

Oggetto series_data

Delete Appointments (senza notifica)

Elimina gli Appointment senza notificare i partecipanti. Per correzioni amministrative.

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

Annulla gli Appointment e notifica tutti i partecipanti via 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"
  }'

Parametri di query

Comportamento

• Imposta lo stato dell'Appointment su CANCELLED
• Imposta tutti gli stati di Participation su CANCELLED
• Invia e-mail di annullamento a tutti i partecipanti
• L'Appointment non è più prenotabile

Participations (Partecipazioni)

Le Participation collegano i Customer agli Appointment. Ogni Participation ha uno stato che riflette il processo di prenotazione.

Participation States

Create Participation

Aggiunge un Customer a 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"
  }'

Parametri di query

Request Body

Update Participation

Modifica lo stato di una 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."
  }'

Transizioni di stato con invio di e-mail

Customers (Clienti)

I Customer sono persone che prenotano appuntamenti. Appartengono a un fornitore e possono partecipare a più Appointment.

Get Customer

Recupera un Customer in base al suo riferimento.

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

Crea un nuovo Customer per un fornitore.

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

Aggiorna un Customer esistente.

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

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

Parametri di query

Prossimi passi

• Booking Flow - Endpoint rivolti al consumatore per le prenotazioni

Argomenti correlati

• Panoramica API
• Initial Setup
• Configure Offerings
• Comprendere le disponibilità
• Configurare gli orari di lavoro