# Afspraken

> Diensten, team en afspraken in bulk voor je agenda

- Pagina: https://tbit.app/nl/docs/api/appointments
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`)

## Overzicht

Wat je nodig hebt om de agenda van je bedrijf vanuit een ander systeem te beheren: de diensten die worden ingepland met wie ze uitvoert, het team, en het in bulk laden van afspraken. Het is hetzelfde als wat de MCP-tools list_services, list_collaborators en import_appointments doen, met dezelfde veldnamen.

## Endpoints

| Methode | Route | Beschrijving |
| --- | --- | --- |
| `GET` | `/v1/services` | De diensten die je plant, met wie ze uitvoert |
| `GET` | `/v1/collaborators` | Het team: naam, e-mail, rol en diensten die iemand uitvoert |
| `POST` | `/v1/appointments/import` | Laad tot 200 afspraken in één aanroep |

## Diensten opvragen

Elke dienst bevat id, name, duration_minutes, price, currency, location, active en collaborators (id, name en email van wie hem uitvoert). Het id is wat je als service_id opgeeft bij het importeren van afspraken. Diensten die je verhuurt (kamers, zalen, voertuigen) staan hier niet.

`GET /v1/services`

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

Response:

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

## Het team opvragen

Elke persoon bevat id, name, email, role, attends_appointments (of die afspraken uitvoert) en service_ids (de diensten die die persoon uitvoert). Als een persoon geen naam heeft, is name leeg: herken die persoon aan het e-mailadres.

`GET /v1/collaborators`

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

Response:

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

## Afspraken importeren

Stuur tot 200 afspraken per aanroep in appointments. Elke rij heeft phone (met landcode, bijvoorbeeld 573001234567: het contact wordt op telefoonnummer gezocht en, als het niet bestaat, aangemaakt) of contact_id (een contact dat al bestaat: de afspraak gaat naar dat profiel ook als het geen telefoonnummer heeft, zoals iemand die schrijft met een WhatsApp-gebruiker; als je ook phone meestuurt, wordt dat alleen gebruikt om te melden), contact_name en email optioneel, de service (service_id of service_name, de exacte naam ongeacht hoofdletters), wie het verzorgt (collaborator_id of collaborator_email; als de service door één persoon wordt verzorgd kun je het weglaten), start in ISO 8601 (zonder zone wordt het in de zone van het bedrijf gelezen), end optioneel (standaard start plus de duur van de service), external_id (de sleutel van het event in jouw systeem: opnieuw importeren dupliceert niet) en notes.

Opties, allemaal op het eerste niveau van de body: notify_customer (standaard false: de klant krijgt geen bevestiging; true stuurt die zoals bij elke afspraak), send_reminders (standaard true), release_blocks (true haalt de blokkades van die persoon weg die met de afspraak overlappen), on_existing (skip of update: als er al een afspraak met hetzelfde external_id bestaat, laat hij die staan of verplaatst hij die zonder iemand te waarschuwen) en dry_run (true controleert alles en zegt wat hij zou doen, zonder iets te schrijven). Begin altijd met dry_run.

De reactie zegt per rij wat er gebeurde: status is created, updated, skipped of failed (would_create of would_update met dry_run), met appointment_id, contact_id en, als het mislukte, error met de reden in woorden («Andrés voert Endodoncia niet uit; dat doen: Geral Díaz.»). Een slechte rij stopt de andere niet. Bewaar import_id: dat heb je nodig om het ongedaan te maken.

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

Response:

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

## Een import ongedaan maken

Stuur alleen undo_import_id met het import_id dat de import teruggaf: alle afspraken die die import aanmaakte worden geannuleerd, zonder iemand te waarschuwen, en hun external_id komt vrij om ze opnieuw te importeren.

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

Response:

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

## Regels en fouten

- De persoon moet die dienst uitvoeren. Zo niet, mislukt de rij en zegt de fout wie hem wel uitvoert.
- Een afspraak mag niet overlappen met een andere van dezelfde persoon, noch met een andere rij uit dezelfde batch. Als hij overlapt met een agendablokkade, mislukt de rij tenzij je release_blocks: true meestuurt.
- Een batch die niet helemaal leesbaar is (leeg, meer dan 200 rijen, een onbekend veld in de body) antwoordt 400 VALIDATION_ERROR en schrijft niets.
- Een grote batch kan even duren: elke afspraak maakt zijn bestelling en zijn contact aan. Als je batches meer dan 100 afspraken bevatten, splits ze dan in kleinere aanroepen.
