Dokumentacja narzędzi

Serwer udostępnia poniższe narzędzia. Każde wymaga określonego zakresu (scope) OAuth: połączenie posiadające wyłącznie scorecards:read nie uruchomi narzędzi wymagających scorecards:write.

Narzędzia oznaczone jako destrukcyjne modyfikują lub usuwają istniejące rekordy. Większość klientów poprosi o potwierdzenie przed ich wykonaniem.

scorecard_design_guide

Niezbędny przewodnik przed przystąpieniem do tworzenia lub głębszej edycji formularza. Obejmuje pytania wstępne, zasady układania pytań, formułowanie wniosków diagnostycznych i dobór motywu.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
topics	tablica ciągów	nie	Sekcje tematyczne (np. “themes”, “questions”). Domyślnie wszystkie.

list_scorecards

Zwraca listę formularzy na koncie wraz ze slugiem, statusem publikacji, liczbą odpowiedzi i autoryzowanymi domenami.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
status	all | published | draft	nie	Filtrowanie po statusie. Domyślnie all.

get_scorecard

Pobiera pełną konfigurację formularza: parametry prezentacji, wymiary, pytania, opcje odpowiedzi i progi punktowe.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Unikalny slug formularza.

create_scorecard

Tworzy nowy szkic z ustawieniami wizualnymi, marką, strategią oceny, parametrami osadzania i zbieraniem kontaktów.

Zakres: scorecards:write

Parametr	Typ	Wymagany	Opis
title	ciąg znaków	tak	Tytuł widoczny dla respondentów.
subtitle	ciąg znaków	nie	Podtytuł informujący o celu i czasie trwania.
slug	ciąg znaków	nie	Unikalny slug URL. Domyślnie generowany z tytułu.
idempotencyKey	ciąg znaków	nie	Klucz zapobiegający powielaniu operacji przy ponowieniach sieciowych.
ctaText	ciąg znaków	nie	Tekst na przycisku startowym.
version	ciąg znaków	nie	Wewnętrzne oznaczenie wersji (np. “1.0”).
theme	default | playground | obsidian | brutalist	nie	Wybrany motyw wizualny.
overallTierStrategy	weakest | average	nie	Metoda wyliczania wyniku ogólnego: weakest (najsłabszy wymiar) lub average (średnia).
tiers	tablica obiektów	nie	Konfiguracja poziomów podsumowania.
emailCaptureBeforeQuestions	wartość logiczna	nie	Pobieranie e-maila przed (true) lub po (false) pytaniach.
privacyPolicyUrl	ciąg znaków lub null	nie	Adres polityki prywatności.
termsUrl	ciąg znaków lub null	nie	Adres regulaminu.
embed	obiekt	nie	Ustawienia osadzania iframe.
branding	obiekt	nie	Barwy marki, logo i końcowe CTA.
emailCapture	obiekt	nie	Konfiguracja formularza kontaktowego.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi (domyślnie summary).

update_scorecard_config

Aktualizuje ustawienia główne formularza bez ingerencji w wymiary, pytania czy odpowiedzi.

Zakres: scorecards:write · destrukcyjne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Aktualny slug edytowanej scorecardy.
newSlug	ciąg znaków	nie	Nowy slug (nie tworzy przekierowania ze starego adresu).
title	ciąg znaków	nie	Nowy tytuł.
subtitle	ciąg znaków	nie	Nowy podtytuł.
ctaText	ciąg znaków	nie	Nowy tekst przycisku startowego.
version	ciąg znaków	nie	Nowe oznaczenie wersji.
theme	default | playground | obsidian | brutalist	nie	Nowy motyw graficzny.
overallTierStrategy	weakest | average	nie	Nowa strategia wyliczania wyniku ogólnego.
tiers	tablica obiektów	nie	Nowe poziomy ogólne.
emailCaptureBeforeQuestions	wartość logiczna	nie	Moment zapytania o e-mail.
privacyPolicyUrl	ciąg znaków lub null	nie	Nowy adres polityki prywatności.
termsUrl	ciąg znaków lub null	nie	Nowy adres regulaminu.
embed	obiekt	nie	Zaktualizowane reguły osadzania.
branding	obiekt	nie	Zaktualizowane barwy i elementy marki.
emailCapture	obiekt	nie	Zaktualizowany formularz kontaktu.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

add_dimension

Dodaje nowy wymiar diagnostyczny do formularza.

Zakres: scorecards:write

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
label	ciąg znaków	tak	Pełna nazwa wymiaru.
shortLabel	ciąg znaków	nie	Krótka nazwa na osie wykresów.
key	ciąg znaków	nie	Trwały klucz identyfikacyjny wymiaru.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

add_questions

Dodaje komplet pytań dla jednego wymiaru w pojedynczej operacji. Odpowiedzi muszą być uszeregowane od najgorszej do najlepszej wraz z punktacją.

Zakres: scorecards:write

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
dimensionKey	ciąg znaków	tak	Klucz docelowego wymiaru.
questions	tablica obiektów	tak	Lista pytań w kolejności wyświetlania (zalecane: 3 do 5).
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

add_question

Dodaje pojedyncze pytanie do istniejącego wymiaru.

Zakres: scorecards:write

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
dimensionKey	ciąg znaków	tak	Klucz wymiaru.
text	ciąg znaków	tak	Treść pytania.
answers	tablica obiektów	nie	Opcje odpowiedzi wraz z wagami.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

set_dimension_tiers

Definiuje poziomy diagnostyczne dla danego wymiaru (nazwę i diagnozę), uszeregowane od najniższego do najwyższego.

Zakres: scorecards:write · destrukcyjne, idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
dimensionKey	ciąg znaków	tak	Klucz konfigurowanego wymiaru.
tiers	tablica obiektów	tak	Poziomy w porządku rosnącym (zwykle trzy).
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

update_dimension

Zmienia nazwę, etykietę skróconą, wagę lub pozycję wymiaru. Klucz wymiaru pozostaje bez zmian.

Zakres: scorecards:write · destrukcyjne, idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
dimensionKey	ciąg znaków	tak	Klucz edytowanego wymiaru.
label	ciąg znaków	nie	Nowa pełna nazwa.
shortLabel	ciąg znaków	nie	Nowa etykieta skrócona.
weight	liczba całkowita	nie	Waga względna w ocenie łącznej.
position	liczba całkowita	nie	Nowa pozycja (indeksowana od 0).
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

update_question

Modyfikuje treść, warianty odpowiedzi lub kolejność pytania.

Zakres: scorecards:write · destrukcyjne, idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
questionId	ciąg znaków	tak	Unikalny identyfikator pytania.
text	ciąg znaków	nie	Nowa treść pytania.
answers	tablica obiektów	nie	Nowe opcje odpowiedzi i punktacja.
position	liczba całkowita	nie	Nowa pozycja wewnątrz wymiaru.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

remove_question

Usuwa pytanie z wymiaru i automatycznie przelicza progi punktowe poziomów.

Zakres: scorecards:write · destrukcyjne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
questionId	ciąg znaków	tak	Identyfikator usuwanego pytania.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

remove_dimension

Usuwa cały wymiar wraz ze wszystkimi przypisanymi do niego pytaniami.

Zakres: scorecards:write · destrukcyjne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
dimensionKey	ciąg znaków	tak	Klucz usuwanego wymiaru.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

check_scorecard

Weryfikuje kompletność scorecardy pod kątem publikacji i wskazuje elementy wymagające dopracowania.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug weryfikowanej scorecardy.

publish_scorecard

Publikuje scorecardę lub cofa ją do statusu wersji roboczej.

Zakres: scorecards:write · destrukcyjne, idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	tak	Slug scorecardy.
published	wartość logiczna	nie	true publikuje, false cofa do szkicu.
detail	summary | full	nie	Poziom szczegółowości odpowiedzi.

list_submissions

Wyświetla nadesłane odpowiedzi w porządku od najnowszych, z możliwością filtrowania po statusie, poziomie czy dacie.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
slug	ciąg znaków	nie	Ograniczenie do wybranej scorecardy.
status	all | completed | partial	nie	Zgłoszenia pełne lub porzucone.
tier	ciąg znaków	nie	Filtrowanie po uzyskanym poziomie ogólnym.
dimension	ciąg znaków	nie	Filtrowanie po najsłabszym wymiarze.
since	ciąg znaków	nie	Od daty (RRRR-MM-DD).
until	ciąg znaków	nie	Do daty (RRRR-MM-DD).
search	ciąg znaków	nie	Wyszukiwanie frazy w nazwisku, e-mailu lub firmie.
limit	liczba całkowita	nie	Liczba wierszy (domyślnie 25).

get_submission

Pobiera kompletne dane pojedynczego zgłoszenia: kontakt, rezultat ogólny, oceny cząstkowe i oryginalne odpowiedzi.

Zakres: scorecards:read · idempotentne

Parametr	Typ	Wymagany	Opis
submissionId	ciąg znaków	tak	Identyfikator zgłoszenia.