Referencia de herramientas

El servidor expone el conjunto de herramientas detallado a continuación. Cada función exige un determinado permiso (scope) OAuth: una conexión limitada a scorecards:read no podrá invocar funciones marcadas con scorecards:write.

Las operaciones clasificadas como destructivas sustituyen o eliminan información guardada. La mayoría de clientes solicitarán confirmación antes de ejecutarlas.

scorecard_design_guide

Guía metodológica recomendada antes de crear o editar una evaluación. Abarca preguntas iniciales de enfoque, técnicas contra sesgos, redacción de diagnósticos y selección de temas.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
topics	matriz de cadenas	no	Temas específicos a consultar (p. ej., “themes”, “questions”). Por defecto todos.

list_scorecards

Relación de scorecards de la cuenta, con su slug, estado de publicación, volumen de envíos y dominios de incrustación autorizados.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
status	all | published | draft	no	Filtro según estado de publicación. Por defecto all.

get_scorecard

Recupera una scorecard al completo: ajustes, dimensiones, preguntas, respuestas y niveles de evaluación.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug identificativo de la scorecard.

create_scorecard

Inicializa un borrador con ajustes de diseño, marca, niveles globales, incrustación y captura de contactos.

Scope: scorecards:write

Parámetro	Tipo	Requerido	Descripción
title	cadena	sí	Título de la evaluación mostrado a los participantes.
subtitle	cadena	no	Subtítulo explicativo con destinatarios y duración.
slug	cadena	no	Slug único para la dirección web. Si no se pasa, deriva del título.
idempotencyKey	cadena	no	Clave para evitar duplicados en reintentos.
ctaText	cadena	no	Texto del botón inicial.
version	cadena	no	Identificador interno de versión (ej. “1.0”).
theme	default | playground | obsidian | brutalist	no	Tema visual elegido.
overallTierStrategy	weakest | average	no	Método de cálculo global: weakest (dimensión más rezagada) o average (promedio).
tiers	matriz de objetos	no	Configuración de los niveles globales.
emailCaptureBeforeQuestions	booleano	no	Pedir el correo antes (true) o después (false) del cuestionario.
privacyPolicyUrl	cadena o null	no	Dirección de la política de privacidad.
termsUrl	cadena o null	no	Dirección de los términos y condiciones.
embed	objeto	no	Parámetros para la incrustación en iframe.
branding	objeto	no	Colores corporativos, logotipo y llamadas a la acción.
emailCapture	objeto	no	Textos y campos del formulario de registro.
detail	summary | full	no	Extensión del resultado (summary por defecto).

update_scorecard_config

Modifica las opciones generales de una scorecard sin alterar sus dimensiones, preguntas o respuestas.

Scope: scorecards:write · destructiva

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug actual de la scorecard.
newSlug	cadena	no	Nuevo slug asignado (no genera redirección automática).
title	cadena	no	Nuevo título.
subtitle	cadena	no	Nuevo subtítulo.
ctaText	cadena	no	Nuevo texto para el botón de inicio.
version	cadena	no	Nueva referencia de versión.
theme	default | playground | obsidian | brutalist	no	Nuevo tema visual.
overallTierStrategy	weakest | average	no	Nuevo criterio de cálculo global.
tiers	matriz de objetos	no	Nuevos niveles generales.
emailCaptureBeforeQuestions	booleano	no	Momento de petición del correo.
privacyPolicyUrl	cadena o null	no	Enlace actualizado de privacidad.
termsUrl	cadena o null	no	Enlace actualizado de condiciones.
embed	objeto	no	Modificaciones en ajustes de incrustación.
branding	objeto	no	Modificaciones en elementos de marca.
emailCapture	objeto	no	Modificaciones en formulario de contacto.
detail	summary | full	no	Extensión del resultado devuelto.

add_dimension

Añade un nuevo eje de evaluación a una scorecard.

Scope: scorecards:write

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
label	cadena	sí	Nombre de la dimensión.
shortLabel	cadena	no	Etiqueta corta para gráficos y ejes.
key	cadena	no	Clave permanente de la dimensión.
detail	summary | full	no	Extensión del resultado devuelto.

add_questions

Incorpora todas las preguntas asociadas a una dimensión en una única operación. Las respuestas deben estar puntuadas y jerarquizadas de peor a mejor.

Scope: scorecards:write

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
dimensionKey	cadena	sí	Clave de la dimensión asociada.
questions	matriz de objetos	sí	Listado ordenado de preguntas (recomendado de 3 a 5).
detail	summary | full	no	Extensión del resultado devuelto.

add_question

Inserta una pregunta individual en una dimensión existente.

Scope: scorecards:write

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
dimensionKey	cadena	sí	Clave de la dimensión receptora.
text	cadena	sí	Enunciado de la pregunta.
answers	matriz de objetos	no	Alternativas de respuesta con su puntuación.
detail	summary | full	no	Extensión del resultado devuelto.

set_dimension_tiers

Fija los niveles de diagnóstico de una dimensión (nombre y texto explicativo), ordenados de menor a mayor resultado.

Scope: scorecards:write · destructiva, idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
dimensionKey	cadena	sí	Clave de la dimensión a configurar.
tiers	matriz de objetos	sí	Niveles en orden ascendente (habitualmente tres).
detail	summary | full	no	Extensión del resultado devuelto.

update_dimension

Modifica el título, etiqueta abreviada, peso o posición de una dimensión. La clave no varía.

Scope: scorecards:write · destructiva, idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
dimensionKey	cadena	sí	Clave de la dimensión que se va a editar.
label	cadena	no	Nuevo nombre completo.
shortLabel	cadena	no	Nueva etiqueta corta.
weight	entero	no	Ponderación en el resultado conjunto.
position	entero	no	Nueva posición secuencial (índice 0).
detail	summary | full	no	Extensión del resultado devuelto.

update_question

Edita el enunciado, opciones de respuesta o posición de una pregunta concreta.

Scope: scorecards:write · destructiva, idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
questionId	cadena	sí	Identificador único de la pregunta.
text	cadena	no	Nuevo enunciado.
answers	matriz de objetos	no	Nuevas opciones y puntuaciones.
position	entero	no	Nueva ubicación en la dimensión.
detail	summary | full	no	Extensión del resultado devuelto.

remove_question

Elimina una pregunta de su dimensión y recalcula automáticamente los límites de puntos.

Scope: scorecards:write · destructiva

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
questionId	cadena	sí	Identificador de la pregunta a retirar.
detail	summary | full	no	Extensión del resultado devuelto.

remove_dimension

Borra una dimensión entera junto con las preguntas vinculadas a ella.

Scope: scorecards:write · destructiva

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
dimensionKey	cadena	sí	Clave de la dimensión que se eliminará.
detail	summary | full	no	Extensión del resultado devuelto.

check_scorecard

Examina la preparación de una scorecard de cara a su publicación e indica elementos mejorables.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.

publish_scorecard

Activa la disponibilidad pública de la scorecard o la regresa a borrador.

Scope: scorecards:write · destructiva, idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	sí	Slug de la scorecard.
published	booleano	no	true para publicar, false para borrador.
detail	summary | full	no	Extensión del resultado devuelto.

list_submissions

Muestra los registros completados por los participantes, con filtros por scorecard, estado, nivel o fecha.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
slug	cadena	no	Restringir a una scorecard dada.
status	all | completed | partial	no	Filtrar completados o parciales.
tier	cadena	no	Filtrar por nivel general alcanzado.
dimension	cadena	no	Filtrar por dimensión más débil.
since	cadena	no	A partir de fecha (AAAA-MM-DD).
until	cadena	no	Hasta fecha (AAAA-MM-DD).
search	cadena	no	Coincidencia de texto en nombre, correo o empresa.
limit	entero	no	Cantidad de filas a mostrar (por defecto 25).

get_submission

Obtiene el detalle completo de un envío: persona de contacto, puntuación global, notas por dimensión y respuestas emitidas.

Scope: scorecards:read · idempotente

Parámetro	Tipo	Requerido	Descripción
submissionId	cadena	sí	Identificador del envío según list_submissions.