Initial Setup

Estos endpoints de la API de timum sirven para la configuración inicial única de su estructura organizativa: cree Users, Accounts y Providers.

1. User - Persona con datos de acceso
2. Account - Cliente/empresa (requiere un User como propietario)
3. Provider - Perfil de calendario (requiere un User como propietario)
4. Staff - Añadir empleados al Provider (opcional)

Users

Un User representa una persona con credenciales de acceso, permisos y datos de contacto. Los Users pueden ser propietarios de Accounts y Providers, y también pueden actuar como Staff o como persona de contacto.

Create User

Crea un nuevo User o devuelve uno existente si la referencia ya es conocida.

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

Parámetros de ruta

Request Body

Algoritmo / Comportamiento

• La referencia ya existe: Devuelve el User existente (200 OK). Se actualizan los campos phone, mobile, lastName, firstName.
• El correo existe con una referencia distinta: Se crea un nuevo User con un correo generado (p. ej. max+001@example.com).
• El correo existe sin referencia: Se utiliza el User existente. Se invalida su verificación de correo, se envía un nuevo correo de verificación y se adjunta la referencia.
• Nuevo User: Se crea el User (201 Created). El idioma se toma del usuario CRM que ejecuta la acción (se puede sobrescribir mediante la 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
  }
}

Errores

Get User

Recupera un User a partir de su referencia.

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

Parámetros de ruta

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

Errores

Accounts

Un Account representa un cliente en timum con un plan de servicio contratado y datos de facturación. Cada Account pertenece a un User (propietario).

Create Account

Crea un nuevo Account o devuelve uno existente si la referencia ya es conocida.

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 / Comportamiento

• accountReference desconocida: Se crea un nuevo Account (201 Created).
• accountReference ya conocida: Se devuelve el Account existente (200 OK). Los campos del Account existente no se sobrescriben.

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

Errores

Get Account

Recupera un Account a partir de su referencia.

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

Errores

Providers

Un Provider representa un perfil de calendario que contiene recursos y servicios (Products). Los Providers tienen miembros del Staff (Users) con acceso al Provider.

Create Provider

Crea un nuevo 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 a partir de su referencia.

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

Response

Devuelve los datos del Provider (como en Create Provider).

Errores

Staff

El Staff está formado por Users asignados a un Provider que tienen acceso a su calendario.

List Staff

Enumera todos los miembros del Staff de un Provider.

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

Parámetros de ruta

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

Próximos pasos

Después de configurar su estructura organizativa, puede:

• Configurar Offerings - crear recursos, productos y perfiles de contacto
• Configurar Scheduling - crear disponibilidades y citas

Temas relacionados

• Resumen de la API
• ¿Qué es un recurso?
• ¿Qué es un tipo de cita?