Referência de ferramentas

O servidor disponibiliza as seguintes ferramentas. Cada uma especifica o escopo OAuth exigido: conexões com permissão apenas de scorecards:read não conseguem executar rotinas que exijam scorecards:write.

Ações classificadas como destrutivas alteram ou removem dados existentes. A maioria dos clientes solicitará confirmação antes da execução.

scorecard_design_guide

Guia de estilo e boas práticas a ser consultado antes de criar ou modificar uma avaliação. Contempla perguntas de alinhamento, técnicas de formulação de perguntas, elaboração de diagnósticos e escolha de temas.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
topics	array de strings	não	Seções específicas a consultar (ex.: “themes”, “questions”). Padrão: todas.

list_scorecards

Lista as scorecards da conta com slug, status de publicação, contagem de envios e domínios autorizados para incorporação.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
status	all | published | draft	não	Filtro por status de publicação. Padrão: all.

get_scorecard

Lê uma scorecard completa: opções visuais, dimensões, perguntas, alternativas e faixas de pontuação.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	O slug da scorecard.

create_scorecard

Cria um novo rascunho com opções visuais, marca, níveis globais, incorporação e captura de e-mails.

Escopo: scorecards:write

Argumento	Tipo	Obrigatório	Descrição
title	string	sim	Título visível para os respondentes.
subtitle	string	não	Subtítulo com objetivo e tempo estimado.
slug	string	não	Slug exclusivo para a URL. Derivado do título se não informado.
idempotencyKey	string	não	Chave para evitar criações duplicadas em retentativas.
ctaText	string	não	Texto do botão que inicia o questionário.
version	string	não	Versão interna de controle (ex.: “1.0”).
theme	default | playground | obsidian | brutalist	não	Tema visual escolhido.
overallTierStrategy	weakest | average	não	Critério de cálculo do resultado global: weakest (pior dimensão) ou average (média).
tiers	array de objetos	não	Estrutura dos níveis globais de resultado.
emailCaptureBeforeQuestions	boolean	não	Pedir e-mail antes (true) ou depois (false) das questões.
privacyPolicyUrl	string ou null	não	Link da política de privacidade.
termsUrl	string ou null	não	Link dos termos de uso.
embed	objeto	não	Opções de incorporação em iframe.
branding	objeto	não	Cores corporativas, logotipo e chamada de fechamento.
emailCapture	objeto	não	Configurações da tela de captura de contatos.
detail	summary | full	não	Nível de detalhe do retorno (summary por padrão).

update_scorecard_config

Atualiza a configuração geral de uma scorecard sem alterar dimensões, perguntas ou respostas.

Escopo: scorecards:write · destrutivo

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug atual da scorecard.
newSlug	string	não	Novo slug (não cria redirecionamento da URL antiga).
title	string	não	Novo título.
subtitle	string	não	Novo subtítulo.
ctaText	string	não	Novo texto do botão inicial.
version	string	não	Nova identificação de versão.
theme	default | playground | obsidian | brutalist	não	Novo tema visual.
overallTierStrategy	weakest | average	não	Novo método de cálculo global.
tiers	array de objetos	não	Novos níveis globais.
emailCaptureBeforeQuestions	boolean	não	Momento de captura do e-mail.
privacyPolicyUrl	string ou null	não	Nova URL de privacidade.
termsUrl	string ou null	não	Nova URL de termos.
embed	objeto	não	Novos parâmetros de incorporação.
branding	objeto	não	Nova paleta de cores e marca.
emailCapture	objeto	não	Alterações nos campos de contato.
detail	summary | full	não	Nível de detalhe do retorno.

add_dimension

Insere uma dimensão de avaliação na scorecard.

Escopo: scorecards:write

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
label	string	sim	Nome da dimensão.
shortLabel	string	não	Rótulo abreviado para gráficos.
key	string	não	Identificador permanente da dimensão.
detail	summary | full	não	Nível de detalhe do retorno.

add_questions

Adiciona todas as perguntas de uma dimensão em uma única operação. As opções devem ser pontuadas e organizadas da pior para a melhor.

Escopo: scorecards:write

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
dimensionKey	string	sim	Chave da dimensão de destino.
questions	array de objetos	sim	Lista ordenada de perguntas (sugestão: 3 a 5).
detail	summary | full	não	Nível de detalhe do retorno.

add_question

Insere uma pergunta avulsa em uma dimensão.

Escopo: scorecards:write

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
dimensionKey	string	sim	Chave da dimensão.
text	string	sim	Enunciado da questão.
answers	array de objetos	não	Alternativas com suas pontuações.
detail	summary | full	não	Nível de detalhe do retorno.

set_dimension_tiers

Configura os níveis de resultado de uma dimensão (título e diagnóstico), ordenados do pior para o melhor.

Escopo: scorecards:write · destrutivo, idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
dimensionKey	string	sim	Chave da dimensão.
tiers	array de objetos	sim	Níveis em ordem crescente (geralmente três).
detail	summary | full	não	Nível de detalhe do retorno.

update_dimension

Modifica o nome, rótulo curto, peso ou ordenação de uma dimensão. A chave permanente não é alterada.

Escopo: scorecards:write · destrutivo, idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
dimensionKey	string	sim	Chave da dimensão a editar.
label	string	não	Novo nome completo.
shortLabel	string	não	Novo rótulo curto.
weight	integer	não	Peso na consolidação global.
position	integer	não	Nova posição numérica (índice 0).
detail	summary | full	não	Nível de detalhe do retorno.

update_question

Altera o texto, as opções de resposta ou a ordem de uma pergunta.

Escopo: scorecards:write · destrutivo, idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
questionId	string	sim	Identificador único da questão.
text	string	não	Novo enunciado.
answers	array de objetos	não	Novas opções de resposta e notas.
position	integer	não	Nova posição na dimensão.
detail	summary | full	não	Nível de detalhe do retorno.

remove_question

Remove uma pergunta de sua dimensão, recalculando automaticamente as faixas de pontos.

Escopo: scorecards:write · destrutivo

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
questionId	string	sim	Identificador da pergunta a excluir.
detail	summary | full	não	Nível de detalhe do retorno.

remove_dimension

Exclui uma dimensão completa com todas as questões vinculadas.

Escopo: scorecards:write · destrutivo

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
dimensionKey	string	sim	Chave da dimensão a ser removida.
detail	summary | full	não	Nível de detalhe do retorno.

check_scorecard

Verifica se uma scorecard preenche todas as condições para ser publicada e identifica deficiências.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.

publish_scorecard

Torna a scorecard pública ou a reverte para o estado de rascunho.

Escopo: scorecards:write · destrutivo, idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	sim	Slug da scorecard.
published	boolean	não	true para publicar, false para rascunho.
detail	summary | full	não	Nível de detalhe do retorno.

list_submissions

Lista os participantes que responderam às avaliações, com filtros por status, nível atingido ou data.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
slug	string	não	Filtrar por uma scorecard específica.
status	all | completed | partial	não	Filtrar concluídos ou parciais.
tier	string	não	Filtrar por nível global obtido.
dimension	string	não	Filtrar por dimensão com menor pontuação.
since	string	não	A partir da data (AAAA-MM-DD).
until	string	não	Até a data (AAAA-MM-DD).
search	string	não	Busca por nome, e-mail ou empresa.
limit	integer	não	Quantidade de registros (padrão: 25).

get_submission

Recupera um envio completo: dados de contato, notas por dimensão, resultado consolidado e respostas detalhadas.

Escopo: scorecards:read · idempotente

Argumento	Tipo	Obrigatório	Descrição
submissionId	string	sim	Identificador do envio retornado por list_submissions.