Skip to main content
Ogni richiesta porta una chiave API nell’header Authorization, con schema Bearer. Fanno eccezione GET /health e GET /openapi.json, che non chiedono la chiave.
GET /me restituisce la clinica, gli scope, le sedi, la scadenza e i limiti della chiave che chiama.

​
Formato della chiave

Dopo il prefisso seguono 64 caratteri esadecimali. La chiave è segreta: usala solo da un server, mai nel codice di una pagina web o di un’app.

​
Una chiave vede una clinica

La chiave appartiene alla clinica in cui è stata creata e vede solo i suoi dati. Una risorsa di un’altra clinica risponde 404 not_found, mai 403: dall’esterno non si capisce nemmeno se esiste. Una chiave può essere limitata ad alcune sedi. In quel caso vede le righe di quelle sedi e quelle senza sede, e scrive solo nelle sue sedi. Una risorsa di un’altra sede risponde 404 not_found.

​
Scope

Ogni endpoint chiede uno o più scope, indicati nella sua pagina come Scope: <nome>. Una chiave senza lo scope richiesto riceve 403 insufficient_scope prima che la richiesta legga qualunque dato; gli scope mancanti sono in details.requiredScopes. Nell’app gli scope si scelgono per area, con tre livelli: Nessuno, Leggi, Scrivi. Scrivi comprende Leggi. Una chiave non può fare più di chi la crea: nell’app si possono dare solo i permessi che si hanno.

​
Modelli pronti

Nella finestra di creazione, Parti da: riempie i livelli con un modello.

​
Creare una chiave

1

Apri Chiavi API

Nell’app apri Impostazioni → Chiavi API. Serve il permesso di gestire le integrazioni e il piano Clinic.
2

Clicca Crea chiave

Si apre la finestra Nuova chiave API. Dai un nome che dica quale programma la userà, per esempio Agente vocale.
3

Scegli cosa può fare

In Cosa può fare scegli il livello di ogni area, oppure parti da un modello. Accendi Solo alcune sedi per limitarla. Scadenza è facoltativa: vuota, la chiave non scade.
4

Copia la chiave

Clicca Crea chiave. La chiave compare una volta sola: copiala subito e conservala in un posto sicuro.
dentalspace conserva solo l’impronta della chiave, non la chiave. Una chiave persa non si recupera: creane un’altra e revoca quella vecchia.

​
Rigenerare una chiave

Rigenera dà una chiave nuova con gli stessi permessi. Scegli quando la vecchia smette di funzionare: Subito, Fra 24 ore o Fra 7 giorni. Nel frattempo funzionano tutte e due, così aggiorni il programma collegato senza interruzioni. Una chiave già rigenerata non si rigenera di nuovo: si rigenera quella nuova.

​
Revocare una chiave

Revoca spegne la chiave subito e per sempre. Le richieste successive ricevono 401 api_key_revoked. Una chiave scaduta risponde 401 api_key_revoked con details.reason: "expired".

​
Chiavi di prova

Una clinica di prova ha chiavi dsk_test_. Le richieste funzionano come con una chiave vera, con queste differenze:
  • GET /me restituisce livemode: false;
  • nessun messaggio parte verso l’esterno: WhatsApp, email, Sistema TS e fatturazione elettronica non vengono chiamati;
  • POST /payment-links controlla tutto ma non crea il link: risponde 201 con url: null;
  • POST /webhook-endpoints/{id}/test non spedisce niente.
La clinica di prova la attiva l’assistenza di dentalspace.

​
Errori di autenticazione e di permesso