Scheduling

La API de timum gestiona las disponibilidades (Timeslots), las citas (Appointments), las participaciones (Participations) y los clientes: el corazón de la planificación de citas.

Timeslots (Disponibilidades)

Un Timeslot define que un recurso está disponible durante un periodo de tiempo. Ese periodo se divide en franjas reservables mediante una cuadrícula.

Create Timeslots

Crea uno o varios Timeslots para un recurso.

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

Campos del objeto Timeslot

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

Get Timeslots

Recupera todos los Timeslots de un recurso durante un periodo de tiempo.

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"

Parámetros de consulta

Update Timeslot

Actualiza un Timeslot existente. Solo se modifican los campos proporcionados.

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 (Citas)

Los Appointments son citas reservadas. Se pueden crear de forma individual, como secuencia o como serie a lo largo de varios días.

Get Appointments

Recupera los Appointments de un proveedor. Incluye citas activas y canceladas.

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"

Parámetros de consulta

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 Appointments. Admite citas individuales, secuencias y series.

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 (Cita única)

Objeto Participation

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

Objeto series_data

Delete Appointments (sin notificación)

Elimina Appointments sin notificar a los participantes. Para correcciones administrativas.

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

Cancela Appointments y notifica a todos los participantes por correo electrónico.

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

Parámetros de consulta

Comportamiento

• Establece el estado del Appointment en CANCELLED
• Establece todos los estados de Participation en CANCELLED
• Envía correos de cancelación a todos los participantes
• El Appointment ya no se puede reservar

Participations (Participaciones)

Las Participations conectan a los Customers con los Appointments. Cada Participation tiene un estado que refleja el proceso de reserva.

Participation States

Create Participation

Añade 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"
  }'

Parámetros de consulta

Request Body

Update Participation

Cambia el estado de 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."
  }'

Transiciones de estado con envío de correo electrónico

Customers (Clientes)

Los Customers son personas que reservan citas. Pertenecen a un proveedor y pueden participar en varios Appointments.

Get Customer

Recupera un Customer a partir de su referencia.

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 nuevo Customer para un proveedor.

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

Actualiza un Customer existente.

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"

Parámetros de consulta

Próximos pasos

• Booking Flow - Endpoints orientados al consumidor para reservas

Temas relacionados

• Resumen de la API
• Initial Setup
• Configure Offerings
• Entender las disponibilidades
• Configurar los horarios de trabajo