API e integrazioni

Collega il tuo gestionale a ConsensoSicuro

Con le API il tuo software manda il consenso al paziente, segue la firma e archivia il PDF senza che nessuno debba copiare dati a mano. Le chiavi appartengono al tuo account e vedono al massimo quello che vedi tu in dashboard, nei limiti dei permessi che scegli.

• Studi e strutture con un gestionale — Se lavori già con un gestionale, un CRM o un’agenda, il consenso può partire da lì nel momento in cui prenoti la visita.
• Software house che sviluppano il gestionale di uno studio — Se sviluppi il gestionale di uno studio, il titolare ti consegna una chiave del suo account e tu integri invio, firma e archivio.

Registrati e provale

Sei già cliente? Apri Impostazioni → API & Integrazioni

Indice

• Come funziona
• Cosa puoi fare
• Sicurezza
• Modalità Test
• Per le strutture
• Costi
• Domande frequenti

Come funziona

In quattro passaggi arrivi dal primo accesso al primo consenso firmato dentro il tuo gestionale.

• 1. Crei la chiave in Impostazioni — In Impostazioni → API & Integrazioni scegli nome, modalità (Test o produzione) e permessi. La chiave ti viene mostrata una volta sola: copiala nel tuo gestionale.
• 2. Leggi il catalogo del tuo account — Con GET /templates il software scopre i codici dei trattamenti, i tuoi modelli, le lingue attive e, se sei una struttura, sedi ed esecutori. È la lettura che precede ogni invio.
• 3. Invii il consenso dal tuo software — Una chiamata a POST /consents fa partire il consenso con le stesse opzioni della dashboard: il paziente riceve il link su WhatsApp o per SMS e firma dal telefono con un codice OTP.
• 4. Ricevi il webhook quando è firmato — Quando il paziente firma mandiamo l’evento consent.completed al tuo server, firmato con HMAC-SHA256. Da lì scarichi i PDF firmati con un’altra chiamata.

Invio di un consenso (chiave di prova)

curl -X POST https://api.consensosicuro.it/api/v1/account/consents \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: visita-119" \
  -d '{
    "patient": { "firstName": "Mario", "lastName": "Rossi", "phone": "+393331234567" },
    "template": { "treatments": ["psi-colloquio"] },
    "delivery": { "channel": "WHATSAPP", "language": "it" },
    "metadata": { "cartella": "CRT-119" }
  }'

Risposta 201 (abbreviata)

{
  "id": "e78355d5-…",
  "status": "PENDING_SIGNATURE",
  "consentType": "FULL",
  "isTest": true,
  "source": { "channel": "api", "apiKeyName": "Gestionale", "test": true },
  "metadata": { "cartella": "CRT-119" },
  "signatures": [
    { "slot": "P1", "role": "PATIENT", "phoneHint": "***567",
      "link": "https://…/c/110d60db", "status": "PENDING" }
  ],
  "expectedSignatures": 1,
  "receivedSignatures": 0
}

Con una chiave di prova il consenso nasce davvero ma non parte nessun messaggio. L’intestazione X-Idempotency-Key protegge dai doppioni: se il tuo software ripete la chiamata, ricevi lo stesso consenso.

Tutti gli endpoint, con parametri, esempi ed errori, nel riferimento delle API

Cosa puoi fare

Le API coprono quello che fai ogni giorno in dashboard. Ogni chiave apre solo i permessi che le hai dato.

Invio con tutte le opzioni

Scegli trattamenti o un tuo modello, canale, lingua, invio programmato, firma in studio sul tablet, incarico professionale e apparecchiature, come dalla dashboard.

Doppia firma per i minori

Indichi i due genitori e ognuno riceve il suo link con il suo codice OTP. Se dichiarano dati diversi sul minore ricevi un evento e risolvi dal gestionale.

Ciclo di vita e PDF

Segui stato ed esiti di consegna, reinvii, rinnovi, annulli, correggi il numero di un firmatario e scarichi consenso, privacy, incarico e dossier con link temporanei.

Pazienti e GDPR

Cerchi e crei le anagrafiche, gestisci note, documenti e visite, esporti la scheda di un paziente e chiedi la cancellazione, che resta annullabile per 7 giorni.

Strutture, sedi e professionisti

Lavori sulla sede giusta con un’intestazione e scegli chi esegue il trattamento. Puoi anche leggere e gestire sedi, professionisti e inviti della struttura.

Modelli e registri

Leggi e modifichi i modelli di consenso, l’informativa, l’incarico e le lingue attive. Tieni aggiornati dal gestionale i registri di apparecchiature, lotti iniettabili, inchiostri, operatrici e motivi di consulto.

Consumi e statistiche

Controlli la quota del periodo, i messaggi WhatsApp e SMS e i consumi degli ultimi 12 mesi. Leggi anche le statistiche della dashboard, con i consensi per stato e per trattamento.

Webhook

Ricevi un evento quando un consenso viene inviato, firmato in parte o del tutto, rifiutato, annullato o scade, e quando un’anagrafica cambia. Vale anche per i consensi inviati dalla dashboard.

Sicurezza

Una chiave API apre l’archivio del tuo studio. Per questo ogni passaggio lascia una traccia e ogni permesso va dato in modo esplicito.

• Chiavi mostrate una volta — La chiave compare solo al momento della creazione. Noi conserviamo solo un codice ricavato dalla chiave con l’algoritmo SHA-256, da cui non si può risalire alla chiave. Per questo non possiamo mostrartela di nuovo.
• Permessi per chiave — Ogni chiave ha i suoi permessi. Quelli che cancellano dati o li portano fuori non sono mai preselezionati.
• IP consentiti e scadenza — Puoi limitare una chiave agli indirizzi IP del tuo server. Scade dopo 365 giorni, o dopo 90 se lo scegli; senza scadenza solo se lo decidi apposta. Per cancellare i dati di un paziente gli IP consentiti sono obbligatori.
• Conferme e avvisi — Per creare una chiave di produzione, cambiare l’indirizzo del webhook o rigenerarne il segreto ti chiediamo password e, se attiva, verifica in due passaggi. A ogni modifica ti scriviamo, e ti avvisiamo se una chiave viene usata da un indirizzo nuovo o fa molte più richieste del solito.
• Webhook firmati — Accettiamo solo indirizzi https pubblici. Ogni messaggio porta l’istante dell’invio e la firma HMAC-SHA256 di istante e contenuto, calcolata con un segreto che ti mostriamo una sola volta e che conserviamo cifrato. Per poterlo rimandare, conserviamo il messaggio cifrato con AES-256-GCM per 30 giorni.
• Registro delle richieste — Registriamo ogni chiamata fatta con le tue chiavi, comprese quelle rifiutate per un indirizzo IP non consentito, con metodo, percorso, esito, chiave, IP e durata. Le righe restano consultabili in dashboard per 30 giorni e ogni notte cancelliamo quelle più vecchie.
• Ogni azione in audit — Le azioni che contano finiscono nel Registro attività dell’account con l’indicazione «via API» e il prefisso della chiave che le ha fatte.
• Modalità Test separata — Una chiave di prova lavora solo su consensi e anagrafiche di prova, in un archivio parallelo. Non può leggere né modificare i dati veri.

Come proteggiamo i dati, capitolo per capitolo

Modalità Test

Prima di collegare i pazienti veri puoi provare tutto il flusso con una chiave che inizia con ak_test_.

• Il consenso nasce davvero e lo vedi in dashboard con il marchio «Test API», ma non parte nessun messaggio al paziente.
• Per firmare usi sempre il codice 000000, così provi il flusso fino al PDF firmato.
• I consensi di prova non consumano la quota del piano e li cancelliamo dopo 7 giorni.
• Puoi fare fino a 50 invii di prova al giorno, con al massimo 20 anagrafiche nuove.

Per le strutture

Cliniche, poliambulatori e studi associati usano una chiave della struttura, creata dal titolare.

• La sede in un’intestazione — Con X-Structure-Sede-Id indichi la sede, come fa la dashboard. La chiave lavora solo sulle sedi della sua struttura e rifiuta quelle di altri.
• Chi esegue il trattamento — Nell’invio scegli il professionista che esegue, il titolare oppure l’esecutore generico, se l’hai attivato per quell’ambito.
• La segreteria — La segreteria non ha bisogno di chiavi proprie: il gestionale del front desk usa la chiave della struttura e il registro distingue le azioni fatte via API.

Costi

Le API sono comprese nell’abbonamento e non hanno un canone a parte. Ogni consenso inviato via API conta nella quota del tuo piano esattamente come uno inviato dalla dashboard, con le stesse regole per i consensi oltre la quota.

• Le chiamate di lettura, i download dei PDF e i webhook non si pagano.
• I consensi inviati con una chiave di prova non consumano la quota.
• Se l’abbonamento non è in regola, gli invii via API si fermano alle stesse condizioni della dashboard.

Domande frequenti

Le domande che ci fanno più spesso i titolari e chi sviluppa il loro gestionale.

Chi può creare le chiavi?

Può crearle solo il titolare dell’account, cioè il professionista che lavora da solo oppure il titolare della struttura. I professionisti che collaborano con una struttura e la segreteria non possono crearle. Prima della prima chiave il titolare accetta in dashboard le condizioni per l’integrazione.

Cosa succede se revoco una chiave?

Da quel momento ogni richiesta fatta con quella chiave riceve un errore 401 e il software che la usa smette di funzionare finché non gli dai una chiave nuova. I consensi già inviati, i documenti e il registro attività restano come sono. La revoca è definitiva.

Come funziona la doppia firma per i minori via API?

Nell’invio indichi che il paziente è minore e aggiungi i due genitori con i loro numeri. Ognuno riceve un link separato e firma con il proprio codice OTP. Ti mandiamo un evento quando firma il primo e uno quando il consenso è completo. Se i genitori dichiarano dati diversi sul minore ricevi consent.action_required e puoi risolvere dal gestionale.

Dove vanno i dati dei webhook?

I dati arrivano solo all’indirizzo https che hai indicato tu. Ogni messaggio porta i dati del consenso che servono al gestionale ed è firmato con un segreto che ti mostriamo una sola volta e che noi conserviamo cifrato. Se il tuo server non risponde, riproviamo dopo 30 secondi, 2 minuti, 10 minuti, 30 minuti, 2 ore, 6 ore e 24 ore. Il messaggio resta cifrato nei nostri sistemi per 30 giorni, poi lo cancelliamo.

Posso usare l’API con più sedi?

Sì. Una struttura usa una sola chiave per tutte le sue sedi e indica la sede con l’intestazione X-Structure-Sede-Id o nel corpo dell’invio. La chiave non può uscire dalle sedi della struttura.

Cosa vede una chiave di prova?

Una chiave di prova vede solo i consensi e le anagrafiche di prova, che stanno in un archivio separato. Non legge né modifica i dati dei tuoi pazienti veri e non manda messaggi. I dati di prova vengono cancellati dopo 7 giorni.

Come si cancella un paziente via API?

Chiami POST /patients/{id}/gdpr-delete con una chiave che ha il permesso di cancellare. Quel permesso si può dare solo a una chiave con gli IP consentiti. L’anagrafica sparisce subito da elenchi e invii, ma i dati vengono distrutti dopo 7 giorni: fino ad allora puoi annullare la richiesta. Ricevi un evento quando la cancellazione è programmata e uno quando è eseguita.

Quali limiti di richieste ci sono?

Ogni chiave può fare 300 richieste al minuto e da uno stesso indirizzo IP ne accettiamo 600. Gli invii di consensi hanno un tetto giornaliero per account, pari a una volta e mezza la quota mensile del piano e mai sotto i 30. Oltre un limite ricevi un errore 429 con il codice che spiega quale.

Devo firmare un nuovo DPA per usare le API?

No. Il trattamento resta regolato dall’atto di nomina a responsabile che hai accettato con l’abbonamento. Prima della prima chiave ti chiediamo di accettare in dashboard anche le condizioni per l’integrazione via API, e registriamo data, ora, versione e indirizzo IP dell’accettazione. Puoi leggerle prima di registrarti nella pagina pubblica delle condizioni.

Come mi accorgo se qualcosa non funziona?

In Impostazioni → API & Integrazioni trovi il monitoraggio con richieste, errori e consegne del webhook degli ultimi 7 o 30 giorni. Se il webhook non riesce a consegnare per 10 volte di fila o per 24 ore, ti scriviamo per email, al massimo una volta al giorno. Ti scriviamo anche quando una chiave viene usata da un indirizzo IP nuovo, fa molte più richieste del solito o riceve molti rifiuti in pochi minuti.

Prova le API con il tuo account

Registrati, crea una chiave di prova e manda il primo consenso dal terminale. In dashboard vedi subito la richiesta, il consenso di prova e l’evento del webhook.

Registrati

Apri Impostazioni → API & Integrazioni

Il riferimento completo degli endpoint è pubblico, con le guide, gli esempi da copiare, i codici di errore e la specifica OpenAPI. Lo ritrovi anche in dashboard, nella sezione API & Integrazioni.

Apri il riferimento delle API

Se vuoi una valutazione tecnica, o se chi sviluppa il tuo gestionale ha delle domande, scrivici a [email protected].

Approfondisci

Riferimento delle API: guide, tutti gli endpoint e gli esempi da copiare

Condizioni per l’integrazione via API, da leggere prima di collegare il gestionale

Sicurezza: dove stanno i dati e come sono protetti

Cliniche e poliambulatori: sedi, ruoli e visibilità dei dati

Atto di nomina a responsabile del trattamento

Condizioni generali del servizio