{"openapi":"3.1.0","info":{"title":"KinetiCRM API","version":"1.0.0","description":"API per collegare KinetiCRM a gestionali, siti e strumenti dello studio. Ogni chiave appartiene a un solo studio e ha permessi per categoria di dato (anagrafica, agenda, misure, fatture, richieste), decisi dall'amministratore in Impostazioni, API. Ogni richiesta resta nel registro di audit dello studio, anche quelle rifiutate. Non sono esposti i dati sanitari: niente KinetiCure, parametri fisiologici, dolore e sintomi. Limite: 120 richieste al minuto per chiave."},"servers":[{"url":"/api/v1"}],"security":[{"chiave":[]}],"components":{"securitySchemes":{"chiave":{"type":"http","scheme":"bearer","description":"Chiave dello studio, nel formato kcrm_<codice-studio>_<segreto>"}},"schemas":{"Persona":{"type":"object","properties":{"id":{"type":"string"},"nome":{"type":"string"},"cognome":{"type":"string"},"dataNascita":{"type":["string","null"],"format":"date"},"sesso":{"type":["string","null"],"enum":["M","F","X",null]},"codiceFiscale":{"type":["string","null"]},"email":{"type":["string","null"]},"telefono":{"type":["string","null"]},"indirizzo":{"type":["string","null"]},"citta":{"type":["string","null"]},"cap":{"type":["string","null"]},"stato":{"type":"string","enum":["potenziale","attivo","inattivo","chiuso"]},"canaleAcquisizione":{"type":["string","null"]},"dataAcquisizione":{"type":["string","null"],"format":"date"},"professionistaId":{"type":["string","null"]},"creatoAt":{"type":"string","format":"date-time"},"aggiornatoAt":{"type":["string","null"],"format":"date-time"}}},"NuovaPersona":{"type":"object","required":["nome","cognome"],"properties":{"nome":{"type":"string"},"cognome":{"type":"string"},"email":{"type":"string"},"telefono":{"type":"string","description":"Salvato in formato internazionale; senza prefisso vale come italiano, un numero non valido dà 422. Email e telefono diventano i recapiti preferiti."},"dataNascita":{"type":"string","format":"date"},"canale":{"type":"string","description":"Canale di acquisizione, predefinito API"},"note":{"type":"string","description":"Note amministrative"}}},"Appuntamento":{"type":"object","properties":{"id":{"type":"string"},"personaId":{"type":["string","null"],"description":"Null per un appuntamento fissato a una richiesta del CRM non ancora convertita in persona"},"professionistaId":{"type":["string","null"]},"sedeId":{"type":["string","null"]},"stanzaId":{"type":["string","null"]},"servizioId":{"type":["string","null"],"description":"Servizio del catalogo, se indicato"},"tipologia":{"type":"string"},"inizio":{"type":"string","description":"Data e ora locali della sede, AAAA-MM-GGTHH:MM"},"fine":{"type":"string","description":"Data e ora locali di fine, AAAA-MM-GGTHH:MM"},"durataMin":{"type":"integer"},"stato":{"type":"string","enum":["provvisorio","in_attesa","programmato","confermato","completato","assente","cancellato"],"description":"provvisorio: orario tenuto per pochi minuti in attesa di conferma; in_attesa: in attesa della conferma della persona"}}},"Rilevazione":{"type":"object","properties":{"id":{"type":"string"},"dataOra":{"type":"string"},"misura":{"type":"string","description":"Codice del catalogo"},"nome":{"type":"string"},"valore":{"type":["number","null"]},"valoreTesto":{"type":["string","null"]},"unita":{"type":["string","null"]},"lato":{"type":["string","null"]},"fonte":{"type":"string"},"stato":{"type":"string"}}},"Fattura":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string","enum":["fattura","nota_credito"]},"numero":{"type":"string"},"data":{"type":"string","format":"date"},"scadenza":{"type":["string","null"],"format":"date"},"personaId":{"type":"string"},"riferimentoId":{"type":["string","null"],"description":"Per una nota di credito: la fattura che rettifica"},"intestatario":{"type":["object","null"],"description":"Dati dell'intestatario copiati all'emissione: tipo, denominazione, codice fiscale, partita IVA, indirizzo, codice destinatario, PEC"},"righe":{"type":"array","items":{"type":"object","required":["descrizione","quantita","prezzo","aliquota"],"properties":{"descrizione":{"type":"string"},"quantita":{"type":"number"},"prezzo":{"type":"number","description":"Prezzo unitario senza IVA"},"aliquota":{"type":"number","description":"Aliquota IVA in percentuale (0 per le prestazioni esenti)"},"natura":{"type":"string","description":"Codice natura IVA della fattura elettronica quando l'aliquota è 0 (per esempio N4)"},"sconto":{"type":"number","description":"Sconto percentuale della riga"}}}},"imponibile":{"type":"number"},"iva":{"type":"number"},"bollo":{"type":"number"},"totale":{"type":"number"},"incassato":{"type":"number","description":"Quote dei pagamenti validi attribuite alla fattura"},"stornato":{"type":"number","description":"Totale delle note di credito sulla fattura"},"residuo":{"type":"number","description":"Totale meno note di credito meno incassato"},"stato":{"type":["string","null"],"enum":["emessa","pagata","parzialmente_pagata","insoluta","contestata","annullata",null],"description":"Stato d'incasso, solo per le fatture"},"statoDocumento":{"type":"string","enum":["emessa","inviata"]},"motivo":{"type":["string","null"],"description":"Motivo della nota di credito"}}},"NuovoLead":{"type":"object","description":"Serve il nome o il cognome e almeno un recapito valido (email o telefono).","properties":{"nome":{"type":"string"},"cognome":{"type":"string"},"email":{"type":"string"},"telefono":{"type":"string"},"canale":{"type":"string","default":"sito","description":"Codice di un canale attivo dello studio (sito, telefono, email, whatsapp, social, passaparola, evento, partner...)"},"servizio":{"type":"string","description":"Codice del servizio di interesse"},"messaggio":{"type":"string","description":"Richiesta in forma commerciale; non inviare dati sanitari"},"campagna":{"type":"string"},"sorgente":{"type":"string","description":"Per esempio utm_source"},"mezzo":{"type":"string","description":"Per esempio utm_medium"},"riferimento":{"type":"string","description":"Pagina o modulo di provenienza"},"informativaVersione":{"type":"string","description":"Versione dell'informativa privacy mostrata"},"consensoMarketing":{"type":"boolean","default":false},"chiave":{"type":"string","description":"Chiave di idempotenza, in alternativa all'intestazione Idempotency-Key"}}},"Lead":{"type":"object","properties":{"id":{"type":"string"},"nome":{"type":["string","null"]},"cognome":{"type":["string","null"]},"email":{"type":["string","null"]},"telefono":{"type":["string","null"]},"canale":{"type":"string"},"servizio":{"type":["string","null"]},"campagna":{"type":["string","null"]},"sorgente":{"type":["string","null"]},"mezzo":{"type":["string","null"]},"riferimento":{"type":["string","null"]},"stato":{"type":"string","enum":["nuovo","da_contattare","in_lavorazione","qualificato","non_qualificato","convertito","chiuso"]},"dataAcquisizione":{"type":"string","format":"date"},"consensoMarketing":{"type":"boolean"},"chiave":{"type":["string","null"]},"creatoAt":{"type":"string","format":"date-time"}}},"Errore":{"type":"object","properties":{"errore":{"type":"string"}}}}},"paths":{"/persone":{"get":{"summary":"Elenco delle persone","description":"Permesso: anagrafica, lettura.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Cerca in nome, cognome, email e telefono"},{"name":"stato","in":"query","schema":{"type":"string","enum":["potenziale","attivo","inattivo","chiuso"]}},{"name":"limite","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Pagina di risultati","content":{"application/json":{"schema":{"type":"object","properties":{"dati":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}},"pagina":{"type":"integer"},"limite":{"type":"integer"},"totale":{"type":"integer"}}}}}},"400":{"description":"Valore di stato non ammesso"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}},"post":{"summary":"Nuovo contatto","description":"Crea una persona con stato potenziale, per esempio dal modulo contatti del sito. Permesso: anagrafica, scrittura. Se l'email esiste già risponde 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuovaPersona"}}}},"responses":{"201":{"description":"Creata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"400":{"description":"Il corpo non è un oggetto JSON"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"409":{"description":"Email già presente"},"422":{"description":"Dati non validi"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}},"/persone/{id}":{"get":{"summary":"Una persona","description":"Permesso: anagrafica, lettura.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Persona","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"404":{"description":"Non trovata"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}},"/persone/{id}/rilevazioni":{"get":{"summary":"Misure KinetiCore di una persona","description":"Solo misure valide del modulo Core, senza parametri fisiologici, dolore e sintomi. Permesso: misure, lettura.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"misura","in":"query","schema":{"type":"string"},"description":"Codice del catalogo"},{"name":"da","in":"query","schema":{"type":"string","format":"date"}},{"name":"a","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Misure in ordine di data","content":{"application/json":{"schema":{"type":"object","properties":{"dati":{"type":"array","items":{"$ref":"#/components/schemas/Rilevazione"}}}}}}},"400":{"description":"Parametro non valido (data non nel formato AAAA-MM-GG o stato non ammesso)"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"404":{"description":"Persona non trovata"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}},"/appuntamenti":{"get":{"summary":"Appuntamenti in un intervallo","description":"Intervallo massimo 92 giorni; senza parametri, i prossimi 30 giorni. Solo dati logistici, senza note. Permesso: agenda, lettura.","parameters":[{"name":"da","in":"query","schema":{"type":"string","format":"date"}},{"name":"a","in":"query","schema":{"type":"string","format":"date"}},{"name":"persona","in":"query","schema":{"type":"string"}},{"name":"professionista","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Appuntamenti","content":{"application/json":{"schema":{"type":"object","properties":{"dati":{"type":"array","items":{"$ref":"#/components/schemas/Appuntamento"}},"da":{"type":"string","format":"date"},"a":{"type":"string","format":"date"}}}}}},"400":{"description":"Data non valida o intervallo oltre 92 giorni"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}},"/fatture":{"get":{"summary":"Fatture e note di credito","description":"Documenti emessi (le bozze non compaiono). Permesso: fatture, lettura.","parameters":[{"name":"da","in":"query","schema":{"type":"string","format":"date"}},{"name":"a","in":"query","schema":{"type":"string","format":"date"}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["fattura","nota_credito"]}},{"name":"stato","in":"query","schema":{"type":"string","enum":["emessa","pagata","parzialmente_pagata","insoluta","contestata","annullata"]}},{"name":"persona","in":"query","schema":{"type":"string"}},{"name":"limite","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Fatture con importo incassato","content":{"application/json":{"schema":{"type":"object","properties":{"dati":{"type":"array","items":{"$ref":"#/components/schemas/Fattura"}},"pagina":{"type":"integer"},"limite":{"type":"integer"}}}}}},"400":{"description":"Parametro non valido (data non nel formato AAAA-MM-GG o stato non ammesso)"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}},"/lead":{"post":{"summary":"Nuova richiesta di contatto","description":"Registra una richiesta (lead) dal sito o da un altro strumento, con stato nuovo e un'attività di primo contatto per lo studio. Permesso: richieste, scrittura. Idempotente: con la stessa chiave (intestazione Idempotency-Key o campo chiave) risponde 200 con la richiesta già registrata. I possibili doppioni non vengono uniti: li valuta lo studio.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Chiave unica dell'invio, per esempio l'identificativo del modulo compilato"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuovoLead"}}}},"responses":{"200":{"description":"Già ricevuta con la stessa chiave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"201":{"description":"Creata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"description":"Il corpo non è un oggetto JSON"},"401":{"description":"Chiave mancante, non valida o revocata"},"403":{"description":"Permesso mancante sulla categoria oppure studio sospeso"},"422":{"description":"Dati non validi: manca nome e cognome, manca un recapito valido, canale o servizio sconosciuti"},"429":{"description":"Più di 120 richieste al minuto con la stessa chiave"},"500":{"description":"Errore interno"}}}}}}