> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dentalspace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentazione di dentalspace. Il testo completo, incluso il riferimento API, è in /llms-full.txt. Per endpoint, campi e codici di errore la fonte di verità è openapi.json: non usare endpoint o campi non documentati.

# Introduzione all'API

> API REST v1 di dentalspace: indirizzo, formato di richieste e risposte, versioni, elenco delle risorse.

L'API v1 collega altri programmi alla tua clinica: agenti vocali, gestionali, CRM, siti di prenotazione, strumenti di analisi. Espone pazienti, agenda, preventivi, fatture, documenti, attività, contatti commerciali, messaggi WhatsApp, telefonate, webhook ed eventi.

<Note>
  L'API è inclusa nel piano **Clinic**. Con un altro piano ogni richiesta risponde `403 plan_required`.
</Note>

## Indirizzo

```text theme={null}
https://api.dentalspace.ai/v1
```

Tutte le richieste usano HTTPS.

## Formato

| Elemento | Formato |
| - | - |
| Corpo di richiesta e risposta | JSON, `Content-Type: application/json`. Al massimo 1 MB |
| Nomi dei campi | `camelCase`, in inglese: `firstName`, `startTime` |
| Date | `YYYY-MM-DD` |
| Istanti (`startTime`, `createdAt`, `updatedAt`) | ISO 8601 con fuso |
| Telefono in ingresso | Qualsiasi formato italiano o internazionale; il server lo normalizza |
| Telefono in uscita | E.164, ad esempio `+393391112233` |
| Importi | Euro, numero decimale |
| ID | UUID |

## Versioni

La versione è nel percorso: `/v1`. Non esiste un header di versione. Una modifica che rompe i client esistenti esce come `/v2`; i campi nuovi possono comparire in `/v1` in qualsiasi momento, quindi il tuo client deve ignorare i campi che non conosce.

## Risorse

| Area | Endpoint |
| - | - |
| Meta | `/me`, `/health`, `/openapi.json` |
| Studio | `/facilities`, `/doctors`, `/calendars`, `/treatments` |
| Pazienti | `/patients`, `/patients/lookup`, `/patients/search`, `/patients/{id}/clinical` |
| Agenda | `/calendars/{id}/availability`, `/calendars/{id}/bookings`, `/appointments` |
| Preventivi | `/treatment-plans` |
| Fatture e pagamenti | `/invoices`, `/payment-plans`, `/payment-links` |
| Documenti | `/documents/{id}`, `/patients/{id}/documents` |
| Attività | `/tasks` |
| Contatti commerciali | `/leads` |
| Messaggi WhatsApp | `/conversations` |
| Telefonate e agente vocale | `/calls`, `/voice/context`, `/voice/handoff` |
| Webhook ed eventi | `/events`, `/webhook-endpoints`, `/webhook-deliveries`. Vedi [Webhook](/api/webhook) |

Ogni endpoint ha una pagina con parametri, risposte e playground nella barra laterale. Il [riferimento completo](/api/riferimento-completo) li riporta tutti in una pagina. La specifica OpenAPI 3.1 è servita anche dall'API: `GET /openapi.json`.

## Regole generali

* **Una chiave, una clinica.** La chiave vede solo la sua clinica, e solo alcune sedi se è limitata. Una risorsa di un'altra clinica risponde sempre `404 not_found`, mai `403`. Vedi [Autenticazione](/api/autenticazione).
* **Scope per area.** Ogni endpoint chiede uno scope, indicato nella sua pagina. I dati clinici hanno scope separati, spenti di default. Vedi [Dati clinici](/api/dati-clinici).
* **Elenchi a cursore.** Gli elenchi restituiscono `{ "data", "nextCursor" }`. Vedi [Paginazione](/api/paginazione).
* **Esiti negativi con `200`.** Alcune risposte dicono «non trovato» o «occupato» senza essere errori: `GET /patients/lookup` con un numero sconosciuto risponde `200` con `found: false`.
* **Modifiche sicure.** Le risorse modificabili restituiscono un `ETag`: rimandalo in `If-Match` e la modifica passa solo se nessuno ha cambiato la risorsa nel frattempo. Altrimenti `409 conflict` con `details.reason: "version_mismatch"`.
* **Errori uniformi.** `{ "error": { "code", "message", "details", "requestId" } }`. Vedi [Errori](/api/errori).
* **Identificativo della richiesta.** Ogni risposta porta `X-Request-Id`. Citalo all'assistenza.

## Esempio: prenotare una visita

```bash theme={null}
export DS_KEY="dsk_live_..."
export CAL="<id del calendario>"

# 1. Chi è questo numero?
curl -s "https://api.dentalspace.ai/v1/patients/lookup?phone=3391112233" \
  -H "Authorization: Bearer $DS_KEY"

# 2. Orari liberi della prossima settimana
curl -s "https://api.dentalspace.ai/v1/calendars/$CAL/availability?from=2026-10-12&to=2026-10-16" \
  -H "Authorization: Bearer $DS_KEY"

# 3. Prenota uno degli orari restituiti
curl -s -X POST "https://api.dentalspace.ai/v1/calendars/$CAL/bookings" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chiamata-8f2a-prenota" \
  -d '{"patientId":"<id del paziente>","start":"2026-10-13T09:30:00+02:00"}'
```

I campi esatti di ogni corpo sono nella pagina dell'endpoint.

<CardGroup cols={2}>
  <Card title="Autenticazione" icon="key" href="/api/autenticazione">
    Chiavi, scope per area, chiavi di prova.
  </Card>

  <Card title="Errori" icon="triangle-alert" href="/api/errori">
    Formato dell'errore e codici.
  </Card>

  <Card title="Idempotenza" icon="repeat" href="/api/idempotenza">
    Ripetere una creazione senza doppioni.
  </Card>

  <Card title="Paginazione" icon="list" href="/api/paginazione">
    Elenchi a cursore e sincronizzazione.
  </Card>

  <Card title="Limiti di richiesta" icon="gauge" href="/api/limiti">
    Quante richieste, header `X-RateLimit-*`.
  </Card>

  <Card title="Webhook" icon="webhook" href="/api/webhook">
    Eventi, firma, ritentativi.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.