Configurer les Offerings

Avec l'API timum, vous définissez ce que vous proposez : Products (services), Resources (objets réservables) et Contact Profiles (coordonnées publiques).

1. Créer des Products - Les services que vous proposez
2. Créer des Resources - Les objets réservables (biens, salles, collaborateurs)
3. Créer des Contact Profiles (facultatif) - Coordonnées publiques

Products (produits/services)

Un Product définit un type de service que vous proposez (par ex. "visite", "entretien-conseil"). Les Products ont des contraintes de durée (durée min/max) et peuvent être liés à des ressources.

Create Product

Crée un nouveau produit pour un fournisseur.

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

Paramètres de chemin

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

Liste tous les produits d'un fournisseur.

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

Une Resource représente un objet réservable - typiquement un bien immobilier, une salle, un véhicule ou un collaborateur. Les Resources sont liées à des Products pour indiquer quels services sont proposés sur cette ressource.

Create Resource

Crée une nouvelle ressource ou met à jour une ressource existante (si 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"
    }
  }'

Paramètres de requête

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

Met à jour une ressource existante. Seuls les champs transmis sont modifiés.

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

Champ supplémentaire pour la mise à jour

Response

Renvoie la ressource mise à jour (comme pour Create). Statut : 202 Accepted.

Get Resources

Liste toutes les ressources d'un fournisseur.

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

Supprime une ressource. Échoue s'il existe des rendez-vous futurs (sauf si 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"

Paramètres de requête

Contact Profiles

Les Contact Profiles définissent la manière dont un utilisateur est présenté publiquement. Ils contiennent des canaux de contact (téléphone, e-mail, liens vidéo, etc.) que les clients voient.

• General Profile : Profil par défaut d'un utilisateur, utilisé lorsqu'aucun profil spécifique n'est attribué
• Provider Profile : Profil spécifique pour un fournisseur donné

Get General Profile

Récupère le profil de contact général d'un utilisateur.

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

Met à jour le profil de contact général d'un utilisateur.

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

Champs du Contact Channel

Algorithme pour contactChannels

• Nouveau type dans le tableau : Un nouveau canal est créé
• Type existant dans le tableau : Le canal est mis à jour
• Type absent du tableau : Le canal est supprimé

Get Profile (spécifique au fournisseur)

Récupère un profil de contact spécifique à un fournisseur.

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"

Erreurs

Create or Update Profile (spécifique au fournisseur)

Crée ou met à jour un profil de contact spécifique à un fournisseur.

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

Utilisation dans Resources/Appointments

Pour utiliser un profil, définissez ce qui suit lors de la création d'une ressource ou d'un rendez-vous :

• contact : référence utilisateur
• contactProfileReference : référence du profil

Le profil doit appartenir à l'utilisateur de contact et doit être valide pour le fournisseur dans lequel la ressource/le rendez-vous est créé.

Étapes suivantes

Avec des Offerings configurées, vous pouvez désormais :

• Configurer le Scheduling - Timeslots, Appointments, Participations, Customers
• Intégrer le Booking Flow - Endpoints de réservation destinés aux consommateurs

Sujets connexes

• Vue d'ensemble de l'API
• Initial Setup
• Qu'est-ce qu'une ressource ?
• Qu'est-ce qu'un type de rendez-vous ?