Configurare le Offerings

Con l'API timum si definisce ciò che si offre: Products (servizi), Resources (oggetti prenotabili) e Contact Profiles (dati di contatto pubblici).

1. Creare Products - I servizi offerti
2. Creare Resources - Gli oggetti prenotabili (immobili, sale, personale)
3. Creare Contact Profiles (opzionale) - Dati di contatto pubblici

Products (prodotti/servizi)

Un Product definisce un tipo di servizio offerto (ad es. "visita", "colloquio di consulenza"). I Products hanno vincoli di tempo (durata min/max) e possono essere collegati a risorse.

Create Product

Crea un nuovo prodotto per un fornitore.

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

Parametri del percorso

Request Body

Response

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

Get Products

Elenca tutti i prodotti di un fornitore.

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

Response

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

Una Resource rappresenta un oggetto prenotabile - tipicamente un immobile, una sala, un veicolo o un membro del personale. Le Resources vengono collegate ai Products per specificare quali servizi sono offerti su tale risorsa.

Create Resource

Crea una nuova risorsa o aggiorna una risorsa esistente (se onDuplicateRaise=false).

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

Parametri di query

Request Body

Response

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

Aggiorna una risorsa esistente. Vengono modificati solo i campi forniti.

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

Campo aggiuntivo per l'aggiornamento

Response

Restituisce la risorsa aggiornata (come in Create). Stato: 202 Accepted.

Get Resources

Elenca tutte le risorse di un fornitore.

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

Response

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

Elimina una risorsa. Fallisce se esistono appuntamenti futuri (a meno che ignoreFutureAppointments=true).

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"

Parametri di query

Contact Profiles

I Contact Profiles definiscono come un utente viene presentato pubblicamente. Contengono canali di contatto (telefono, e-mail, link video, ecc.) visibili ai clienti.

• General Profile: Profilo predefinito di un utente, utilizzato quando non è assegnato nessun profilo specifico
• Provider Profile: Profilo specifico per un determinato fornitore

Get General Profile

Recupera il profilo di contatto generale di un utente.

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

Response

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

Aggiorna il profilo di contatto generale di un utente.

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

Campi del Contact Channel

Algoritmo per contactChannels

• Nuovo tipo nell'array: Viene creato un nuovo canale
• Tipo esistente nell'array: Il canale viene aggiornato
• Tipo assente nell'array: Il canale viene rimosso

Get Profile (specifico del fornitore)

Recupera un profilo di contatto specifico di un fornitore.

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"

Errori

Create or Update Profile (specifico del fornitore)

Crea o aggiorna un profilo di contatto specifico di un fornitore.

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

Utilizzo in Resources/Appointments

Per utilizzare un profilo, impostare quanto segue durante la creazione di una risorsa o di un appuntamento:

• contact: riferimento utente
• contactProfileReference: riferimento del profilo

Il profilo deve appartenere all'utente di contatto e deve essere valido per il fornitore in cui viene creata la risorsa/l'appuntamento.

Prossimi passi

Con le Offerings configurate, ora è possibile:

• Configurare lo Scheduling - Timeslots, Appointments, Participations, Customers
• Integrare il Booking Flow - Endpoint di prenotazione lato consumatore

Argomenti correlati

• Panoramica dell'API
• Initial Setup
• Cos'è una risorsa?
• Cos'è un tipo di appuntamento?