Riferimento completo - dentalspace

Indirizzo: https://api.dentalspace.ai/v1. Autenticazione: header Authorization: Bearer dsk_live_... su ogni richiesta. Specifica sorgente: openapi.json.

La chiave che sta chiamando

GET /me Clinica, chiave (scope, sedi, scadenza), limiti e modalita’. Basta una chiave valida, senza scope.

Risposte

Status	Descrizione
`200`	La chiave e la sua clinica.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`organization`	object	sì
`organization.id`	string (uuid)	sì
`organization.name`	string	sì
`apiKey`	object	sì
`apiKey.id`	string (uuid)	sì
`apiKey.name`	string	sì
`apiKey.prefix`	string	sì	L’inizio della chiave, per riconoscerla: dsk_live_ab12.
`apiKey.last4`	string	sì	Le ultime 4 cifre.
`apiKey.scopes`	array di string	sì
`apiKey.facilityIds`	array di string (uuid) \| null	sì	Le sedi a cui e’ limitata; null = tutte.
`apiKey.expiresAt`	string \| null	sì
`livemode`	boolean	sì	false per una chiave dsk_test_: nessun messaggio parte verso l’esterno.
`rateLimit`	object	sì
`rateLimit.organization`	object	sì
`rateLimit.organization.per10Seconds`	integer	sì
`rateLimit.organization.perDay`	integer	sì
`rateLimit.apiKey`	object	sì
`rateLimit.apiKey.per10Seconds`	integer	sì
`rateLimit.apiKey.perDay`	integer	sì

Stato del servizio

GET /health Non richiede chiave. Senza chiave. 200 se l’API e il database rispondono, 503 unavailable altrimenti.

Risposte

Status	Descrizione
`200`	Il servizio risponde.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`status`	string	sì
`time`	string	sì	L’ora del server (ISO 8601, UTC).

Specifica OpenAPI 3.1

GET /openapi.json Non richiede chiave. Senza chiave. Generata dagli stessi schemi che validano le richieste.

Risposte

Status	Descrizione
`200`	La specifica.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Le sedi della clinica

GET /facilities Scope: clinic:read. Indirizzo, telefono e orari di apertura. Una chiave limitata a delle sedi vede solo quelle.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).

Risposte

Status	Descrizione
`200`	Una pagina di sedi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].name`	string	sì
`data[].street`	string \| null	sì
`data[].city`	string \| null	sì
`data[].province`	string \| null	sì
`data[].zipCode`	string \| null	sì
`data[].phone`	string \| null	sì
`data[].email`	string \| null	sì
`data[].isMainLocation`	boolean	sì
`data[].avgAppointmentMinutes`	number \| null	sì
`data[].workingSchedule`	object	sì	Gli orari di apertura, come li salva l’app.
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Una sede

GET /facilities/{id} Scope: clinic:read. Dove siete e che orari fate.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La sede.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`name`	string	sì
`street`	string \| null	sì
`city`	string \| null	sì
`province`	string \| null	sì
`zipCode`	string \| null	sì
`phone`	string \| null	sì
`email`	string \| null	sì
`isMainLocation`	boolean	sì
`avgAppointmentMinutes`	number \| null	sì
`workingSchedule`	object	sì	Gli orari di apertura, come li salva l’app.
`updatedAt`	string \| null	sì

Le poltrone attive di una sede

GET /facilities/{id}/chairs Scope: clinic:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Le poltrone attive (non paginato: nextCursor e’ sempre null).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].facilityId`	string (uuid)	sì
`data[].name`	string	sì
`data[].color`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

I medici della clinica

GET /doctors Scope: clinic:read. Nome, specialita’ e sedi in cui lavorano; nessun dato di contatto. Una chiave limitata a delle sedi vede solo i medici di quelle sedi (una pagina puo’ quindi contenere meno di limit medici).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).

Risposte

Status	Descrizione
`200`	Una pagina di medici.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].firstName`	string \| null	sì
`data[].lastName`	string \| null	sì
`data[].specialties`	array di string	sì
`data[].facilityIds`	array di string (uuid)	sì	Le sedi in cui lavora (appartenenza attiva).
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

I calendari prenotabili

GET /calendars Scope: clinic:read. Con le regole di prenotazione: preavviso, orizzonte, disdetta e spostamento consentiti, prestazioni e medici.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`facilityId`	query	string (uuid)	no	Solo i calendari di questa sede.

Risposte

Status	Descrizione
`200`	Una pagina di calendari.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].facilityId`	string (uuid)	sì
`data[].name`	string	sì
`data[].durationMinutes`	integer	sì
`data[].minNoticeHours`	integer	sì	Preavviso minimo per prenotare.
`data[].bookingHorizonDays`	integer	sì	Quanti giorni avanti si puo’ prenotare.
`data[].allowBooking`	boolean	sì
`data[].allowReschedule`	boolean	sì
`data[].allowCancel`	boolean	sì
`data[].doctorAssignment`	string	sì	auto: sceglie il programma; patient_choice: sceglie il paziente.
`data[].treatmentIds`	array di string (uuid)	sì	Le prestazioni prenotabili su questo calendario.
`data[].doctorIds`	array di string (uuid)	sì	I medici del calendario.
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Un calendario

GET /calendars/{id} Scope: clinic:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Il calendario con le prestazioni ammesse.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`facilityId`	string (uuid)	sì
`name`	string	sì
`durationMinutes`	integer	sì
`minNoticeHours`	integer	sì	Preavviso minimo per prenotare.
`bookingHorizonDays`	integer	sì	Quanti giorni avanti si puo’ prenotare.
`allowBooking`	boolean	sì
`allowReschedule`	boolean	sì
`allowCancel`	boolean	sì
`doctorAssignment`	string	sì	auto: sceglie il programma; patient_choice: sceglie il paziente.
`treatmentIds`	array di string (uuid)	sì	Le prestazioni prenotabili su questo calendario.
`doctorIds`	array di string (uuid)	sì	I medici del calendario.
`updatedAt`	string	sì

Il listino

GET /treatments Scope: clinic:read. Codice, nome, durata e prezzo delle prestazioni. Di default solo quelle attive. L’elenco e’ ordinato per id: updatedSince non e’ disponibile (400).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`active`	query	string: `true`, `false`	no	`false` = anche le prestazioni disattivate.

Risposte

Status	Descrizione
`200`	Una pagina di prestazioni.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].code`	string \| null	sì
`data[].name`	string	sì
`data[].category`	string \| null	sì
`data[].description`	string \| null	sì
`data[].defaultDurationMinutes`	number \| null	sì
`data[].price`	number \| null	sì	Prezzo di listino in euro.
`data[].vatRate`	number \| null	sì
`data[].isActive`	boolean	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Una prestazione

GET /treatments/{id} Scope: clinic:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La prestazione.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`code`	string \| null	sì
`name`	string	sì
`category`	string \| null	sì
`description`	string \| null	sì
`defaultDurationMinutes`	number \| null	sì
`price`	number \| null	sì	Prezzo di listino in euro.
`vatRate`	number \| null	sì
`isActive`	boolean	sì

Chi e’ questo numero?

GET /patients/lookup Scope: patients:read. Confronto esatto sul numero (in qualunque formato). kind: patient se e’ di un paziente, family se lo stesso numero e’ di piu’ pazienti (genitore e figli), lead se non e’ di nessun paziente ma di un contatto commerciale, null se non lo conosciamo. I candidati hanno solo nome, anno di nascita e ultime 4 cifre.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone`	query	string	sì

Risposte

Status	Descrizione
`200`	Chi corrisponde a quel numero.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`found`	boolean	sì
`kind`	string: `patient`, `family`, `lead` \| null	sì
`candidates`	array di object	sì
`candidates[].id`	string (uuid)	sì
`candidates[].kind`	string: `patient`, `lead`	sì
`candidates[].name`	string	sì
`candidates[].birthYear`	integer \| null	sì
`candidates[].phoneLast4`	string	sì	Le ultime 4 cifre del numero.
`candidates[].archived`	boolean	sì

Cerca un paziente

GET /patients/search Scope: patients:read. Trova la persona anche scritta male: nome, telefono in qualunque forma, codice fiscale, email. Restituisce pochi candidati con il punteggio; closeMatches dice quanti sono altrettanto probabili del migliore.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`q`	query	string	sì
`facilityId`	query	string (uuid)	no	Solo i pazienti di questa sede.
`limit`	query	integer	no

Risposte

Status	Descrizione
`200`	I candidati, dal piu’ probabile.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].name`	string	sì
`data[].birthYear`	integer \| null	sì
`data[].phoneLast4`	string	sì	Le ultime 4 cifre del numero.
`data[].archived`	boolean	sì
`data[].score`	number	sì	Da 0 a 1: quanto somiglia a cio’ che hai cercato.
`data[].matchedBy`	string: `name`, `phone`, `taxCode`, `email`	sì
`data[].lastVisitAt`	string \| null	sì
`closeMatches`	integer	sì

Elenco dei pazienti

GET /patients Scope: patients:read. Anagrafica, senza dati sanitari (quelli stanno solo nella scheda e nel /clinical, con clinical:read). Di default solo i pazienti attivi. Per cercare per nome usa /patients/search.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`phone`	query	string	no	In qualunque formato: si confronta quello canonico.
`email`	query	string	no	Senza distinguere maiuscole.
`facilityId`	query	string (uuid)	no
`archived`	query	string: `true`, `false`	no	`true` = solo gli archiviati.

Risposte

Status	Descrizione
`200`	Una pagina di pazienti.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].firstName`	string	sì
`data[].lastName`	string	sì
`data[].email`	string \| null	sì
`data[].phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`data[].dateOfBirth`	string \| null	sì
`data[].gender`	string \| null	sì
`data[].taxCode`	string \| null	sì
`data[].address`	object	sì
`data[].address.street`	string \| null	sì
`data[].address.city`	string \| null	sì
`data[].address.zip`	string \| null	sì
`data[].address.country`	string \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].referralSource`	string \| null	sì
`data[].isActive`	boolean	sì	false = archiviato.
`data[].archivedAt`	string \| null	sì
`data[].createdAt`	string \| null	sì
`data[].updatedAt`	string	sì
`data[].allergies`	array di string	no	Solo con clinical:read.
`data[].medications`	array di string	no	Solo con clinical:read.
`data[].conditions`	array di string	no	Solo con clinical:read.
`data[].notes`	string \| null	no	Solo con clinical:read.
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea un paziente

POST /patients Scope: patients:write. 409 conflict (details.patientId) se esiste gia’ un paziente con lo stesso nome e la stessa email o lo stesso telefono. Allergie, farmaci, condizioni e note richiedono anche clinical:write. Con Idempotency-Key un nuovo tentativo non crea un secondo paziente.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`firstName`	string	sì
`lastName`	string	sì
`email`	string (email)	no
`phone`	string	no	In qualunque formato: si salva quello canonico.
`dateOfBirth`	string (date)	no
`gender`	string: `male`, `female`, `other`, `prefer_not_to_say`	no
`taxCode`	string	no
`address`	object	no
`address.street`	string	no
`address.city`	string	no
`address.zip`	string	no
`address.country`	string	no
`facilityId`	string (uuid)	no	Obbligatoria se la chiave e’ limitata a delle sedi.
`referralSource`	string: `walk_in`, `internet`, `social`, `companies`, `referral`	no
`allergies`	array di string	no	Richiede clinical:write.
`medications`	array di string	no	Richiede clinical:write.
`conditions`	array di string	no	Richiede clinical:write.
`notes`	string	no	Richiede clinical:write.

Risposte

Status	Descrizione
`201`	Il paziente creato (header ETag).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `forbidden`, `plan_required`, `insufficient_scope`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`firstName`	string	sì
`lastName`	string	sì
`email`	string \| null	sì
`phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`dateOfBirth`	string \| null	sì
`gender`	string \| null	sì
`taxCode`	string \| null	sì
`address`	object	sì
`address.street`	string \| null	sì
`address.city`	string \| null	sì
`address.zip`	string \| null	sì
`address.country`	string \| null	sì
`facilityId`	string (uuid) \| null	sì
`referralSource`	string \| null	sì
`isActive`	boolean	sì	false = archiviato.
`archivedAt`	string \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string	sì
`allergies`	array di string	no	Solo con clinical:read.
`medications`	array di string	no	Solo con clinical:read.
`conditions`	array di string	no	Solo con clinical:read.
`notes`	string \| null	no	Solo con clinical:read.

La scheda di un paziente

GET /patients/{id} Scope: patients:read. Con clinical:read la scheda include allergie, farmaci, condizioni e note, e la lettura entra nel registro accessi. L’header ETag va rimandato come If-Match per modificarla.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Il paziente.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`firstName`	string	sì
`lastName`	string	sì
`email`	string \| null	sì
`phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`dateOfBirth`	string \| null	sì
`gender`	string \| null	sì
`taxCode`	string \| null	sì
`address`	object	sì
`address.street`	string \| null	sì
`address.city`	string \| null	sì
`address.zip`	string \| null	sì
`address.country`	string \| null	sì
`facilityId`	string (uuid) \| null	sì
`referralSource`	string \| null	sì
`isActive`	boolean	sì	false = archiviato.
`archivedAt`	string \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string	sì
`allergies`	array di string	no	Solo con clinical:read.
`medications`	array di string	no	Solo con clinical:read.
`conditions`	array di string	no	Solo con clinical:read.
`notes`	string \| null	no	Solo con clinical:read.

Modifica un paziente

PATCH /patients/{id} Scope: patients:write. Solo i campi indicati; null svuota un campo (non il nome). If-Match col valore di ETag della scheda: se e’ cambiata, 409. Allergie, farmaci, condizioni e note richiedono anche clinical:write.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`firstName`	string	no
`lastName`	string	no
`email`	string (email) \| null	no
`phone`	string \| null	no
`dateOfBirth`	string (date) \| null	no
`gender`	string: `male`, `female`, `other`, `prefer_not_to_say` \| null	no
`taxCode`	string \| null	no
`address`	object	no
`address.street`	string \| null	no
`address.city`	string \| null	no
`address.zip`	string \| null	no
`address.country`	string \| null	no
`facilityId`	string (uuid)	no
`referralSource`	string: `walk_in`, `internet`, `social`, `companies`, `referral` \| null	no
`allergies`	array di string	no	Richiede clinical:write.
`medications`	array di string	no	Richiede clinical:write.
`conditions`	array di string	no	Richiede clinical:write.
`notes`	string \| null	no	Richiede clinical:write.

Risposte

Status	Descrizione
`200`	La scheda aggiornata (header ETag).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`firstName`	string	sì
`lastName`	string	sì
`email`	string \| null	sì
`phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`dateOfBirth`	string \| null	sì
`gender`	string \| null	sì
`taxCode`	string \| null	sì
`address`	object	sì
`address.street`	string \| null	sì
`address.city`	string \| null	sì
`address.zip`	string \| null	sì
`address.country`	string \| null	sì
`facilityId`	string (uuid) \| null	sì
`referralSource`	string \| null	sì
`isActive`	boolean	sì	false = archiviato.
`archivedAt`	string \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string	sì
`allergies`	array di string	no	Solo con clinical:read.
`medications`	array di string	no	Solo con clinical:read.
`conditions`	array di string	no	Solo con clinical:read.
`notes`	string \| null	no	Solo con clinical:read.

Archivia un paziente

POST /patients/{id}/archive Scope: patients:write. Non cancella niente: il paziente esce dagli elenchi (archived=true per vederli) e si puo’ riattivare. Ripeterla non cambia nulla.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La scheda aggiornata (header ETag).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`firstName`	string	sì
`lastName`	string	sì
`email`	string \| null	sì
`phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`dateOfBirth`	string \| null	sì
`gender`	string \| null	sì
`taxCode`	string \| null	sì
`address`	object	sì
`address.street`	string \| null	sì
`address.city`	string \| null	sì
`address.zip`	string \| null	sì
`address.country`	string \| null	sì
`facilityId`	string (uuid) \| null	sì
`referralSource`	string \| null	sì
`isActive`	boolean	sì	false = archiviato.
`archivedAt`	string \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string	sì
`allergies`	array di string	no	Solo con clinical:read.
`medications`	array di string	no	Solo con clinical:read.
`conditions`	array di string	no	Solo con clinical:read.
`notes`	string \| null	no	Solo con clinical:read.

Riattiva un paziente archiviato

POST /patients/{id}/restore Scope: patients:write. Riporta fra gli attivi un paziente archiviato. Ripeterla non cambia nulla.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La scheda aggiornata (header ETag).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`firstName`	string	sì
`lastName`	string	sì
`email`	string \| null	sì
`phone`	string \| null	sì	In forma canonica: +<paese><numero>.
`dateOfBirth`	string \| null	sì
`gender`	string \| null	sì
`taxCode`	string \| null	sì
`address`	object	sì
`address.street`	string \| null	sì
`address.city`	string \| null	sì
`address.zip`	string \| null	sì
`address.country`	string \| null	sì
`facilityId`	string (uuid) \| null	sì
`referralSource`	string \| null	sì
`isActive`	boolean	sì	false = archiviato.
`archivedAt`	string \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string	sì
`allergies`	array di string	no	Solo con clinical:read.
`medications`	array di string	no	Solo con clinical:read.
`conditions`	array di string	no	Solo con clinical:read.
`notes`	string \| null	no	Solo con clinical:read.

Gli appuntamenti di un paziente

GET /patients/{id}/appointments Scope: patients:read e appointments:read. upcoming=true: solo quelli che devono ancora avvenire e non sono disdetti, saltati o conclusi. Senza note cliniche. Titolo e motivo sono testo libero: la lettura finisce nel registro accessi. Ordinati per ultima modifica.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`upcoming`	query	string: `true`, `false`	no

Risposte

Status	Descrizione
`200`	Una pagina di appuntamenti.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid)	sì
`data[].startTime`	string	sì
`data[].endTime`	string	sì
`data[].status`	string	sì
`data[].type`	string \| null	sì
`data[].title`	string \| null	sì
`data[].reason`	string \| null	sì
`data[].doctorId`	string (uuid) \| null	sì
`data[].chairId`	string (uuid) \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].calendarId`	string (uuid) \| null	sì
`data[].origin`	string	sì
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

I preventivi di un paziente

GET /patients/{id}/treatment-plans Scope: patients:read e treatment_plans:read. Riepilogo senza voci, denti e diagnosi (il dettaglio e’ in /treatment-plans/\{id\}). Esclusi quelli eliminati.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).

Risposte

Status	Descrizione
`200`	Una pagina di preventivi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid)	sì
`data[].name`	string	sì
`data[].status`	string \| null	sì
`data[].totalCost`	number \| null	sì
`data[].presentedAmount`	number \| null	sì
`data[].acceptedAmount`	number \| null	sì
`data[].presentedAt`	string \| null	sì
`data[].acceptedAt`	string \| null	sì
`data[].assignedDoctorId`	string (uuid) \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].createdAt`	string \| null	sì
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

I dati sanitari di un paziente

GET /patients/{id}/clinical Scope: clinical:read. Allergie, farmaci, condizioni e odontogramma. Serve lo scope clinical:read (spento di default) e ogni lettura viene registrata nel registro accessi della clinica.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	I dati sanitari.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`patientId`	string (uuid)	sì
`allergies`	array di string	sì
`medications`	array di string	sì
`declaredConditions`	array di string	sì	Le condizioni scritte a mano sulla scheda.
`conditions`	array di object	sì	Le condizioni del catalogo diagnosticate al paziente.
`conditions[].conditionId`	string (uuid)	sì
`conditions[].name`	string	sì
`conditions[].severity`	string \| null	sì
`conditions[].isBiohazard`	boolean	sì
`conditions[].diagnosedAt`	string \| null	sì
`conditions[].notes`	string \| null	sì
`notes`	string \| null	sì
`odontograms`	array di object	sì
`odontograms[].id`	string (uuid)	sì
`odontograms[].odontogramType`	string	sì
`odontograms[].toothData`	object	sì	Lo stato dei denti, come lo salva l’app.
`odontograms[].notes`	string \| null	sì
`odontograms[].updatedAt`	string	sì

I documenti di un paziente

GET /patients/{id}/documents Scope: documents:read. I documenti da firmare del paziente (consensi, moduli) con lo stato della firma. Solo i metadati: il contenuto e’ in /documents/\{id\}. Il titolo e’ testo libero: la lettura finisce nel registro accessi. Ordinati per data di creazione.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.

Risposte

Status	Descrizione
`200`	Una pagina di documenti.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].name`	string	sì
`data[].status`	string: `draft`, `sent`, `signed`, `voided` \| null	sì	Stato della firma: draft, sent (inviato da firmare), signed, voided (annullato).
`data[].mimeType`	string \| null	sì	Sempre null: il file non si scarica dall’API.
`data[].sizeBytes`	number \| null	sì	Sempre null: il file non si scarica dall’API.
`data[].createdAt`	string \| null	sì
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Orari liberi di un calendario

GET /calendars/{id}/availability Scope: appointments:read. Gli orari prenotabili fra from e to, con le regole del calendario (medici, fasce, durata, preavviso, orizzonte). In un calendario «scelta del paziente» lo stesso orario compare una volta per ogni medico libero, e ognuno conta in limit. La risposta dice la finestra davvero cercata (window) e se gli orari sono tutti (complete); se no, si continua con from=nextFrom. Una pagina non spezza un orario fra i suoi medici: se a uno stesso orario i medici liberi sono piu’ di limit, 400 su limit.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`from`	query	string (date-time)	sì	Da quando cercare (ISO 8601). Il preavviso del calendario vale comunque.
`to`	query	string (date-time)	sì	Fino a quando (ISO 8601), al massimo 31 giorni dopo from.
`doctorId`	query	string (uuid)	no	Solo gli orari di questo medico (deve ricevere nel calendario).
`patientId`	query	string (uuid)	no	Il paziente: nei calendari ad assegnazione automatica, prima il suo medico abituale.
`limit`	query	integer	no	Quanti orari al massimo (1-200).

Risposte

Status	Descrizione
`200`	Gli orari liberi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì	In ordine di inizio: tutti gli orari liberi di `window` (se complete) o quelli che iniziano prima di `nextFrom`.
`data[].start`	string	sì	Inizio (ISO 8601).
`data[].end`	string	sì	Fine (ISO 8601).
`data[].doctorId`	string (uuid)	sì	Il medico che lo riceverebbe.
`data[].chairId`	string (uuid) \| null	sì	La poltrona di default di quel medico in quella sede.
`window`	object \| null	sì	La finestra davvero cercata: quella chiesta, stretta da preavviso e orizzonte del calendario. null = le regole del calendario non lasciano niente in quella chiesta (tutta oltre l’orizzonte o dentro il preavviso).
`window.from`	string	sì
`window.to`	string	sì
`complete`	boolean	sì	true: `data` contiene tutti gli orari liberi di `window`. false: ce ne sono altri, chiedili con from=nextFrom.
`nextFrom`	string \| null	sì	Se complete=false: il `from` della richiesta successiva (stesso `to`). Altrimenti null.

Prenota un orario

POST /calendars/{id}/bookings Scope: appointments:write. Ricontrolla l’orario con le regole del calendario e lo prenota (stato scheduled). 409 no_availability se non e’ piu’ libero (reason: slot_taken) o non rispetta il preavviso (reason: min_notice), con details.alternatives; 409 conflict con reason: booking_disabled se il calendario non accetta prenotazioni da fuori.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	sì	Obbligatoria. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`patientId`	string (uuid)	sì
`start`	string (date-time)	sì	L’inizio di uno degli orari di /availability, tale e quale.
`doctorId`	string (uuid)	no	Il medico scelto; senza, lo sceglie il calendario (abituale, poi il primo libero).
`title`	string	no	Senza, il nome del calendario.
`reason`	string	no	Il motivo della visita, come lo dice il paziente.
`origin`	string: `api`, `voice`	no	voice se prenota l’agente vocale.

Risposte

Status	Descrizione
`201`	L’appuntamento prenotato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `no_availability`, `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Elenco degli appuntamenti

GET /appointments Scope: appointments:read. In ordine di ultima modifica (updatedSince per sincronizzare), o di orario con sort=start. Senza note ne’ note cliniche: si leggono dal dettaglio, con clinical:read. Titolo e motivo sono testo libero: la lettura finisce nel registro accessi.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`from`	query	string (date-time)	no	Solo gli appuntamenti che iniziano da qui (incluso).
`to`	query	string (date-time)	no	Solo quelli che iniziano prima di qui (escluso).
`facilityId`	query	string (uuid)	no
`doctorId`	query	string (uuid)	no
`patientId`	query	string (uuid)	no
`status`	query	string	no	Uno o piu’ stati separati da virgola: draft, scheduled, confirmed, checked_in, in_progress, completed, cancelled, no_show, pending, postponed.
`sort`	query	string: `updated`, `start`	no	updated (predefinito): per ultima modifica, con updatedSince. start: per orario di inizio, senza updatedSince.

Risposte

Status	Descrizione
`200`	Una pagina di appuntamenti.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid)	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].doctorId`	string (uuid) \| null	sì
`data[].chairId`	string (uuid) \| null	sì
`data[].calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`data[].start`	string	sì	ISO 8601 con fuso (UTC).
`data[].end`	string	sì	ISO 8601 con fuso (UTC).
`data[].status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`data[].type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`data[].category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`data[].title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`data[].reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`data[].notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`data[].origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`data[].treatmentPlanId`	string (uuid) \| null	sì
`data[].createdAt`	string \| null	sì
`data[].updatedAt`	string \| null	sì
`data[].clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`data[].completionNotes`	string \| null	no	Solo con lo scope clinical:read.
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea un appuntamento fuori calendario

POST /appointments Scope: appointments:write. Per i gestionali che sanno gia’ medico, sede e orario: nessuna regola di calendario, solo il controllo di sovrapposizione su medico e poltrona (409 no_availability, reason: slot_taken). Per prenotare per conto di un paziente usa /calendars/{id}/bookings.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	sì	Obbligatoria. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`patientId`	string (uuid)	sì
`facilityId`	string (uuid)	sì
`doctorId`	string (uuid)	sì
`chairId`	string (uuid)	no	Deve stare nella sede.
`start`	string (date-time)	sì
`end`	string (date-time)	sì	Dopo start, entro 12 ore.
`status`	string: `draft`, `scheduled`, `confirmed`	no
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other`	no
`title`	string	no
`reason`	string	no
`notes`	string	no
`origin`	string: `api`, `voice`	no

Risposte

Status	Descrizione
`201`	L’appuntamento creato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `no_availability`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Un appuntamento

GET /appointments/{id} Scope: appointments:read. Con l’ETag da rimandare in If-Match. Note e note cliniche solo con clinical:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	L’appuntamento.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Modifica titolo, motivo o note

PATCH /appointments/{id} Scope: appointments:write. Solo i testi: per l’orario c’e’ /move, per lo stato /status. Con If-Match (l’ETag ricevuto) la modifica passa solo se nessuno ha cambiato l’appuntamento nel frattempo, altrimenti 409 conflict.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio
`title`	string \| null	no
`reason`	string \| null	no
`notes`	string \| null	no

Risposte

Status	Descrizione
`200`	L’appuntamento modificato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Sposta un appuntamento

POST /appointments/{id}/move Scope: appointments:write. Cambia solo l’orario (medico, sede e durata restano), con le regole del calendario di provenienza. 409 no_availability (slot_taken / min_notice) con details.alternatives; 409 conflict con reason reschedule_disabled, status_not_movable, doctor_not_in_calendar o no_calendar.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`start`	string (date-time)	sì	Il nuovo inizio: uno degli orari di /availability del suo calendario.

Risposte

Status	Descrizione
`200`	L’appuntamento spostato (o gia’ a quell’ora).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `no_availability`, `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Disdici un appuntamento

POST /appointments/{id}/cancel Scope: appointments:write. La disdetta del paziente, con le regole del calendario di provenienza. 409 conflict con reason cancel_disabled, min_notice, status_not_cancellable o no_calendar. Lo staff che annulla senza regole usa /status con cancelled.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Risposte

Status	Descrizione
`200`	L’appuntamento disdetto (o gia’ disdetto).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Conferma la presenza

POST /appointments/{id}/confirm Scope: appointments:write. Porta l’appuntamento in confirmed (da draft o scheduled). 409 conflict con reason: transition_not_allowed, details.status e details.allowedTransitions; 409 no_availability se rimetterlo in agenda si sovrapporrebbe a un altro.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Risposte

Status	Descrizione
`200`	L’appuntamento confermato (o gia’ confermato).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `no_availability`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Cambia lo stato

POST /appointments/{id}/status Scope: appointments:write. Il cambio di stato dello staff, lungo lo stesso grafo dell’app (completed no: lo scrive il completamento della visita). Nessuna regola di calendario: la disdetta del paziente e’ /cancel. 409 conflict con reason: transition_not_allowed, details.status e details.allowedTransitions; 409 no_availability se rimetterlo in agenda si sovrapporrebbe a un altro.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`status`	string: `confirmed`, `scheduled`, `cancelled`, `postponed`, `draft`, `in_progress`, `no_show`	sì

Risposte

Status	Descrizione
`200`	L’appuntamento nel nuovo stato (o gia’ in quello).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `no_availability`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`doctorId`	string (uuid) \| null	sì
`chairId`	string (uuid) \| null	sì
`calendarId`	string (uuid) \| null	sì	Il calendario da cui e’ nato: le sue regole valgono per spostarlo e disdirlo. null = fuori calendario.
`start`	string	sì	ISO 8601 con fuso (UTC).
`end`	string	sì	ISO 8601 con fuso (UTC).
`status`	string: `draft`, `scheduled`, `confirmed`, `checked_in`, `in_progress`, `completed`, `cancelled`, `no_show`, `pending`, `postponed`	sì
`type`	string: `checkup`, `treatment`, `consultation`, `emergency`, `other` \| null	sì
`category`	string: `recall`, `treatment_plan`, `first_visit`, `case_study`, `standard` \| null	sì
`title`	string \| null	sì	Ogni lettura finisce nel registro accessi (testo libero).
`reason`	string \| null	sì	Il motivo della visita. Ogni lettura finisce nel registro accessi (testo libero).
`notes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`origin`	string: `manual`, `bot`, `voice`, `api`	sì	Da dove e’ nato: manual (agenda), bot (WhatsApp), voice (agente vocale), api.
`treatmentPlanId`	string (uuid) \| null	sì
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`clinicalNotes`	string \| null	no	Solo con lo scope clinical:read (l’accesso finisce nel registro).
`completionNotes`	string \| null	no	Solo con lo scope clinical:read.

Elenco dei preventivi

GET /treatment-plans Scope: treatment_plans:read. Senza voci e senza dati clinici; quelli nel cestino non compaiono.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`patientId`	query	string (uuid)	no	Solo i preventivi di questo paziente.
`status`	query	string: `draft`, `proposed`, `standby`, `accepted`, `rejected`, `in_progress`, `completed`	no

Risposte

Status	Descrizione
`200`	Una pagina di preventivi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid)	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].name`	string	sì
`data[].description`	string \| null	sì
`data[].status`	string: `draft`, `proposed`, `standby`, `accepted`, `rejected`, `in_progress`, `completed`	sì
`data[].totalCost`	number \| null	sì
`data[].presentedAmount`	number \| null	sì
`data[].presentedAt`	string \| null	sì
`data[].acceptedAmount`	number \| null	sì
`data[].acceptedAt`	string \| null	sì
`data[].doctorId`	string (uuid) \| null	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea una bozza di preventivo dal listino

POST /treatment-plans Scope: treatment_plans:write. I prezzi sono quelli del listino. Nasce sempre come bozza (draft): la conferma una persona nell’app.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`patientId`	string (uuid)	sì
`items`	array di object	sì
`items[].treatmentId`	string (uuid)	sì	La prestazione del listino.
`items[].quantity`	integer	no
`items[].tooth`	integer	no	Dente (FDI). Chiede clinical:write.
`items[].surface`	string	no	Superficie. Chiede clinical:write.
`name`	string	no
`description`	string	no
`doctorId`	string (uuid)	no
`facilityId`	string (uuid)	no	Predefinita: la sede del paziente.

Risposte

Status	Descrizione
`201`	La bozza creata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `forbidden`, `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`name`	string	sì
`description`	string \| null	sì
`status`	string: `draft`, `proposed`, `standby`, `accepted`, `rejected`, `in_progress`, `completed`	sì
`totalCost`	number \| null	sì
`presentedAmount`	number \| null	sì
`presentedAt`	string \| null	sì
`acceptedAmount`	number \| null	sì
`acceptedAt`	string \| null	sì
`doctorId`	string (uuid) \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`items`	array di object	sì
`items[].id`	string (uuid)	sì
`items[].treatmentId`	string (uuid) \| null	sì
`items[].name`	string \| null	sì
`items[].cost`	number \| null	sì
`items[].status`	string \| null	sì
`items[].priority`	integer \| null	sì
`items[].doctorId`	string (uuid) \| null	sì
`items[].tooth`	integer \| null	no	Solo con clinical:read.
`items[].surface`	string \| null	no	Solo con clinical:read.
`items[].treatmentArea`	string \| null	no	Solo con clinical:read.
`items[].diagnosisId`	string (uuid) \| null	no	Solo con clinical:read.
`odontogramType`	string \| null	no	Solo con clinical:read.
`toothData`	object \| null	no	Solo con clinical:read.
`diagnoses`	array di object	no	Solo con clinical:read.
`diagnoses[].id`	string (uuid)	sì
`diagnoses[].tooth`	integer \| null	sì
`diagnoses[].issueType`	string \| null	sì
`diagnoses[].issueCategory`	string \| null	sì
`diagnoses[].treatmentArea`	string \| null	sì
`diagnoses[].surfaces`	array di string \| null	sì
`diagnoses[].severity`	string \| null	sì
`diagnoses[].note`	string \| null	sì
`diagnoses[].status`	string \| null	sì

Un preventivo, con le voci

GET /treatment-plans/{id} Scope: treatment_plans:read. Con lo scope clinical:read anche denti, superfici, odontogramma e diagnosi (e l’accesso finisce nel registro).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Il preventivo.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`name`	string	sì
`description`	string \| null	sì
`status`	string: `draft`, `proposed`, `standby`, `accepted`, `rejected`, `in_progress`, `completed`	sì
`totalCost`	number \| null	sì
`presentedAmount`	number \| null	sì
`presentedAt`	string \| null	sì
`acceptedAmount`	number \| null	sì
`acceptedAt`	string \| null	sì
`doctorId`	string (uuid) \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`items`	array di object	sì
`items[].id`	string (uuid)	sì
`items[].treatmentId`	string (uuid) \| null	sì
`items[].name`	string \| null	sì
`items[].cost`	number \| null	sì
`items[].status`	string \| null	sì
`items[].priority`	integer \| null	sì
`items[].doctorId`	string (uuid) \| null	sì
`items[].tooth`	integer \| null	no	Solo con clinical:read.
`items[].surface`	string \| null	no	Solo con clinical:read.
`items[].treatmentArea`	string \| null	no	Solo con clinical:read.
`items[].diagnosisId`	string (uuid) \| null	no	Solo con clinical:read.
`odontogramType`	string \| null	no	Solo con clinical:read.
`toothData`	object \| null	no	Solo con clinical:read.
`diagnoses`	array di object	no	Solo con clinical:read.
`diagnoses[].id`	string (uuid)	sì
`diagnoses[].tooth`	integer \| null	sì
`diagnoses[].issueType`	string \| null	sì
`diagnoses[].issueCategory`	string \| null	sì
`diagnoses[].treatmentArea`	string \| null	sì
`diagnoses[].surfaces`	array di string \| null	sì
`diagnoses[].severity`	string \| null	sì
`diagnoses[].note`	string \| null	sì
`diagnoses[].status`	string \| null	sì

Cambia lo stato di un preventivo

POST /treatment-plans/{id}/status Scope: treatment_plans:write. proposed → standby (presentato) · proposed/standby → accepted/rejected. Una bozza non cambia stato via API.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`status`	string: `standby`, `accepted`, `rejected`	sì	standby = presentato al paziente.
`acceptedAmount`	number	no	Solo con accepted: l’importo accettato, maggiore di 0 e non oltre il totale del preventivo (altrimenti 400). Predefinito: il totale.

Risposte

Status	Descrizione
`200`	Il preventivo aggiornato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`name`	string	sì
`description`	string \| null	sì
`status`	string: `draft`, `proposed`, `standby`, `accepted`, `rejected`, `in_progress`, `completed`	sì
`totalCost`	number \| null	sì
`presentedAmount`	number \| null	sì
`presentedAt`	string \| null	sì
`acceptedAmount`	number \| null	sì
`acceptedAt`	string \| null	sì
`doctorId`	string (uuid) \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`items`	array di object	sì
`items[].id`	string (uuid)	sì
`items[].treatmentId`	string (uuid) \| null	sì
`items[].name`	string \| null	sì
`items[].cost`	number \| null	sì
`items[].status`	string \| null	sì
`items[].priority`	integer \| null	sì
`items[].doctorId`	string (uuid) \| null	sì
`items[].tooth`	integer \| null	no	Solo con clinical:read.
`items[].surface`	string \| null	no	Solo con clinical:read.
`items[].treatmentArea`	string \| null	no	Solo con clinical:read.
`items[].diagnosisId`	string (uuid) \| null	no	Solo con clinical:read.
`odontogramType`	string \| null	no	Solo con clinical:read.
`toothData`	object \| null	no	Solo con clinical:read.
`diagnoses`	array di object	no	Solo con clinical:read.
`diagnoses[].id`	string (uuid)	sì
`diagnoses[].tooth`	integer \| null	sì
`diagnoses[].issueType`	string \| null	sì
`diagnoses[].issueCategory`	string \| null	sì
`diagnoses[].treatmentArea`	string \| null	sì
`diagnoses[].surfaces`	array di string \| null	sì
`diagnoses[].severity`	string \| null	sì
`diagnoses[].note`	string \| null	sì
`diagnoses[].status`	string \| null	sì

Elenco delle fatture

GET /invoices Scope: billing:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`patientId`	query	string (uuid)	no
`status`	query	string: `draft`, `issued`, `paid`, `overdue`, `cancelled`	no
`from`	query	string (date)	no	Emesse da questo giorno (compreso).
`to`	query	string (date)	no	Emesse fino a questo giorno (compreso).

Risposte

Status	Descrizione
`200`	Una pagina di fatture.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid) \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].number`	integer \| null	sì	Il numero, assegnato all’emissione.
`data[].status`	string: `draft`, `issued`, `paid`, `overdue`, `cancelled`	sì
`data[].totalAmount`	number	sì
`data[].amountPaid`	number	sì
`data[].balanceDue`	number \| null	sì
`data[].dueDate`	string \| null	sì
`data[].issuedDate`	string \| null	sì
`data[].paymentMethod`	string \| null	sì
`data[].paymentTraced`	boolean \| null	sì
`data[].payerIsPatient`	boolean \| null	sì
`data[].payerName`	string \| null	sì
`data[].patientName`	string \| null	sì
`data[].doctorId`	string (uuid) \| null	sì
`data[].installmentNumber`	integer \| null	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Una fattura, con le righe

GET /invoices/{id} Scope: billing:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La fattura.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid) \| null	sì
`facilityId`	string (uuid) \| null	sì
`number`	integer \| null	sì	Il numero, assegnato all’emissione.
`status`	string: `draft`, `issued`, `paid`, `overdue`, `cancelled`	sì
`totalAmount`	number	sì
`amountPaid`	number	sì
`balanceDue`	number \| null	sì
`dueDate`	string \| null	sì
`issuedDate`	string \| null	sì
`paymentMethod`	string \| null	sì
`paymentTraced`	boolean \| null	sì
`payerIsPatient`	boolean \| null	sì
`payerName`	string \| null	sì
`patientName`	string \| null	sì
`doctorId`	string (uuid) \| null	sì
`installmentNumber`	integer \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`lines`	array di object	sì
`lines[].id`	string (uuid)	sì
`lines[].description`	string \| null	sì
`lines[].quantity`	integer \| null	sì
`lines[].unitPrice`	number \| null	sì
`lines[].vatRate`	number \| null	sì
`lines[].total`	number \| null	sì
`lines[].treatmentItemId`	string (uuid) \| null	sì

Gli incassi di una fattura

GET /invoices/{id}/payments Scope: billing:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Gli incassi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].invoiceId`	string (uuid) \| null	sì
`data[].amount`	number	sì
`data[].method`	string: `cash`, `credit_card`, `debit_card`, `bank_transfer`, `insurance`, `other` \| null	sì
`data[].reference`	string \| null	sì
`data[].notes`	string \| null	sì
`data[].processedAt`	string \| null	sì

Registra un incasso

POST /invoices/{id}/payments Scope: billing:write. Solo su fatture emesse o scadute, fino al saldo. Chiede Idempotency-Key. Saldata, la fattura passa a paid.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	sì	Obbligatoria. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`amount`	number	sì	In euro, al centesimo.
`method`	string: `cash`, `credit_card`, `debit_card`, `bank_transfer`, `insurance`, `other`	sì
`notes`	string	no

Risposte

Status	Descrizione
`201`	L’incasso e la fattura aggiornata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`payment`	object	sì
`payment.id`	string (uuid)	sì
`payment.invoiceId`	string (uuid) \| null	sì
`payment.amount`	number	sì
`payment.method`	string: `cash`, `credit_card`, `debit_card`, `bank_transfer`, `insurance`, `other` \| null	sì
`payment.reference`	string \| null	sì
`payment.notes`	string \| null	sì
`payment.processedAt`	string \| null	sì
`invoice`	object	sì
`invoice.id`	string (uuid)	sì
`invoice.patientId`	string (uuid) \| null	sì
`invoice.facilityId`	string (uuid) \| null	sì
`invoice.number`	integer \| null	sì	Il numero, assegnato all’emissione.
`invoice.status`	string: `draft`, `issued`, `paid`, `overdue`, `cancelled`	sì
`invoice.totalAmount`	number	sì
`invoice.amountPaid`	number	sì
`invoice.balanceDue`	number \| null	sì
`invoice.dueDate`	string \| null	sì
`invoice.issuedDate`	string \| null	sì
`invoice.paymentMethod`	string \| null	sì
`invoice.paymentTraced`	boolean \| null	sì
`invoice.payerIsPatient`	boolean \| null	sì
`invoice.payerName`	string \| null	sì
`invoice.patientName`	string \| null	sì
`invoice.doctorId`	string (uuid) \| null	sì
`invoice.installmentNumber`	integer \| null	sì
`invoice.createdAt`	string	sì
`invoice.updatedAt`	string	sì

Piani di pagamento e rate

GET /payment-plans Scope: billing:read. state=open (predefinito): rate non pagate · overdue: non pagate e scadute · all: tutte.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`patientId`	query	string (uuid)	no
`state`	query	string: `open`, `overdue`, `all`	no

Risposte

Status	Descrizione
`200`	Una pagina di piani.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid) \| null	sì
`data[].treatmentPlanId`	string (uuid) \| null	sì
`data[].type`	string: `prepaid`, `on_account`, `split_60_20_20`, `per_treatment`, `pos`, `downpayment`, `financing` \| null	sì
`data[].totalAmount`	number \| null	sì
`data[].installmentCount`	integer \| null	sì
`data[].createdAt`	string	sì
`data[].installments`	array di object	sì
`data[].installments[].id`	string (uuid)	sì
`data[].installments[].amount`	number	sì
`data[].installments[].amountPaid`	number \| null	sì
`data[].installments[].dueDate`	string \| null	sì
`data[].installments[].status`	string \| null	sì	pending / paid.
`data[].installments[].paidAt`	string \| null	sì
`data[].installments[].paymentMethod`	string: `cash`, `credit_card`, `debit_card`, `bank_transfer`, `insurance`, `other` \| null	sì
`data[].installments[].overdue`	boolean	sì	Non pagata e con la scadenza passata.
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea un link di pagamento

POST /payment-links Scope: billing:write. Un link Stripe (Checkout, sul conto collegato della clinica) per il residuo di una fattura emessa o scaduta, o di una rata non pagata. L’importo non si sceglie. Non invia niente: restituisce l’URL. Chiede Idempotency-Key. Con una chiave di prova verifica tutto ma non crea il link (livemode: false, url: null).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	sì	Obbligatoria. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`invoiceId`	string (uuid)	no	La fattura da incassare (emessa o scaduta).
`installmentId`	string (uuid)	no	Oppure la rata di un piano di pagamento.
`description`	string	no	Cio’ che il paziente legge su Stripe. Predefinito: «Prestazione odontoiatrica».

Risposte

Status	Descrizione
`201`	Il link creato (o, con una chiave di prova, quello che sarebbe).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid) \| null	sì	null con una chiave di prova: nessun link creato.
`url`	string \| null	sì	L’indirizzo di Stripe da mandare al paziente; scade dopo un’ora. null con una chiave di prova.
`livemode`	boolean	sì	false con una chiave di prova (dsk_test_): niente passa da Stripe.
`amount`	number	sì	In euro: il residuo della fattura o della rata al momento della creazione.
`currency`	string	sì
`expiresAt`	string \| null	sì
`patientId`	string (uuid)	sì
`invoiceId`	string (uuid) \| null	sì
`installmentId`	string (uuid) \| null	sì

Un documento del paziente

GET /documents/{id} Scope: documents:read. Un documento da firmare (consenso, modulo, preventivo) con lo stato della firma. Non e’ un file: con clinical:read esce il contenuto (HTML) e la firma. Niente download e niente upload: vedi la guida.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Il documento.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid) \| null	sì
`name`	string	sì
`type`	string: `preventivo`, `privacy_consent`, `clinical_consent`, `extraction_consent`, `generic` \| null	sì
`status`	string: `draft`, `sent`, `signed`, `voided` \| null	sì	draft, sent (inviato da firmare), signed, voided (annullato).
`signedAt`	string \| null	sì
`signingExpiresAt`	string \| null	sì	Fino a quando vale il link di firma; solo per `sent`.
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì
`content`	object	no	Solo con clinical:read; la lettura finisce nel registro accessi.
`content.html`	string \| null	sì	Il testo del documento, in HTML.
`content.signatureImage`	string \| null	sì	La firma, come data URL PNG; null se non firmato.

Elenco delle attivita’

GET /tasks Scope: tasks:read. Ordinate per ultima modifica; updatedSince per la sincronizzazione incrementale.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`status`	query	string: `todo`, `in_progress`, `done`	no
`assigneeId`	query	string (uuid)	no
`patientId`	query	string (uuid)	no
`dueBefore`	query	string (date-time)	no	Solo con scadenza prima di questo istante.

Risposte

Status	Descrizione
`200`	Una pagina di attivita’.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].title`	string	sì
`data[].status`	string: `todo`, `in_progress`, `done`	sì
`data[].dueDate`	string \| null	sì	Scadenza, istante ISO 8601.
`data[].assigneeId`	string (uuid) \| null	sì	Il profilo a cui e’ assegnata.
`data[].patientId`	string (uuid) \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].type`	string \| null	sì	manual, recall, o un tipo creato dall’app.
`data[].createdAt`	string \| null	sì
`data[].updatedAt`	string \| null	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea un’attivita’

POST /tasks Scope: tasks:write. Con Idempotency-Key un nuovo tentativo non crea un doppione. Una chiave limitata a delle sedi deve indicare facilityId.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio
`title`	string	sì
`dueDate`	string (date-time)	no
`assigneeId`	string (uuid)	no
`patientId`	string (uuid)	no
`facilityId`	string (uuid)	no
`type`	string: `manual`, `recall`	no

Risposte

Status	Descrizione
`201`	L’attivita’ creata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`title`	string	sì
`status`	string: `todo`, `in_progress`, `done`	sì
`dueDate`	string \| null	sì	Scadenza, istante ISO 8601.
`assigneeId`	string (uuid) \| null	sì	Il profilo a cui e’ assegnata.
`patientId`	string (uuid) \| null	sì
`facilityId`	string (uuid) \| null	sì
`type`	string \| null	sì	manual, recall, o un tipo creato dall’app.
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì

Modifica un’attivita’

PATCH /tasks/{id} Scope: tasks:write. Solo i campi mandati cambiano; null toglie scadenza o assegnatario. Con If-Match (l’ETag ricevuto) la modifica fallisce con 409 se qualcuno l’ha cambiata nel frattempo.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio
`title`	string	no
`status`	string: `todo`, `in_progress`, `done`	no
`dueDate`	string (date-time) \| null	no
`assigneeId`	string (uuid) \| null	no

Risposte

Status	Descrizione
`200`	L’attivita’ aggiornata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`title`	string	sì
`status`	string: `todo`, `in_progress`, `done`	sì
`dueDate`	string \| null	sì	Scadenza, istante ISO 8601.
`assigneeId`	string (uuid) \| null	sì	Il profilo a cui e’ assegnata.
`patientId`	string (uuid) \| null	sì
`facilityId`	string (uuid) \| null	sì
`type`	string \| null	sì	manual, recall, o un tipo creato dall’app.
`createdAt`	string \| null	sì
`updatedAt`	string \| null	sì

Elenco dei lead

GET /leads Scope: leads:read. Ordinati per ultima modifica. Le attivita’ si leggono dal dettaglio.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`status`	query	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	no
`source`	query	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	no
`assignedTo`	query	string (uuid)	no

Risposte

Status	Descrizione
`200`	Una pagina di lead.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].firstName`	string	sì
`data[].lastName`	string \| null	sì
`data[].email`	string \| null	sì
`data[].phone`	string \| null	sì
`data[].source`	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	sì
`data[].sourceDetail`	string \| null	sì
`data[].status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	sì
`data[].assignedTo`	string (uuid) \| null	sì
`data[].estimatedValue`	number \| null	sì
`data[].notes`	string \| null	sì
`data[].nextFollowUpAt`	string \| null	sì
`data[].lastContactedAt`	string \| null	sì
`data[].lostReason`	string \| null	sì
`data[].convertedPatientId`	string (uuid) \| null	sì
`data[].convertedAt`	string \| null	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`data[].activities`	array di object	no	Solo nel dettaglio.
`data[].activities[].id`	string	sì
`data[].activities[].kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`data[].activities[].body`	string	sì
`data[].activities[].at`	string	sì	Istante ISO 8601.
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea un lead

POST /leads Scope: leads:write. Se esiste gia’ un lead con lo stesso telefono (qualunque formato: si confronta quello normalizzato) o la stessa email, NON ne crea un altro: risponde 200 con quello esistente e deduplicated: true, senza modificarlo. Una chiamata da un numero sconosciuto e’ un lead con source: "phone". Una chiave limitata a delle sedi deve indicare facilityId.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio
`firstName`	string	sì
`lastName`	string	no
`email`	string (email)	no
`phone`	string	no
`source`	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	no
`sourceDetail`	string	no
`status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	no
`notes`	string	no
`assignedTo`	string (uuid)	no
`estimatedValue`	number	no
`nextFollowUpAt`	string (date-time)	no
`facilityId`	string (uuid)	no

Risposte

Status	Descrizione
`201`	Il lead creato (201) o quello gia’ esistente (200).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`firstName`	string	sì
`lastName`	string \| null	sì
`email`	string \| null	sì
`phone`	string \| null	sì
`source`	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	sì
`sourceDetail`	string \| null	sì
`status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	sì
`assignedTo`	string (uuid) \| null	sì
`estimatedValue`	number \| null	sì
`notes`	string \| null	sì
`nextFollowUpAt`	string \| null	sì
`lastContactedAt`	string \| null	sì
`lostReason`	string \| null	sì
`convertedPatientId`	string (uuid) \| null	sì
`convertedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`activities`	array di object	no	Solo nel dettaglio.
`activities[].id`	string	sì
`activities[].kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`activities[].body`	string	sì
`activities[].at`	string	sì	Istante ISO 8601.
`deduplicated`	boolean	sì	true = c’era gia’: nessun lead creato, nessuna modifica.

Un lead

GET /leads/{id} Scope: leads:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Il lead, con le attivita’.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`firstName`	string	sì
`lastName`	string \| null	sì
`email`	string \| null	sì
`phone`	string \| null	sì
`source`	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	sì
`sourceDetail`	string \| null	sì
`status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	sì
`assignedTo`	string (uuid) \| null	sì
`estimatedValue`	number \| null	sì
`notes`	string \| null	sì
`nextFollowUpAt`	string \| null	sì
`lastContactedAt`	string \| null	sì
`lostReason`	string \| null	sì
`convertedPatientId`	string (uuid) \| null	sì
`convertedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`activities`	array di object	no	Solo nel dettaglio.
`activities[].id`	string	sì
`activities[].kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`activities[].body`	string	sì
`activities[].at`	string	sì	Istante ISO 8601.

Modifica un lead

PATCH /leads/{id} Scope: leads:write. Solo i campi mandati cambiano; null svuota un campo facoltativo. Un cambio di status riparte il conteggio dei giorni nello stadio. Per convertire in paziente usa POST /leads/\{id\}/convert. Con If-Match la modifica fallisce con 409 se il lead e’ cambiato nel frattempo.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio
`firstName`	string	no
`lastName`	string \| null	no
`email`	string (email) \| null	no
`phone`	string \| null	no
`sourceDetail`	string \| null	no
`status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	no
`notes`	string \| null	no
`assignedTo`	string (uuid) \| null	no
`estimatedValue`	number \| null	no
`nextFollowUpAt`	string (date-time) \| null	no
`lostReason`	string \| null	no

Risposte

Status	Descrizione
`200`	Il lead aggiornato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`facilityId`	string (uuid) \| null	sì
`firstName`	string	sì
`lastName`	string \| null	sì
`email`	string \| null	sì
`phone`	string \| null	sì
`source`	string: `social_media`, `website`, `referral_link`, `manual`, `import`, `phone`, `walk_in`, `other`, `whatsapp`	sì
`sourceDetail`	string \| null	sì
`status`	string: `new`, `contacted`, `qualified`, `proposal`, `won`, `lost`	sì
`assignedTo`	string (uuid) \| null	sì
`estimatedValue`	number \| null	sì
`notes`	string \| null	sì
`nextFollowUpAt`	string \| null	sì
`lastContactedAt`	string \| null	sì
`lostReason`	string \| null	sì
`convertedPatientId`	string (uuid) \| null	sì
`convertedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`activities`	array di object	no	Solo nel dettaglio.
`activities[].id`	string	sì
`activities[].kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`activities[].body`	string	sì
`activities[].at`	string	sì	Istante ISO 8601.

Aggiungi un’attivita’ a un lead

POST /leads/{id}/activities Scope: leads:write. Una nota o un contatto (chiamata, email, WhatsApp, incontro). I contatti aggiornano anche l’ultimo contatto del lead.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`body`	string	sì
`at`	string (date-time)	no	Quando e’ avvenuta; predefinito: adesso.

Risposte

Status	Descrizione
`201`	L’attivita’ aggiunta.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string	sì
`kind`	string: `call`, `email`, `whatsapp`, `meeting`, `note`	sì
`body`	string	sì
`at`	string	sì	Istante ISO 8601.

Converti un lead in paziente

POST /leads/{id}/convert Scope: leads:write e patients:write. Crea il paziente dai dati del lead e segna il lead come convertito. Serve il cognome: se il lead non ce l’ha, mandalo in lastName. Un lead gia’ convertito risponde 409. Chiede sia leads:write sia patients:write.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`lastName`	string	no

Risposte

Status	Descrizione
`201`	Il paziente creato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente
`leadId`	string (uuid)	sì
`patientId`	string (uuid)	sì
`convertedAt`	string	sì

Elenco delle conversazioni WhatsApp

GET /conversations Scope: messages:read. Ordinate per ultima modifica; updatedSince per la sincronizzazione incrementale.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`patientId`	query	string (uuid)	no
`leadId`	query	string (uuid)	no

Risposte

Status	Descrizione
`200`	Una pagina di conversazioni.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].patientId`	string (uuid) \| null	sì
`data[].leadId`	string (uuid) \| null	sì
`data[].phone`	string	sì
`data[].botState`	string: `attivo`, `in_pausa`, `allo_studio`	sì	attivo = risponde; in_pausa = zitto fino a `botPausedUntil`; allo_studio = spento da una persona.
`data[].botPausedUntil`	string \| null	sì
`data[].optedOut`	boolean	sì	true = il paziente ha scritto STOP: non gli si mandano messaggi automatici.
`data[].lastInboundAt`	string \| null	sì
`data[].lastOutboundAt`	string \| null	sì
`data[].lastActivityAt`	string	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

I messaggi di una conversazione

GET /conversations/{id}/messages Scope: messages:read. In ordine di arrivo. updatedSince filtra per istante di arrivo. La trascrizione dei vocali c’e’ solo con lo scope clinical:read (e patients:read) e solo se la conversazione e’ di un paziente. Il testo esce con messages:read, ma ogni lettura che lo contiene finisce nel registro accessi come accesso a dati clinici.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).

Risposte

Status	Descrizione
`200`	Una pagina di messaggi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].direction`	string: `in`, `out`	sì
`data[].author`	string: `paziente`, `bot`, `staff_app`, `staff_telefono`, `automazione`	sì
`data[].type`	string: `testo`, `audio`, `immagine`, `documento`, `video`, `altro`	sì
`data[].body`	string \| null	sì	null se il messaggio e’ stato cancellato dal paziente o non ha testo.
`data[].occurredAt`	string	sì
`data[].createdAt`	string	sì
`data[].mediaMimeType`	string \| null	sì
`data[].mediaDurationSeconds`	number \| null	sì
`data[].transcriptionStatus`	string: `assente`, `in_corso`, `completata`, `fallita`, `troppo_lunga`	sì
`data[].transcription`	string \| null	no	Trascrizione di un vocale: solo con lo scope clinical:read (e patients:read), e ogni lettura va nel registro accessi.
`nextCursor`	string \| null	sì	null = ultima pagina.

Manda un messaggio WhatsApp

POST /conversations/{id}/messages Scope: messages:write. Accoda un messaggio di testo al numero della conversazione (parte con il ritmo del numero della clinica, non subito). 409 se il paziente ha scritto STOP o se il bot e’ in pausa o spento su quel filo (una persona sta gestendo la conversazione). 409 anche se in coda ci sono gia’ 5 messaggi dell’API per quel numero (recipient_queue_full) o 200 per la clinica (queue_full). Passano dopo i promemoria e le automazioni della clinica; revocata la chiave, i suoi messaggi non ancora partiti si annullano. Chiede Idempotency-Key: un nuovo tentativo con la stessa chiave non manda due volte. Con una chiave di prova non parte nulla.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	sì	Obbligatoria. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`text`	string	sì

Risposte

Status	Descrizione
`202`	Il messaggio e’ stato accodato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`conversationId`	string (uuid)	sì
`status`	string: `queued`, `duplicate`, `not_sent_test_mode`	sì	queued = in coda; duplicate = una richiesta con questa Idempotency-Key era gia’ in coda; not_sent_test_mode = chiave di prova, nulla e’ partito.
`outboxId`	string (uuid) \| null	sì	L’id nella coda d’invio; null se non accodato adesso.

Stato del bot su una conversazione

PATCH /conversations/{id}/bot Scope: messages:write. \{ "state": "attivo" \} lo riaccende; \{ "state": "in_pausa", "pausedUntil": "<istante futuro>" \} lo mette in pausa fino a quell’istante (al massimo 7 giorni). Se una persona l’ha spento (allo_studio) si puo’ solo riaccendere, non mettere in pausa.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`state`	string	sì

Risposte

Status	Descrizione
`200`	La conversazione con il bot nel nuovo stato.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`patientId`	string (uuid) \| null	sì
`leadId`	string (uuid) \| null	sì
`phone`	string	sì
`botState`	string: `attivo`, `in_pausa`, `allo_studio`	sì	attivo = risponde; in_pausa = zitto fino a `botPausedUntil`; allo_studio = spento da una persona.
`botPausedUntil`	string \| null	sì
`optedOut`	boolean	sì	true = il paziente ha scritto STOP: non gli si mandano messaggi automatici.
`lastInboundAt`	string \| null	sì
`lastOutboundAt`	string \| null	sì
`lastActivityAt`	string	sì
`createdAt`	string	sì
`updatedAt`	string	sì

Registra una telefonata conclusa

POST /calls Scope: calls:write. Idempotente su externalCallId: 201 la prima volta, 200 con la riga gia’ registrata dopo. Un numero sconosciuto diventa un lead con source=phone.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`externalCallId`	string	sì	L’id della chiamata presso il fornitore: la chiave di idempotenza.
`direction`	string: `inbound`, `outbound`	sì
`from`	string	sì	Numero di telefono in qualunque formato; «anonymous» se nascosto.
`to`	string	sì	Numero di telefono in qualunque formato; «anonymous» se nascosto.
`startedAt`	string (date-time)	sì
`durationSeconds`	integer	sì
`outcome`	string: `booked`, `rescheduled`, `cancelled`, `information`, `callback`, `interested`, `not_interested`, `transferred`, `no_answer`, `voicemail`, `failed`, `other`	sì
`summary`	string	no
`recordingUrl`	string (uri)	no
`transcript`	string	no	Dato clinico: richiede lo scope clinical:write.
`patientId`	string (uuid)	no
`leadId`	string (uuid)	no
`facilityId`	string (uuid)	no
`caller`	object	no	Il nome detto al telefono: serve solo se il numero e’ sconosciuto e nasce un lead.
`caller.firstName`	string	no
`caller.lastName`	string	no

Risposte

Status	Descrizione
`201`	La telefonata registrata (200 se era gia’ registrata).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`externalCallId`	string	sì	L’id della chiamata presso il fornitore della voce.
`direction`	string: `inbound`, `outbound`	sì
`from`	string	sì
`to`	string	sì
`startedAt`	string	sì	Istante ISO 8601.
`durationSeconds`	integer	sì
`outcome`	string: `booked`, `rescheduled`, `cancelled`, `information`, `callback`, `interested`, `not_interested`, `transferred`, `no_answer`, `voicemail`, `failed`, `other`	sì
`summary`	string \| null	sì
`recordingUrl`	string \| null	sì	Link alla registrazione presso il fornitore.
`patientId`	string (uuid) \| null	sì
`leadId`	string (uuid) \| null	sì
`facilityId`	string (uuid) \| null	sì
`createdAt`	string	sì
`transcript`	string \| null	no	Solo nel dettaglio e solo con lo scope clinical:read (dato clinico, finisce nel registro accessi).

Elenca le telefonate

GET /calls Scope: calls:read. In ordine di registrazione. updatedSince guarda l’istante di registrazione (una telefonata non cambia).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`patientId`	query	string (uuid)	no
`leadId`	query	string (uuid)	no
`outcome`	query	string: `booked`, `rescheduled`, `cancelled`, `information`, `callback`, `interested`, `not_interested`, `transferred`, `no_answer`, `voicemail`, `failed`, `other`	no
`from`	query	string (date-time)	no	Solo le chiamate iniziate da questo istante.
`to`	query	string (date-time)	no	Solo le chiamate iniziate prima di questo istante.

Risposte

Status	Descrizione
`200`	Una pagina di telefonate, senza trascrizione.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].externalCallId`	string	sì	L’id della chiamata presso il fornitore della voce.
`data[].direction`	string: `inbound`, `outbound`	sì
`data[].from`	string	sì
`data[].to`	string	sì
`data[].startedAt`	string	sì	Istante ISO 8601.
`data[].durationSeconds`	integer	sì
`data[].outcome`	string: `booked`, `rescheduled`, `cancelled`, `information`, `callback`, `interested`, `not_interested`, `transferred`, `no_answer`, `voicemail`, `failed`, `other`	sì
`data[].summary`	string \| null	sì
`data[].recordingUrl`	string \| null	sì	Link alla registrazione presso il fornitore.
`data[].patientId`	string (uuid) \| null	sì
`data[].leadId`	string (uuid) \| null	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].createdAt`	string	sì
`data[].transcript`	string \| null	no	Solo nel dettaglio e solo con lo scope clinical:read (dato clinico, finisce nel registro accessi).
`nextCursor`	string \| null	sì	null = ultima pagina.

Una telefonata

GET /calls/{id} Scope: calls:read. Con lo scope clinical:read anche la trascrizione (l’accesso finisce nel registro).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La telefonata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`externalCallId`	string	sì	L’id della chiamata presso il fornitore della voce.
`direction`	string: `inbound`, `outbound`	sì
`from`	string	sì
`to`	string	sì
`startedAt`	string	sì	Istante ISO 8601.
`durationSeconds`	integer	sì
`outcome`	string: `booked`, `rescheduled`, `cancelled`, `information`, `callback`, `interested`, `not_interested`, `transferred`, `no_answer`, `voicemail`, `failed`, `other`	sì
`summary`	string \| null	sì
`recordingUrl`	string \| null	sì	Link alla registrazione presso il fornitore.
`patientId`	string (uuid) \| null	sì
`leadId`	string (uuid) \| null	sì
`facilityId`	string (uuid) \| null	sì
`createdAt`	string	sì
`transcript`	string \| null	no	Solo nel dettaglio e solo con lo scope clinical:read (dato clinico, finisce nel registro accessi).

Briefing prima della chiamata

POST /voice/context Scope: patients:read e appointments:read. Chi e’ il numero e cosa ha in sospeso, senza dati clinici. 403 reason ai_disabled se la clinica ha spento l’AI.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`phone`	string	sì	Numero di telefono in qualunque formato; «anonymous» se nascosto.

Risposte

Status	Descrizione
`200`	Il briefing.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`phone`	string \| null	sì	Il numero normalizzato (E.164); null se non e’ un numero.
`match`	string: `patient`, `multiple`, `lead`, `none`	sì	multiple = piu’ pazienti sullo stesso numero (famiglia): chiedere per chi chiama.
`patient`	object \| null	sì
`patient.id`	string (uuid)	sì
`patient.firstName`	string	sì
`patient.lastName`	string \| null	sì
`candidates`	array di object	sì
`candidates[].id`	string (uuid)	sì
`candidates[].firstName`	string	sì
`lead`	object \| null	sì
`lead.id`	string (uuid)	sì
`lead.firstName`	string	sì
`lead.lastName`	string \| null	sì
`lead.status`	string	sì
`nextAppointment`	object \| null	sì
`nextAppointment.id`	string (uuid)	sì
`nextAppointment.startTime`	string	sì
`nextAppointment.endTime`	string	sì
`nextAppointment.status`	string	sì
`nextAppointment.category`	string \| null	sì
`nextAppointment.doctorId`	string (uuid) \| null	sì
`nextAppointment.facilityId`	string (uuid) \| null	sì
`lastAppointment`	object \| null	sì
`lastAppointment.id`	string (uuid)	sì
`lastAppointment.startTime`	string	sì
`lastAppointment.endTime`	string	sì
`lastAppointment.status`	string	sì
`lastAppointment.category`	string \| null	sì
`lastAppointment.doctorId`	string (uuid) \| null	sì
`lastAppointment.facilityId`	string (uuid) \| null	sì
`openTreatmentPlan`	object \| null	no	Solo con lo scope treatment_plans:read.
`openTreatmentPlan.id`	string (uuid)	sì
`openTreatmentPlan.status`	string	sì
`openTreatmentPlan.totalCost`	number \| null	sì
`openTreatmentPlan.presentedAt`	string \| null	sì
`openTasks`	array di object	no	Solo con lo scope tasks:read. Senza titolo: e’ testo libero, anche dettato da chi chiama.
`openTasks[].id`	string (uuid)	sì
`openTasks[].type`	string \| null	sì	Il tipo (voice_handoff = un richiamo chiesto al telefono, recall, manual…).
`openTasks[].dueDate`	string \| null	sì

Passa la chiamata alla segreteria

POST /voice/handoff Scope: tasks:write. Crea un’attivita’ di richiamo. Un numero sconosciuto diventa un lead con source=phone. 403 reason ai_disabled se la clinica ha spento l’AI.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`phone`	string	sì	Il numero da richiamare.
`reason`	string	sì	Cosa vuole chi ha chiamato, in una riga.
`callbackBy`	string (date-time)	no	Entro quando richiamare.
`patientId`	string (uuid)	no
`leadId`	string (uuid)	no
`facilityId`	string (uuid)	no
`caller`	object	no
`caller.firstName`	string	no
`caller.lastName`	string	no

Risposte

Status	Descrizione
`201`	L’attivita’ creata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente
`taskId`	string (uuid)	sì
`title`	string	sì
`dueDate`	string \| null	sì
`patientId`	string (uuid) \| null	sì
`leadId`	string (uuid) \| null	sì

Elenca gli eventi

GET /events Scope: webhooks:read. Gli eventi degli ultimi 30 giorni, nella stessa busta dei webhook. updatedSince filtra sull’istante in cui l’evento e’ diventato visibile. Si vedono solo i tipi coperti dagli scope della chiave. Gli eventi che non sono nati lasciano un events.skipped con data.reason (bulk_import: piu’ di 50 *.created insieme; no_active_key: un periodo senza chiavi attive, da data.from a data.to; error: il trigger e’ fallito), data.type, data.scope e data.count: da li’ si risincronizza con updatedSince sugli elenchi.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`type`	query	string	no	Un tipo di evento del catalogo.

Risposte

Status	Descrizione
`200`	Una pagina di eventi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì	Su /v1/events: l’evento. Nel corpo di un webhook: la consegna.
`data[].eventId`	string (uuid)	sì	L’evento: usalo per riconoscere i doppioni.
`data[].type`	string	sì
`data[].createdAt`	string	sì
`data[].apiVersion`	string	sì
`data[].livemode`	boolean	sì
`data[].facilityId`	string (uuid) \| null	sì
`data[].data`	object	sì	La risorsa nella forma pubblica. Mai dati sanitari; le risorse collegate sono solo id.
`nextCursor`	string \| null	sì	null = ultima pagina.

Elenca le destinazioni dei webhook

GET /webhook-endpoints Scope: webhooks:read. Le destinazioni create da questa chiave (o da quella che ha rigenerato).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).

Risposte

Status	Descrizione
`200`	Una pagina di destinazioni.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì
`data[].url`	string	sì
`data[].description`	string \| null	sì
`data[].events`	array di string	sì
`data[].enabled`	boolean	sì
`data[].disabledReason`	string: `manual`, `too_many_failures` \| null	sì	too_many_failures: spenta dopo 50 consegne scartate di fila. Riaccendila con PATCH enabled=true.
`data[].consecutiveFailures`	integer	sì
`data[].previousSecretExpiresAt`	string \| null	sì	Fino a quest’istante si firma anche con il segreto precedente.
`data[].secretRotatedAt`	string \| null	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Crea una destinazione dei webhook

POST /webhook-endpoints Scope: webhooks:write. Al massimo 20 per clinica. Il segreto si vede solo nella risposta. Gli eventi sono filtrati con gli scope e le sedi di QUESTA chiave. Ogni webhook e’ un POST JSON firmato: calcola HMAC-SHA256(segreto, “v1\n” + X-DentalSpace-Timestamp + “\n” + X-DentalSpace-Idempotency-Key + “\n” + corpo) e confrontalo con uno dei valori v1= di X-DentalSpace-Signature; rifiuta i timestamp piu’ vecchi di 5 minuti e scarta le Idempotency-Key gia’ viste. Rispondi 2xx entro 10 secondi; altrimenti si ritenta dopo 1, 5, 15 minuti e 1 ora. I redirect non si seguono.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`url`	string	sì	https, con un nome pubblico: indirizzi privati, locali o con credenziali si rifiutano.
`events`	array di string	sì
`description`	string	no

Risposte

Status	Descrizione
`201`	La destinazione, con il segreto.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`url`	string	sì
`description`	string \| null	sì
`events`	array di string	sì
`enabled`	boolean	sì
`disabledReason`	string: `manual`, `too_many_failures` \| null	sì	too_many_failures: spenta dopo 50 consegne scartate di fila. Riaccendila con PATCH enabled=true.
`consecutiveFailures`	integer	sì
`previousSecretExpiresAt`	string \| null	sì	Fino a quest’istante si firma anche con il segreto precedente.
`secretRotatedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`secret`	string	sì	whsec_…: si vede SOLO in questa risposta. Conservalo.

Una destinazione

GET /webhook-endpoints/{id} Scope: webhooks:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La destinazione (senza segreto).
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`url`	string	sì
`description`	string \| null	sì
`events`	array di string	sì
`enabled`	boolean	sì
`disabledReason`	string: `manual`, `too_many_failures` \| null	sì	too_many_failures: spenta dopo 50 consegne scartate di fila. Riaccendila con PATCH enabled=true.
`consecutiveFailures`	integer	sì
`previousSecretExpiresAt`	string \| null	sì	Fino a quest’istante si firma anche con il segreto precedente.
`secretRotatedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì

Modifica una destinazione

PATCH /webhook-endpoints/{id} Scope: webhooks:write. URL, eventi, descrizione, accesa/spenta. Con If-Match (l’ETag della GET) non sovrascrive modifiche altrui.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`url`	string	no	https, con un nome pubblico: indirizzi privati, locali o con credenziali si rifiutano.
`events`	array di string	no
`description`	string \| null	no
`enabled`	boolean	no

Risposte

Status	Descrizione
`200`	La destinazione aggiornata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`url`	string	sì
`description`	string \| null	sì
`events`	array di string	sì
`enabled`	boolean	sì
`disabledReason`	string: `manual`, `too_many_failures` \| null	sì	too_many_failures: spenta dopo 50 consegne scartate di fila. Riaccendila con PATCH enabled=true.
`consecutiveFailures`	integer	sì
`previousSecretExpiresAt`	string \| null	sì	Fino a quest’istante si firma anche con il segreto precedente.
`secretRotatedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì

Elimina una destinazione

DELETE /webhook-endpoints/{id} Scope: webhooks:write. Non riceve piu’ niente e i suoi segreti si cancellano. Le consegne gia’ fatte restano leggibili 30 giorni.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`If-Match`	header	string	no	L’ETag ricevuto: la modifica passa solo se nessuno ha cambiato la risorsa (altrimenti 409 conflict, details.reason = version_mismatch).

Risposte

Status	Descrizione
`200`	Eliminata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`deleted`	boolean	sì

Ruota il segreto di una destinazione

POST /webhook-endpoints/{id}/rotate-secret Scope: webhooks:write.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Corpo (JSON)

Campo	Tipo	Obbligatorio	Descrizione
`overlapMinutes`	integer	no	Per quanti minuti si firma anche con il segreto vecchio (0-10080, predefinito 1440 = un giorno).

Risposte

Status	Descrizione
`200`	La destinazione, con il segreto nuovo.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì
`url`	string	sì
`description`	string \| null	sì
`events`	array di string	sì
`enabled`	boolean	sì
`disabledReason`	string: `manual`, `too_many_failures` \| null	sì	too_many_failures: spenta dopo 50 consegne scartate di fila. Riaccendila con PATCH enabled=true.
`consecutiveFailures`	integer	sì
`previousSecretExpiresAt`	string \| null	sì	Fino a quest’istante si firma anche con il segreto precedente.
`secretRotatedAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`secret`	string	sì	whsec_…: si vede SOLO in questa risposta. Conservalo.

Manda un webhook di prova

POST /webhook-endpoints/{id}/test Scope: webhooks:write. Un evento webhook.test con data {}, firmato come gli altri. Funziona anche su una destinazione spenta.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	Com’e’ andata.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`delivered`	boolean	sì	true se la destinazione ha risposto 2xx entro 10 secondi.
`statusCode`	integer \| null	sì
`durationMs`	integer	sì
`error`	string \| null	sì
`skipped`	string \| null	sì	test_mode: chiave di prova, non e’ partito niente.

Elenca le consegne dei webhook

GET /webhook-deliveries Scope: webhooks:read. Le consegne degli ultimi 30 giorni alle destinazioni di questa chiave.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`limit`	query	integer	no	Quante righe per pagina (1-200).
`cursor`	query	string	no	Il nextCursor della pagina precedente, tale e quale.
`updatedSince`	query	string (date-time)	no	Solo le righe modificate da questo istante in poi (sincronizzazione incrementale).
`endpointId`	query	string (uuid)	no
`status`	query	string: `pending`, `delivering`, `succeeded`, `discarded`	no

Risposte

Status	Descrizione
`200`	Una pagina di consegne.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`data`	array di object	sì
`data[].id`	string (uuid)	sì	La consegna. E’ anche la X-DentalSpace-Idempotency-Key di ogni suo tentativo.
`data[].endpointId`	string (uuid)	sì
`data[].eventId`	string (uuid)	sì
`data[].status`	string: `pending`, `delivering`, `succeeded`, `discarded`	sì	discarded = scartata dopo 5 tentativi: si rimanda con /redeliver.
`data[].attempts`	integer	sì
`data[].nextAttemptAt`	string \| null	sì
`data[].lastStatusCode`	integer \| null	sì
`data[].lastError`	string \| null	sì
`data[].deliveredAt`	string \| null	sì
`data[].createdAt`	string	sì
`data[].updatedAt`	string	sì
`nextCursor`	string \| null	sì	null = ultima pagina.

Una consegna, con i suoi tentativi

GET /webhook-deliveries/{id} Scope: webhooks:read.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.

Risposte

Status	Descrizione
`200`	La consegna e il registro dei tentativi.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì	La consegna. E’ anche la X-DentalSpace-Idempotency-Key di ogni suo tentativo.
`endpointId`	string (uuid)	sì
`eventId`	string (uuid)	sì
`status`	string: `pending`, `delivering`, `succeeded`, `discarded`	sì	discarded = scartata dopo 5 tentativi: si rimanda con /redeliver.
`attempts`	integer	sì
`nextAttemptAt`	string \| null	sì
`lastStatusCode`	integer \| null	sì
`lastError`	string \| null	sì
`deliveredAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì
`history`	array di object	sì
`history[].attempt`	integer	sì
`history[].statusCode`	integer \| null	sì
`history[].error`	string \| null	sì
`history[].responseExcerpt`	string \| null	sì	Sempre null: il corpo della risposta della destinazione non si legge ne’ si conserva (esito cieco).
`history[].durationMs`	integer \| null	sì
`history[].createdAt`	string	sì

Rimanda una consegna

POST /webhook-deliveries/{id}/redeliver Scope: webhooks:write. Solo una consegna succeeded o discarded, verso una destinazione accesa. Parte entro una decina di secondi. Al massimo 3 volte per consegna: oltre, 409 con reason redeliver_limit.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	path	string (uuid)	sì	Identificativo della risorsa.
`Idempotency-Key`	header	string	no	Facoltativa. La stessa chiave entro 24 ore ripete la prima risposta 2xx.

Risposte

Status	Descrizione
`200`	La consegna, di nuovo in coda.
`400`	Codici: `invalid_request`.
`401`	Codici: `unauthenticated`, `api_key_invalid`, `api_key_revoked`.
`403`	Codici: `plan_required`, `insufficient_scope`.
`404`	Codici: `not_found`.
`409`	Codici: `conflict`, `idempotency_in_progress`.
`422`	Codici: `idempotency_key_reused`.
`429`	Codici: `rate_limited`.
`500`	Codici: `internal_error`.
`503`	Codici: `unavailable`.

Campi della risposta

Campo	Tipo	Sempre presente	Descrizione
`id`	string (uuid)	sì	La consegna. E’ anche la X-DentalSpace-Idempotency-Key di ogni suo tentativo.
`endpointId`	string (uuid)	sì
`eventId`	string (uuid)	sì
`status`	string: `pending`, `delivering`, `succeeded`, `discarded`	sì	discarded = scartata dopo 5 tentativi: si rimanda con /redeliver.
`attempts`	integer	sì
`nextAttemptAt`	string \| null	sì
`lastStatusCode`	integer \| null	sì
`lastError`	string \| null	sì
`deliveredAt`	string \| null	sì
`createdAt`	string	sì
`updatedAt`	string	sì

Oggetto errore

Tutte le risposte di errore hanno questo formato.

Campo	Tipo	Obbligatorio	Descrizione
`error`	object	sì
`error.code`	string	sì	Codice stabile, da usare nel codice del client.
`error.message`	string	sì	Spiegazione per una persona (in italiano). Non confrontarla nel codice.
`error.details`	object \| null	sì
`error.requestId`	string	sì	Lo stesso valore dell’header X-Request-Id: citalo all’assistenza.

​La chiave che sta chiamando

​Risposte

​Campi della risposta

​Stato del servizio

​Risposte

​Campi della risposta

​Specifica OpenAPI 3.1

​Risposte

​Le sedi della clinica

​Parametri

​Risposte

​Campi della risposta

​Una sede

​Parametri

​Risposte

​Campi della risposta

​Le poltrone attive di una sede

​Parametri

​Risposte

​Campi della risposta

​I medici della clinica

​Parametri

​Risposte

​Campi della risposta

​I calendari prenotabili

​Parametri

​Risposte

​Campi della risposta

​Un calendario

​Parametri

​Risposte

​Campi della risposta

​Il listino

​Parametri

​Risposte

​Campi della risposta

​Una prestazione

​Parametri

​Risposte

​Campi della risposta

​Chi e’ questo numero?

​Parametri

​Risposte

​Campi della risposta

​Cerca un paziente

​Parametri

​Risposte

​Campi della risposta

​Elenco dei pazienti

​Parametri

​Risposte

​Campi della risposta

​Crea un paziente

​Parametri

​Corpo (JSON)

​Risposte

​Campi della risposta

​La scheda di un paziente

​Parametri

​Risposte

​Campi della risposta

​Modifica un paziente

​Parametri

​Corpo (JSON)

​Risposte

​Campi della risposta

​Archivia un paziente

​Parametri

​Risposte

​Campi della risposta

​Riattiva un paziente archiviato

​Parametri

​Risposte

​Campi della risposta

​Gli appuntamenti di un paziente

​Parametri

​Risposte

​Campi della risposta

​I preventivi di un paziente

​Parametri

La chiave che sta chiamando

Risposte

Campi della risposta

Stato del servizio

Risposte

Campi della risposta

Specifica OpenAPI 3.1

Risposte

Le sedi della clinica

Parametri

Risposte

Campi della risposta

Una sede

Parametri

Risposte

Campi della risposta

Le poltrone attive di una sede

Parametri

Risposte

Campi della risposta

I medici della clinica

Parametri

Risposte

Campi della risposta

I calendari prenotabili

Parametri

Risposte

Campi della risposta

Un calendario

Parametri

Risposte

Campi della risposta

Il listino

Parametri

Risposte

Campi della risposta

Una prestazione

Parametri

Risposte

Campi della risposta

Chi e’ questo numero?

Parametri

Risposte

Campi della risposta

Cerca un paziente

Parametri

Risposte

Campi della risposta

Elenco dei pazienti

Parametri

Risposte

Campi della risposta

Crea un paziente

Parametri

Corpo (JSON)

Risposte

Campi della risposta

La scheda di un paziente

Parametri

Risposte

Campi della risposta

Modifica un paziente

Parametri

Corpo (JSON)

Risposte

Campi della risposta

Archivia un paziente

Parametri

Risposte

Campi della risposta

Riattiva un paziente archiviato

Parametri

Risposte

Campi della risposta

Gli appuntamenti di un paziente

Parametri

Risposte

Campi della risposta

I preventivi di un paziente

Parametri