# Appuntamenti

> Servizi, team e appuntamenti in blocco per la tua agenda

- Pagina: https://tbit.app/it/docs/api/appointments
- URL base: `https://rest-api.tbit.app/v1`
- Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`)

## Panoramica

Ciò che ti serve per gestire l'agenda della tua attività da un altro sistema: i servizi che si prenotano con chi li eroga, il team, e il caricamento di appuntamenti in blocco. È lo stesso che fanno le tool del MCP list_services, list_collaborators e import_appointments, con gli stessi nomi dei campi.

## Endpoint

| Metodo | Percorso | Descrizione |
| --- | --- | --- |
| `GET` | `/v1/services` | I servizi che si prenotano, con chi li eroga |
| `GET` | `/v1/collaborators` | Il team: nome, email, ruolo e servizi che eroga |
| `POST` | `/v1/appointments/import` | Carica fino a 200 appuntamenti in una chiamata |

## Elenca i servizi

Ogni servizio porta id, name, duration_minutes, price, currency, location, active e collaborators (id, name ed email di chi lo eroga). L'id è quello che richiedi come service_id quando importi gli appuntamenti. I servizi che si affittano (camere, sale, veicoli) non compaiono qui.

`GET /v1/services`

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

Risposta:

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

## Elenca il team

Ogni persona porta id, name, email, role, attends_appointments (se eroga appuntamenti) e service_ids (i servizi che eroga). Quando una persona non ha un nome caricato, name arriva vuoto: identificala con la sua email.

`GET /v1/collaborators`

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

Risposta:

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

## Importa appuntamenti

Invia fino a 200 appuntamenti per chiamata in appointments. Ogni riga porta phone (con prefisso internazionale, per esempio 573001234567: il contatto si cerca per telefono e, se non esiste, viene creato) o contact_id (un contatto che esiste già: l'appuntamento va su quella scheda anche se non ha telefono, come chi scrive con un utente di WhatsApp; se invii anche phone, viene usato solo per avvisare), contact_name ed email opzionali, il servizio (service_id o service_name, il nome esatto senza badare alle maiuscole), chi lo gestisce (collaborator_id o collaborator_email; se il servizio lo gestisce una sola persona puoi ometterlo), start in ISO 8601 (senza fuso viene letto nel fuso dell'attività), end opzionale (per impostazione predefinita start più la durata del servizio), external_id (la chiave dell'evento nel tuo sistema: reimportare non duplica) e notes.

Opzioni, tutte al primo livello del corpo: notify_customer (per impostazione predefinita false: al cliente non arriva la conferma; true la invia come per qualsiasi appuntamento), send_reminders (per impostazione predefinita true), release_blocks (true rimuove i blocchi di quella persona che si incrociano con l'appuntamento), on_existing (skip o update: se esiste già un appuntamento con lo stesso external_id, lo lascia com'è o lo sposta senza avvisare nessuno) e dry_run (true valida tutto e dice cosa farebbe, senza scrivere nulla). Inizia sempre con dry_run.

La risposta dice per riga cosa è successo: status è created, updated, skipped o failed (would_create o would_update con dry_run), con appointment_id, contact_id e, se ha fallito, error con il motivo a parole («Andrés non eroga Endodonzia; la eroga: Geral Díaz.»). Una riga sbagliata non ferma le altre. Salva import_id: è quello che ti serve per annullare.

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

Risposta:

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

## Annulla un import

Invia solo undo_import_id con l'import_id che ti ha restituito l'importazione: tutti gli appuntamenti che quell'import ha creato restano annullati, senza avvisare nessuno, e il loro external_id resta libero per reimportarli.

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

Risposta:

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

## Regole ed errori

- La persona deve erogare quel servizio. Altrimenti la riga fallisce e l'errore dice chi lo eroga.
- Un appuntamento non può incrociarsi con un altro della stessa persona, né con un'altra riga dello stesso lotto. Se si incrocia con un blocco di agenda, la riga fallisce a meno che tu non invii release_blocks: true.
- Un lotto che non si può leggere interamente (vuoto, più di 200 righe, un campo sconosciuto nel corpo) risponde 400 VALIDATION_ERROR e non scrive nulla.
- Un lotto grande può richiedere tempo: ogni appuntamento crea il suo ordine e il suo contatto. Se i tuoi lotti superano i 100 appuntamenti, dividili in chiamate più piccole.
