API e webhook di Sanovia

Collega Sanovia ai programmi che usi già. Con una chiave API un programma legge i dati che scegli tu; con un webhook riceve un avviso firmato quando succede qualcosa nel tuo studio.

Specifica OpenAPI (JSON) · Verifica della firma

A cosa serve

Come ottieni una chiave

  1. Accedi a Sanovia e apri Impostazioni → Integrazioni → API e webhook.
  2. Premi «Nuova chiave»: dai un nome, scegli cosa può leggere e, se vuoi, una scadenza. Per sicurezza ti chiediamo di confermare che sei tu.
  3. Copia la chiave subito: te la mostriamo una volta sola. Sanovia ne conserva solo un’impronta, mai la chiave intera.
  4. Una chiave per ogni programma: quando uno non ti serve più, revochi la sua e gli altri continuano a funzionare.

Le chiavi API e i webhook sono inclusi nei piani Studio e Struttura.

Le chiavi sono del professionista o della struttura: in una struttura le crea l’amministratore. Segreteria e commercialista non possono crearle.

Se la scheda ti dice che le API non sono attive sul tuo account, per ora non puoi creare chiavi.

Autenticazione

Ogni richiesta porta la chiave nell’intestazione Authorization. Una chiave mancante, sbagliata, revocata o scaduta riceve sempre la stessa risposta 401; una chiave senza l’ambito giusto riceve 403.

Authorization: Bearer snv_…

Gli elenchi rispondono con data e next_cursor: ripassa next_cursor come parametro cursor finché vale null. Gli importi sono in centesimi di euro.

Limiti: 120 richieste al minuto per chiave (tutte le rotte insieme) e 300 al minuto per indirizzo IP su ogni rotta. Oltre, la risposta è 429: riprova dopo un minuto.

Ambiti di una chiave

Una chiave legge solo gli ambiti che le dai quando la crei. Questo elenco arriva dalla specifica OpenAPI, la stessa da cui Sanovia registra le sue rotte.

Rotte

Parametri, risposte e schemi completi: specifica OpenAPI 3.1 (JSON)

Webhook

Registri un indirizzo https pubblico sulla porta 443: Sanovia lo controlla quando lo salvi e prima di ogni invio, e non segue mai i reindirizzamenti. A ogni evento arriva una richiesta POST con un corpo JSON fatto solo di identificativi, numeri, date e importi: mai dati dei pazienti.

Rispondi con un codice 2xx entro 10 secondi. Qualsiasi altra risposta, anche un 3xx, conta come errore: riproviamo più volte, con attese sempre più lunghe.

Verifica la firma

Ogni invio porta l’intestazione Sanovia-Signature nella forma t=<secondi unix>,v1=<firma>. La firma è l’HMAC-SHA256, in esadecimale, calcolato con il tuo segreto di firma (whsec_…) sulla stringa fatta da t, un punto e il corpo grezzo della richiesta.

Verifica sui byte grezzi del corpo, prima di leggere il JSON; confronta in tempo costante; scarta un t più vecchio di qualche minuto, così nessuno può rispedirti un invio vecchio.

Verifica in Node.js, da copiare:

// Node.js 18+, nessuna dipendenza
import { createHmac, timingSafeEqual } from "node:crypto";

const MAX_SKEW_S = 300; // finestra anti-replay: 5 minuti

/** true quando `header` (Sanovia-Signature) firma `rawBody` con `secret`. */
export function verifySignature(rawBody, header, secret, nowS = Math.floor(Date.now() / 1000)) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header || ""));
  if (!m) return false;
  const t = Number(m[1]);
  if (Math.abs(nowS - t) > MAX_SKEW_S) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`, "utf8").digest();
  const given = Buffer.from(m[2], "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

// Nel tuo server: leggi il corpo GREZZO (stringa), poi
// verifySignature(raw, req.headers["sanovia-signature"], process.env.SANOVIA_WEBHOOK_SECRET)
// false → rispondi 401; true → rispondi 2xx subito e lavora dopo.

Ricette per Zapier, Make e n8n

Passaggi, non schermate. I nomi dei moduli sono quelli che questi strumenti usano oggi e possono cambiare: se non li trovi, cerca il modulo equivalente.

Ogni fattura emessa diventa una riga del foglio di calcolo

  1. Nello strumento crea un trigger che riceve webhook: «Webhooks by Zapier → Catch Hook» in Zapier, «Webhooks → Custom webhook» in Make, il nodo «Webhook» in n8n. Copia l’indirizzo https che ti dà.
  2. In Sanovia apri Impostazioni → Integrazioni → API e webhook → «Nuovo webhook»: incolla l’indirizzo, scegli l’evento document.issued, salva e conserva il segreto di firma.
  3. Premi «Invia evento di prova»: lo strumento riceve un esempio e ti mostra i campi.
  4. Aggiungi l’azione che scrive una riga in Google Sheets o in Excel e associa le colonne ai campi di data: numero, data di emissione, totale (total_cents diviso 100).
  5. Dove lo strumento ti permette un passo di codice, verifica la firma con lo snippet qui sopra prima di scrivere la riga, e usa Sanovia-Event-Id per non scrivere due volte lo stesso evento.

Ogni giorno i nuovi incassi nel CRM o nel gestionale contabile

  1. In Sanovia crea una chiave con il solo ambito payments:read e copiala.
  2. Nello strumento crea un trigger a orario: «Schedule by Zapier» in Zapier, la pianificazione dello scenario in Make, il nodo «Schedule Trigger» in n8n.
  3. Aggiungi una richiesta HTTP GET a https://sanovia.app/api/v1/public/payments con from e to uguali al giorno prima e l’intestazione Authorization: Bearer seguita dalla tua chiave.
  4. Se next_cursor non è null, ripeti la richiesta con cursor uguale a quel valore, finché diventa null.
  5. Per ogni elemento di data crea o aggiorna il record nel CRM usando id come chiave: così, se rileggi un giorno, non crei doppioni.

Cosa non fa

Crea l’account gratis · Prezzi · Sanovia — Gestionale cloud per studi e professionisti della salute