Panoramica dell'API REST

L'API di timum consente agli sviluppatori di integrare in modo completamente programmatico la prenotazione di appuntamenti nella propria piattaforma come soluzione white-label.

Base URL

Tutte le richieste API vengono inviate al seguente URL di base:

https://www.timum.de

Autenticazione

Tutte le richieste API devono essere autenticate con la Sua chiave API. La chiave viene trasmessa nell'intestazione HTTP X-TIMUM-CLIENT-ID:

curl -X GET "https://www.timum.de/crms/{crmId}/resources" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json"

Ottenere la chiave API

Riceverà la Sua chiave API (chiamata anche "directUseSecret") da timum al momento della configurazione della Sua integrazione. La chiave è associata al Suo ID CRM e consente l'accesso a tutte le risorse all'interno del Suo contesto CRM.

Formato di riferimento

timum utilizza un formato di riferimento unificato per identificare in modo univoco le entità. I riferimenti sono composti da due parti, separate da @:

{uniqueId}@{platformName}

Beispiele:
- 12345@yourCrmUser          (User-Referenz)
- abc-def-123@yourCrmAccount (Account-Referenz)
- property-42@yourCrmResource (Ressourcen-Referenz)

Componenti

Aree dell'API

L'API è strutturata in base ai casi d'uso:

1. Configurazione iniziale – Initial Setup

Users, Accounts, Providers, Staff - creare la struttura di base

2. Configurazione – Configure Offerings

Resources, Products, Contact Profiles - definire l'offerta

3. Pianificazione degli appuntamenti – Scheduling

Timeslots, Appointments, Participations, Customers

4. Prenotazione – Booking Flow

Endpoint rivolti al consumatore per la prenotazione degli appuntamenti

Formato di risposta

Tutte le risposte API sono in formato JSON. Ogni risposta include un oggetto api-info con le informazioni sulla versione:

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

Risposta di errore

In caso di errori, la risposta contiene un array errors con codici di errore e messaggi:

{
  "api-info": {
    "version": "1"
  },
  "errors": [
    {
      "errorCode": "201",
      "message": "Das überlappt mit einem anderen Termin."
    }
  ]
}

HTTP Status Codes

Codici di errore comuni

CORS

L'API supporta il Cross-Origin Resource Sharing (CORS) per le integrazioni basate su browser. Le richieste preflight ricevono una risposta automatica.

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Auth-Token

Prossimi passi

• Initial Setup - Inizi creando Users e Accounts
• Configure Offerings - Definisca risorse e prodotti
• Scheduling - Crei disponibilità e appuntamenti
• Booking Flow - Integri la prenotazione degli appuntamenti

Per gli utenti finali

• Cos'è una risorsa?
• Cos'è un tipo di appuntamento?
• Comprendere le disponibilità