Initial Setup

Ces endpoints de l'API timum servent à la configuration initiale unique de votre structure organisationnelle : créez des Users, Accounts et Providers.

1. User - Personne disposant d'identifiants de connexion
2. Account - Client/entreprise (nécessite un User comme propriétaire)
3. Provider - Profil de calendrier (nécessite un User comme propriétaire)
4. Staff - Ajouter des employés au Provider (optionnel)

Users

Un User représente une personne disposant d'identifiants de connexion, de droits d'accès et de coordonnées. Les Users peuvent être propriétaires d'Accounts et de Providers, et peuvent également agir en tant que Staff ou personne de contact.

Create User

Crée un nouveau User ou renvoie un User existant si la référence est déjà connue.

curl -X POST "https://www.timum.de/crms/{crmId}/user" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": "+49 30 12345678",
    "mobile": "+49 170 1234567"
  }'

Paramètres de chemin

Request Body

Algorithme / Comportement

• La référence existe déjà : Renvoie le User existant (200 OK). Les champs phone, mobile, lastName, firstName sont mis à jour.
• L'e-mail existe avec une référence différente : Un nouveau User est créé avec un e-mail généré (p. ex. max+001@example.com).
• L'e-mail existe sans référence : Le User existant est utilisé. Sa vérification d'e-mail est invalidée, un nouvel e-mail de vérification est envoyé, et la référence est rattachée.
• Nouveau User : Le User est créé (201 Created). La langue est reprise de l'utilisateur CRM à l'origine de l'action (peut être remplacée via le cookie PLAY_LANG).

Response

{
  "api-info": {
    "version": "1"
  },
  "user": {
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": null,
    "mobile": null
  }
}

{
  "api-info": {
    "version": "1"
  },
  "user": {
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": null,
    "mobile": null
  }
}

Erreurs

Get User

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

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

Paramètres de chemin

Response

{
  "api-info": {
    "version": "1"
  },
  "user": {
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": "+49 30 12345678",
    "mobile": "+49 170 1234567"
  }
}

Erreurs

Accounts

Un Account représente un client dans timum avec un plan de service souscrit et des données de facturation. Chaque Account appartient à un User (propriétaire).

Create Account

Crée un nouvel Account ou renvoie un Account existant si la référence est déjà connue.

curl -X POST "https://www.timum.de/crms/{crmId}/account" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerReference": "12345@yourCrm",
    "accountReference": "acc-001@yourCrm",
    "branch": "real-estate",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }'

Request Body

Algorithme / Comportement

• accountReference inconnue : Un nouvel Account est créé (201 Created).
• accountReference déjà connue : L'Account existant est renvoyé (200 OK). Les champs de l'Account existant ne sont pas écrasés.

Response

{
  "api-info": {
    "version": "1"
  },
  "account": {
    "ownerReference": "12345@yourCrm",
    "branch": "real-estate",
    "accountReference": "acc-001@yourCrm",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }
}

Erreurs

Get Account

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

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

Response

{
  "api-info": {
    "version": "1"
  },
  "account": {
    "ownerReference": "12345@yourCrm",
    "branch": "real-estate",
    "accountReference": "acc-001@yourCrm",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }
}

Erreurs

Providers

Un Provider représente un profil de calendrier contenant des ressources et des services (Products). Les Providers ont des membres du Staff (Users) qui ont accès au Provider.

Create Provider

Crée un nouveau Provider.

curl -X POST "https://www.timum.de/crms/{crmId}/provider" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "prov-001@yourCrm",
    "ownerReference": "12345@yourCrm",
    "accountReference": "acc-001@yourCrm",
    "name": "Mustermann Immobilien",
    "email": "kontakt@mustermann-immo.de",
    "mobile": "+49 170 1234567",
    "phone": "+49 30 12345678",
    "impressum": "Mustermann Immobilien GmbH, Musterstraße 28, 10115 Berlin",
    "branch": "real-estate",
    "subbranch": "IS24PROFI"
  }'

Request Body

Response

{
  "api-info": {
    "version": "1"
  },
  "provider": {
    "uuid": "0a3006b0-43c7-11e4-96eb-06df9a948f2f",
    "reference": "prov-001@yourCrm",
    "name": "Mustermann Immobilien",
    "email": "kontakt@mustermann-immo.de",
    "mobile": "+49 170 1234567",
    "phone": "+49 30 12345678",
    "impressum": "Mustermann Immobilien GmbH, Musterstraße 28, 10115 Berlin",
    "branch": "real-estate",
    "subbranch": "IS24PROFI"
  }
}

Get Provider

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

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

Response

Renvoie les données du Provider (comme pour Create Provider).

Erreurs

Staff

Le Staff désigne des Users associés à un Provider et ayant accès à son calendrier.

List Staff

Liste tous les membres du Staff d'un Provider.

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

Paramètres de chemin

Response

[
  {
    "reference": "user-123@yourCrm",
    "email": "thomas@example.com",
    "username": "thomas.anderson",
    "firstName": "Thomas",
    "lastName": "Anderson",
    "phone": "030 1101011",
    "mobile": "+49 170 1234567"
  },
  {
    "reference": "user-456@yourCrm",
    "email": "forrest@example.com",
    "username": "forrest.gump",
    "firstName": "Forrest",
    "lastName": "Gump",
    "phone": "030 123456789",
    "mobile": "+49 170 9876543"
  }
]

Étapes suivantes

Une fois votre structure organisationnelle configurée, vous pouvez :

• Configurer les Offerings - créer des ressources, produits et profils de contact
• Configurer le Scheduling - créer des disponibilités et des rendez-vous

Sujets connexes

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