Initial Setup

Questi endpoint dell'API timum servono per la configurazione iniziale una tantum della struttura organizzativa: crei Users, Accounts e Providers.

1. User - Persona con credenziali di accesso
2. Account - Cliente/azienda (richiede uno User come proprietario)
3. Provider - Profilo calendario (richiede uno User come proprietario)
4. Staff - Aggiungere dipendenti al Provider (opzionale)

Users

Uno User rappresenta una persona con credenziali di accesso, diritti di accesso e dati di contatto. Gli Users possono essere proprietari di Accounts e Providers, oltre a fungere da Staff o da persona di contatto.

Create User

Crea un nuovo User o restituisce quello esistente se il riferimento è già noto.

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

Parametri del percorso

Request Body

Algoritmo / Comportamento

• Il riferimento esiste già: Restituisce lo User esistente (200 OK). I campi phone, mobile, lastName, firstName vengono aggiornati.
• L'email esiste con un riferimento diverso: Viene creato un nuovo User con un'email generata (ad es. max+001@example.com).
• L'email esiste senza riferimento: Viene utilizzato lo User esistente. La sua verifica email viene invalidata, viene inviata una nuova email di verifica e il riferimento viene collegato.
• Nuovo User: Lo User viene creato (201 Created). La lingua viene ripresa dall'utente CRM che esegue l'azione (sovrascrivibile tramite il 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
  }
}

Errori

Get User

Recupera uno User in base al suo riferimento.

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

Parametri del percorso

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

Errori

Accounts

Un Account rappresenta un cliente in timum con un piano di servizio sottoscritto e dati di fatturazione. Ogni Account appartiene a uno User (proprietario).

Create Account

Crea un nuovo Account o restituisce quello esistente se il riferimento è già noto.

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

Algoritmo / Comportamento

• accountReference sconosciuta: Viene creato un nuovo Account (201 Created).
• accountReference già nota: Viene restituito l'Account esistente (200 OK). I campi dell'Account esistente non vengono sovrascritti.

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

Errori

Get Account

Recupera un Account in base al suo riferimento.

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

Errori

Providers

Un Provider rappresenta un profilo calendario che contiene risorse e servizi (Products). I Providers hanno membri dello Staff (Users) che hanno accesso al Provider.

Create Provider

Crea un nuovo 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

Recupera un Provider in base al suo riferimento.

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

Response

Restituisce i dati del Provider (come in Create Provider).

Errori

Staff

Lo Staff è costituito da Users assegnati a un Provider e che hanno accesso al suo calendario.

List Staff

Elenca tutti i membri dello Staff di un Provider.

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

Parametri del percorso

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

Prossimi passi

Dopo aver configurato la struttura organizzativa, può:

• Configurare le Offerings - creare risorse, prodotti e profili di contatto
• Configurare lo Scheduling - creare disponibilità e appuntamenti

Argomenti correlati

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