Vue d'ensemble de l'API REST

L'API timum permet aux développeurs d'intégrer entièrement la prise de rendez-vous par programmation dans votre plateforme, sous forme de solution en marque blanche.

Base URL

Toutes les requêtes API sont envoyées à l'URL de base suivante :

https://www.timum.de

Authentification

Toutes les requêtes API doivent être authentifiées avec votre clé API. La clé est transmise dans l'en-tête 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"

Obtenir une clé API

Vous recevrez votre clé API (également appelée "directUseSecret") de la part de timum lors de la mise en place de votre intégration. La clé est liée à votre ID CRM et permet d'accéder à toutes les ressources de votre contexte CRM.

Format de référence

timum utilise un format de référence unifié pour identifier les entités de manière unique. Les références se composent de deux parties, séparées par @ :

{uniqueId}@{platformName}

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

Composants

Domaines de l'API

L'API est structurée par cas d'usage :

1. Configuration initiale – Initial Setup

Users, Accounts, Providers, Staff - mettre en place la structure de base

2. Configuration – Configure Offerings

Resources, Products, Contact Profiles - définir l'offre

3. Planification des rendez-vous – Scheduling

Timeslots, Appointments, Participations, Customers

4. Réservation – Booking Flow

Endpoints orientés consommateur pour la réservation de rendez-vous

Format de réponse

Toutes les réponses de l'API sont au format JSON. Chaque réponse contient un objet api-info avec des informations de version :

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

Réponse d'erreur

En cas d'erreur, la réponse contient un tableau errors avec les codes d'erreur et les messages :

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

HTTP Status Codes

Codes d'erreur courants

CORS

L'API prend en charge le Cross-Origin Resource Sharing (CORS) pour les intégrations basées sur navigateur. Les requêtes preflight reçoivent une réponse automatique.

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

Prochaines étapes

• Initial Setup - Commencez par créer des Users et des Accounts
• Configure Offerings - Définissez les ressources et les produits
• Scheduling - Créez des disponibilités et des rendez-vous
• Booking Flow - Intégrez la réservation de rendez-vous

Pour les utilisateurs finaux

• Qu'est-ce qu'une ressource ?
• Qu'est-ce qu'un type de rendez-vous ?
• Comprendre les disponibilités