> ## 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.

# Idempotenza

> Header Idempotency-Key per ripetere una richiesta senza creare doppioni.

Una richiesta può fallire per la rete dopo che il server l'ha già eseguita. Se la ripeti, rischi di prenotare due volte o di registrare due volte lo stesso incasso. L'header `Idempotency-Key` lo impedisce: la stessa chiave ripete la prima risposta invece di rifare l'operazione.

```http theme={null}
Idempotency-Key: chiamata-8f2a-prenota
```

## Dove si usa

Su questi endpoint è **obbligatoria**, perché l'operazione costa o non si annulla:

| Endpoint | Operazione |
| - | - |
| `POST /calendars/{id}/bookings` | Prenota un orario |
| `POST /appointments` | Crea un appuntamento fuori calendario |
| `POST /invoices/{id}/payments` | Registra un incasso |
| `POST /payment-links` | Crea un link di pagamento |
| `POST /conversations/{id}/messages` | Manda un messaggio WhatsApp |

Senza l'header, questi endpoint rispondono `400 invalid_request`.

È **facoltativa** sulle altre creazioni e azioni: `POST /patients`, `POST /appointments/{id}/move`, `/cancel`, `/confirm` e `/status`, `POST /treatment-plans`, `POST /tasks`, `POST /leads`, `POST /leads/{id}/activities` e `/convert`, `POST /calls`, `POST /voice/handoff`, `POST /webhook-deliveries/{id}/redeliver`. Gli endpoint che non la prevedono la ignorano.

## Comportamento

| Caso | Risposta |
| - | - |
| Prima richiesta con la chiave | Eseguita normalmente |
| Stessa chiave, prima richiesta riuscita (`2xx`) | La stessa risposta della prima, stesso status e stesso corpo, con l'header `Idempotent-Replayed: true`. L'operazione non si ripete |
| Stessa chiave, prima richiesta ancora in corso | `409 idempotency_in_progress`. Riprova dopo qualche secondo con la stessa chiave |
| Stessa chiave con un'altra operazione, un altro corpo o un'altra chiave API | `422 idempotency_key_reused` |
| Prima richiesta finita con un errore | La chiave si libera: la richiesta successiva con la stessa chiave viene eseguita da capo |

La prima risposta si conserva per **24 ore**. Dopo, la stessa chiave vale come nuova.

La chiave è legata alla chiave API, all'operazione e al corpo. Cliniche diverse possono usare la stessa stringa senza disturbarsi.

### Risposte con un segreto

`POST /webhook-endpoints` e `POST /webhook-endpoints/{id}/rotate-secret` mostrano un segreto una volta sola, e quella risposta non viene conservata. Una seconda richiesta con la stessa chiave risponde `409 conflict` con `details.reason: "response_not_stored"`, senza generare un altro segreto.

## Scegliere la chiave

Una chiave per ogni operazione, non per ogni tentativo. Per un agente vocale: l'id della telefonata più l'azione, per esempio `<id-telefonata>-prenota`. Ogni ripetizione della stessa prenotazione usa la stessa chiave; una seconda prenotazione nella stessa telefonata ne usa un'altra.

```bash theme={null}
curl -s -X POST "https://api.dentalspace.ai/v1/invoices/$FATTURA/payments" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incasso-pos-000123" \
  -d '{"amount":150,"method":"credit_card"}'
```

I campi esatti del corpo sono nella pagina dell'endpoint.


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