Prompt per agenti

Integra l'API v1 di dentalspace (gestionale per studi e cliniche dentistiche) in <sistema: es. "un agente vocale che risponde al telefono dello studio", "il nostro CRM">.

## Fonti
Leggi queste fonti prima di scrivere codice. Non usare endpoint, campi o codici di errore che non compaiono nella specifica.
- Documentazione completa, riferimento API compreso: https://docs.dentalspace.ai/llms-full.txt
- Specifica OpenAPI 3.1 (fonte di verità): https://api.dentalspace.ai/v1/openapi.json

## Dati
- Indirizzo: https://api.dentalspace.ai/v1
- Autenticazione: header `Authorization: Bearer dsk_live_...`. Leggi la chiave dalla variabile d'ambiente DENTALSPACE_API_KEY.
- La chiave vede una sola clinica; GET /me dice quali scope e quali sedi ha.
- Date `YYYY-MM-DD`; istanti ISO 8601 con fuso; telefoni in uscita in E.164.

## Regole
1. Per riconoscere chi chiama usa GET /patients/lookup?phone=... `found: false` (status 200) = numero sconosciuto. `kind: "family"` = più pazienti con lo stesso numero: chiedi per chi è.
2. Un numero sconosciuto si salva come contatto commerciale: POST /leads con `source: "phone"`. Se poi prenota, prima convertilo con POST /leads/{id}/convert, poi prenota con il `patientId` restituito.
3. Per prenotare: GET /calendars/{id}/availability, poi POST /calendars/{id}/bookings con uno degli orari restituiti, tale e quale. Se `complete` è false, continua con from=`nextFrom`.
4. Su ogni POST che crea o cambia qualcosa manda `Idempotency-Key`: una chiave per operazione (es. `<id-telefonata>-prenota`), identica a ogni ripetizione. Su bookings, appointments, payments, payment-links e messaggi è obbligatoria.
   - Stesso status e stesso corpo con `Idempotent-Replayed: true`: è la risposta della prima richiesta.
   - 409 `idempotency_in_progress`: ripeti dopo qualche secondo con la stessa chiave.
   - 422 `idempotency_key_reused`: chiave usata per un'altra operazione; errore del client.
5. Gli errori hanno la forma `{ "error": { "code", "message", "details", "requestId" } }`. La logica usa `code` e `details.reason`, mai `message`.
   - 409 `no_availability`: l'orario non è più libero; proponi `details.alternatives`.
   - 409 `conflict` con `reason: "version_mismatch"`: rileggi la risorsa e riprova con il nuovo `ETag` in `If-Match`.
   - 401 `api_key_revoked`, 403 `plan_required`, 403 `insufficient_scope`: non ripetere, segnala.
   - 429 `rate_limited`: aspetta i secondi di `Retry-After`.
   - 500 e 503: ripeti con backoff esponenziale.
6. Negli elenchi guarda solo `nextCursor` per sapere se ci sono altre pagine, mai il numero di elementi.
7. Non chiedere scope `clinical:*` se non servono: sono spenti di default e ogni lettura finisce nel registro accessi della clinica.

## Consegna
- Client tipizzato, una funzione per endpoint, generato dalla specifica o scritto a mano.
- Gestione di tutti i valori di `code` della specifica.
- Test per: numero sconosciuto; orario preso nel frattempo; ripetizione idempotente; 429.
- Nessun segreto nel codice.