# Rendez-vous

> Services, équipe et rendez-vous en lot pour votre agenda

- Page: https://tbit.app/fr/docs/api/appointments
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Aperçu

Ce qu'il vous faut pour gérer l'agenda de votre entreprise depuis un autre système : les services qui se planifient avec qui les assure, l'équipe, et le chargement de rendez-vous en lot. C'est ce que font les tools du MCP list_services, list_collaborators et import_appointments, avec les mêmes noms de champs.

## Endpoints

| Méthode | Route | Description |
| --- | --- | --- |
| `GET` | `/v1/services` | Les services que l'on planifie, avec qui les prend en charge |
| `GET` | `/v1/collaborators` | L'équipe : nom, e-mail, rôle et services pris en charge |
| `POST` | `/v1/appointments/import` | Charger jusqu'à 200 rendez-vous en un appel |

## Lister les services

Chaque service apporte id, name, duration_minutes, price, currency, location, active et collaborators (id, name et email de ceux qui le prennent en charge). L'id est celui que vous demandez comme service_id lors de l'import de rendez-vous. Les services qui se louent (chambres, salons, véhicules) n'apparaissent pas ici.

`GET /v1/services`

```bash
curl "https://rest-api.tbit.app/v1/services" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab34cd",
      "name": "Endodoncia",
      "duration_minutes": 60,
      "price": 350000,
      "currency": "COP",
      "location": "Sede norte · Calle 72 # 7-41",
      "active": true,
      "collaborators": [
        {
          "id": "6a0f3c2e9b1d4a0012ab0001",
          "name": "Geral Díaz",
          "email": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## Lister l'équipe

Chaque personne apporte id, name, email, role, attends_appointments (si elle prend des rendez-vous) et service_ids (les services qu'elle prend en charge). Quand une personne n'a pas de nom chargé, name arrive vide : identifiez-la par son e-mail.

`GET /v1/collaborators`

```bash
curl "https://rest-api.tbit.app/v1/collaborators" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "geral@tuclinica.co",
      "role": "ADMIN",
      "attends_appointments": true,
      "service_ids": [
        "6a0f3c2e9b1d4a0012ab34cd"
      ]
    }
  ]
}
```

## Importer des rendez-vous

Envoyez jusqu'à 200 rendez-vous par appel dans appointments. Chaque ligne porte phone (avec l'indicatif du pays, par exemple 573001234567 : le contact est recherché par téléphone et, s'il n'existe pas, il est créé) ou contact_id (un contact qui existe déjà : le rendez-vous va sur cette fiche même sans téléphone, comme quelqu'un qui écrit avec un compte WhatsApp ; si vous envoyez aussi phone, il sert seulement à prévenir), contact_name et email facultatifs, le service (service_id ou service_name, le nom exact sans tenir compte des majuscules), qui reçoit (collaborator_id ou collaborator_email ; si le service n'est assuré que par une seule personne vous pouvez l'omettre), start en ISO 8601 (sans fuseau, il est lu dans le fuseau de l'entreprise), end facultatif (par défaut start plus la durée du service), external_id (la clé de l'événement dans votre système : réimporter ne duplique pas) et notes.

Options, toutes au premier niveau du corps : notify_customer (par défaut false : le client ne reçoit pas de confirmation ; true l'envoie comme n'importe quel rendez-vous), send_reminders (par défaut true), release_blocks (true retire les blocages de cette personne qui croisent le rendez-vous), on_existing (skip ou update : si un rendez-vous existe déjà avec le même external_id, il le laisse tel quel ou le déplace sans prévenir personne) et dry_run (true valide tout et dit ce qu'il ferait, sans rien écrire). Commencez toujours par dry_run.

La réponse dit par ligne ce qui s'est passé : status est created, updated, skipped ou failed (would_create ou would_update avec dry_run), avec appointment_id, contact_id et, en cas d'échec, error avec la raison en mots (« Andrés ne prend pas en charge Endodoncia ; ce sont Geral Díaz qui le prennent en charge. »). Une mauvaise ligne n'arrête pas les autres. Gardez import_id : c'est ce dont vous avez besoin pour défaire.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "appointments": [
      {
        "phone": "573001234567",
        "contact_name": "Ana Pérez",
        "service_name": "Endodoncia",
        "collaborator_email": "geral@tuclinica.co",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
```

Réponse:

```json
{
  "data": {
    "import_id": null,
    "dry_run": true,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "external_id": "gcal-7f3k2",
        "status": "would_create",
        "contact_id": "6a0f3c2e9b1d4a0012ab9f10"
      }
    ]
  }
}
```

## Défaire un import

Envoyez seulement undo_import_id avec l'import_id que l'importation vous a renvoyé : tous les rendez-vous que cet import a créés restent annulés, sans prévenir personne, et leur external_id reste libre pour les réimporter.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
  }'
```

Réponse:

```json
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
```

## Règles et erreurs

- La personne doit prendre en charge ce service. Sinon, la ligne échoue et l'erreur dit qui le prend en charge.
- Un rendez-vous ne peut pas croiser un autre de la même personne, ni une autre ligne du même lot. S'il croise un blocage d'agenda, la ligne échoue sauf si vous envoyez release_blocks : true.
- Un lot qui ne peut pas être lu en entier (vide, plus de 200 lignes, un champ inconnu dans le corps) répond 400 VALIDATION_ERROR et n'écrit rien.
- Un grand lot peut prendre du temps : chaque rendez-vous crée sa commande et son contact. Si vos lots dépassent 100 rendez-vous, découpez-les en appels plus petits.
