Riferimento strumenti

Il server offre gli strumenti descritti di seguito. Ciascuno richiede uno specifico permesso (scope) OAuth: una sessione limitata a scorecards:read non potrà richiamare funzioni contrassegnate con scorecards:write.

Gli strumenti indicati come distruttivi sovrascrivono o cancellano informazioni esistenti. La quasi totalità dei client richiederà conferma prima di eseguirli.

scorecard_design_guide

Guida metodologica consigliata prima di creare o modificare una scorecard. Approfondisce le domande di inquadramento, la formulazione di risposte realistiche, la redazione dei testi di livello e la selezione del tema.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
topics	array di stringhe	no	Sezioni specifiche da consultare (es. “themes”, “questions”). Di base tutte.

list_scorecards

Elenca le scorecard del profilo con slug, stato di pubblicazione, numero di invii e domini abilitati all’incorporamento.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
status	all | published | draft	no	Filtro per stato di pubblicazione. Default: all.

get_scorecard

Recupera una scorecard in ogni dettaglio: parametri visivi, dimensioni, quesiti, scelte di risposta e livelli di punteggio.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Lo slug identificativo della scorecard.

create_scorecard

Inizializza una nuova bozza con opzioni di layout, branding, fasce di risultato, incorporamento e raccolta email.

Scope: scorecards:write

Argomento	Tipo	Obbligatorio	Descrizione
title	stringa	sì	Titolo presentato ai partecipanti.
subtitle	stringa	no	Sottotitolo illustrativo con destinatari e tempo di compilazione.
slug	stringa	no	Slug univoco per l’indirizzo web. Ricavato dal titolo se tralasciato.
idempotencyKey	stringa	no	Chiave per prevenire duplicazioni in caso di chiamate ripetute.
ctaText	stringa	no	Testo del pulsante di avvio.
version	stringa	no	Codice di versione interno (es. “1.0”).
theme	default | playground | obsidian | brutalist	no	Tema visivo scelto.
overallTierStrategy	weakest | average	no	Criterio di sintesi del risultato: weakest (dimensione più debole) o average (media ponderata).
tiers	array di oggetti	no	Struttura dei livelli complessivi.
emailCaptureBeforeQuestions	booleano	no	Richiesta dell’email prima (true) o dopo (false) i quesiti.
privacyPolicyUrl	stringa o null	no	Link all’informativa sulla privacy.
termsUrl	stringa o null	no	Link alle condizioni di servizio.
embed	oggetto	no	Regole per l’integrazione iframe.
branding	oggetto	no	Colori aziendali, logo e chiamata all’azione finale.
emailCapture	oggetto	no	Configurazione della schermata di contatto.
detail	summary | full	no	Profondità dell’output (summary per impostazione predefinita).

update_scorecard_config

Aggiorna le impostazioni generali di una scorecard senza intervenire su dimensioni, domande o risposte.

Scope: scorecards:write · distruttivo

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug attuale della scorecard da modificare.
newSlug	stringa	no	Nuovo slug (non attiva alcun reindirizzamento dal vecchio indirizzo).
title	stringa	no	Nuovo titolo.
subtitle	stringa	no	Nuovo sottotitolo.
ctaText	stringa	no	Nuovo testo del pulsante iniziale.
version	stringa	no	Nuovo identificativo di versione.
theme	default | playground | obsidian | brutalist	no	Nuovo tema visivo.
overallTierStrategy	weakest | average	no	Nuovo criterio di calcolo sintetico.
tiers	array di oggetti	no	Nuove fasce generali.
emailCaptureBeforeQuestions	booleano	no	Collocazione della raccolta email.
privacyPolicyUrl	stringa o null	no	Nuovo link di privacy.
termsUrl	stringa o null	no	Nuovo link dei termini.
embed	oggetto	no	Modifiche all’incorporamento.
branding	oggetto	no	Modifiche alla palette di colori.
emailCapture	oggetto	no	Modifiche ai campi di contatto.
detail	summary | full	no	Grado di dettaglio della risposta.

add_dimension

Aggiunge un asse valutativo alla scorecard.

Scope: scorecards:write

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
label	stringa	sì	Nome della dimensione.
shortLabel	stringa	no	Etichetta abbreviata per i grafici.
key	stringa	no	Chiave fissa della dimensione.
detail	summary | full	no	Grado di dettaglio della risposta.

add_questions

Inserisce tutte le domande di una dimensione con una singola chiamata. Le risposte devono essere ordinate dalla peggiore alla migliore e corredate di punteggio.

Scope: scorecards:write

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
dimensionKey	stringa	sì	Chiave della dimensione a cui assegnare le domande.
questions	array di oggetti	sì	Elenco strutturato dei quesiti (consigliati da 3 a 5).
detail	summary | full	no	Grado di dettaglio della risposta.

add_question

Inserisce una domanda singola all’interno di una dimensione esistente.

Scope: scorecards:write

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
dimensionKey	stringa	sì	Chiave della dimensione.
text	stringa	sì	Testo del quesito.
answers	array di oggetti	no	Opzioni di risposta con relativo punteggio.
detail	summary | full	no	Grado di dettaglio della risposta.

set_dimension_tiers

Imposta le fasce di risultato di una dimensione (titolo ed esito diagnostico), ordinate dal livello più basso a quello più alto.

Scope: scorecards:write · distruttivo, idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
dimensionKey	stringa	sì	Chiave della dimensione interessata.
tiers	array di oggetti	sì	Fasce di livello in ordine progressivo (di norma tre).
detail	summary | full	no	Grado di dettaglio della risposta.

update_dimension

Modifica denominazione, etichetta breve, peso o posizione di una dimensione. La chiave fissa rimane inalterata.

Scope: scorecards:write · distruttivo, idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
dimensionKey	stringa	sì	Chiave della dimensione da editare.
label	stringa	no	Nuova denominazione completa.
shortLabel	stringa	no	Nuova etichetta breve.
weight	intero	no	Peso relativo nel computo globale.
position	intero	no	Nuova posizione ordinale (partendo da 0).
detail	summary | full	no	Grado di dettaglio della risposta.

update_question

Modifica formulazione, opzioni di risposta o collocazione di una domanda.

Scope: scorecards:write · distruttivo, idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
questionId	stringa	sì	Identificativo univoco della domanda.
text	stringa	no	Nuova formulazione del quesito.
answers	array di oggetti	no	Nuove opzioni di risposta con punteggio.
position	intero	no	Nuova posizione all’interno della dimensione.
detail	summary | full	no	Grado di dettaglio della risposta.

remove_question

Elimina una domanda dalla sua dimensione, ricalcolando automaticamente gli intervalli di punteggio dei livelli.

Scope: scorecards:write · distruttivo

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
questionId	stringa	sì	Identificativo della domanda da eliminare.
detail	summary | full	no	Grado di dettaglio della risposta.

remove_dimension

Cancella un’intera dimensione e tutte le domande in essa contenute.

Scope: scorecards:write · distruttivo

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
dimensionKey	stringa	sì	Chiave della dimensione da cancellare.
detail	summary | full	no	Grado di dettaglio della risposta.

check_scorecard

Verifica se la scorecard soddisfa i criteri per essere pubblicata ed evidenzia eventuali punti deboli.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.

publish_scorecard

Rende pubblica la scorecard o la riporta allo stato di bozza.

Scope: scorecards:write · distruttivo, idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	sì	Slug della scorecard.
published	booleano	no	true per pubblicare, false per riportare a bozza.
detail	summary | full	no	Grado di dettaglio della risposta.

list_submissions

Elenca le risposte registrate, con possibilità di filtro per scorecard, stato di compilazione, livello o data.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
slug	stringa	no	Limita la ricerca a una scorecard.
status	all | completed | partial	no	Compilazioni completate o interrotte.
tier	stringa	no	Filtro per livello sintetico ottenuto.
dimension	stringa	no	Filtro per dimensione più debole.
since	stringa	no	A partire dalla data (AAAA-MM-GG).
until	stringa	no	Fino alla data (AAAA-MM-GG).
search	stringa	no	Ricerca per testo su nome, email o azienda.
limit	intero	no	Numero di record restituiti (default: 25).

get_submission

Recupera una compilazione nella sua interezza: dati di contatto, esito globale, punteggi per asse e risposte precise memorizzate.

Scope: scorecards:read · idempotente

Argomento	Tipo	Obbligatorio	Descrizione
submissionId	stringa	sì	Identificativo della compilazione.