Relatório de questionários: esquema JSON de respostas

O relatório do questionário contém o formulário estruturado apresentado a um utilizador, o percurso que seguiu através de eventuais ramificações condicionais e a resposta a cada item visível. É retornado por nó, pelo que os fluxos com múltiplas instâncias (por exemplo, um questionário por UBO) incluem uma entrada por ocorrência.

Relatório do questionário de KYC da Didit a apresentar respostas estruturadas, secções e tipos de elementos

Visão geral

Cada resposta ao questionário descreve:

A versão do questionário que o utilizador viu (título, descrição, idiomas, metadados da versão, secções).
Os itens visíveis no percurso que o utilizador efetivamente seguiu pelo grafo do formulário — os itens ocultados pela lógica condicional são removidos da resposta.
A resposta a cada item interativo visível, no formato correspondente ao seu element_type.
Um único estado para a resposta como um todo.

Os elementos de esquema visual são reconfigurados em vez de respondidos: cada SECTION_HEADER torna-se um limite de secção (o seu título e descrição tornam-se o title/description da secção), enquanto HEADING, PARAGRAPH e SEPARATOR permanecem em items[] sem a chave answer para que o relatório mantenha a mesma estrutura visual que o utilizador viu.

Onde aparece

O relatório do questionário aparece como o array plural questionnaire_responses[] em GET /v3/session/{sessionId}/decision/, tanto para sessões de KYC como de KYB, sempre que uma funcionalidade de questionário tenha sido executada. O campo é null até que pelo menos uma instância de questionário tenha sido iniciada. Cada entrada inclui um node_id para que fluxos com múltiplas instâncias possam desambiguar qual o passo do grafo que a gerou.

GET /v3/session/{sessionId}/decision/
  ──▶ { "questionnaire_responses": [ { node_id, questionnaire_id, title, status, sections, … }, … ] }

Formato do item

Consulte Resposta ao questionário na referência de modelos de dados para o esquema canónico.

interface QuestionnaireResponse {
  questionnaire_id: string;          // UUID of the questionnaire version that was answered
  title: string;                     // Questionnaire name, as set in the Console
  description: string | null;
  languages: string[];               // Supported language codes
  default_language: string;          // Default language code
  is_active: boolean;
  is_simple_questionnaire: boolean;  // true = flat list, false = branching graph
  questionnaire_group_id: string;    // UUID shared by all versions of the same questionnaire
  version: number;                   // Version number within the group
  published_at: string | null;       // ISO 8601 — when this version was published
  status: "Approved" | "In Review" | "Not Finished";
  sections: Array<{
    title: string | null;            // From the SECTION_HEADER that opens the section
    description: string | null;
    items: QuestionnaireItem[];
  }>;
  node_id: string | null;            // Workflow graph node that ran this questionnaire
}

interface QuestionnaireItem {
  uuid: string;                      // Form element UUID
  value: string;                     // Stable node id of the element within the questionnaire graph
  element_type:
    | "SHORT_TEXT" | "LONG_TEXT"
    | "DROPDOWN" | "SINGLE_CHOICE" | "MULTIPLE_CHOICE"
    | "NUMBER" | "EMAIL" | "PHONE" | "ADDRESS" | "COUNTRY"
    | "DATE_PICKER" | "TIME"
    | "CONSENT"
    | "FILE_UPLOAD" | "IMAGE"
    | "REPEATABLE_GROUP"
    | "HEADING" | "PARAGRAPH" | "SEPARATOR";   // layout-only — no answer key
  is_required: boolean;
  title: string | null;              // Localized
  description: string | null;        // Localized help text, or null when none is set
  placeholder: string | null;        // Localized
  choices: Array<{                   // DROPDOWN / SINGLE_CHOICE / MULTIPLE_CHOICE
    label: string;                   // Localized
    value: string;                   // Stable across languages
    requires_text_input?: boolean;   // Selecting this option triggers a free-text follow-up
  }> | null;
  max_files: number | null;          // FILE_UPLOAD / IMAGE upload cap (1–5)
  required_if: {                     // Conditional requirement rule, or null
    rules: Array<{ field: string; operator: string; value?: unknown }>;
    logic: "and" | "or";
  } | null;
  repeatable_config: {               // REPEATABLE_GROUP only, or null
    min_items?: number;
    max_items?: number;
    item_label?: string;             // Localized
    fields: Array<object>;           // Sub-field definitions (value, element_type, title, …)
  } | null;
  answer?: Answer | null;            // Omitted on HEADING / PARAGRAPH / SEPARATOR; null when unanswered
}

Os elementos SECTION_HEADER nunca aparecem em items[] — abrem uma nova secção e fornecem o respetivo title e description.

Tipos de elementos

Tipo de elemento	Formato da resposta	Notas
`SHORT_TEXT`, `LONG_TEXT`	`{ value: string }`	Texto livre.
`EMAIL`, `DATE_PICKER`, `TIME`	`{ value: string }`	Variantes de texto tipificado.
`NUMBER`	`{ value: number }`	Número JSON — validado no servidor como numérico.
`COUNTRY`	`{ value: string }`	Código ISO 3166-1 alfa-3 (por exemplo, `"ESP"`), validado no servidor.
`PHONE`	`{ value: { countryCode, callingCode, number } }`	Objeto de telefone estruturado.
`ADDRESS`	`{ value: { street, streetExtraInfo, city, state, postalCode, country } }`	Objeto de morada estruturado.
`DROPDOWN`, `SINGLE_CHOICE`	`{ value: string, text?: string }`	`value` é o valor da opção; `text` é preenchido quando a opção selecionada tem `requires_text_input: true`.
`MULTIPLE_CHOICE`	`{ value: string[], text?: string }`	Array de valores das opções.
`CONSENT`	`{ value: boolean }`	Booleano JSON.
`FILE_UPLOAD`, `IMAGE`	`{ files: string[] }`	Cada entrada é um URL pré-assinado.
`REPEATABLE_GROUP`	`{ items: Array<{ [fieldValue]: Answer }> }`	Um objeto por repetição, indexado pelo `value` de cada subcampo com o seu próprio objeto de resposta.
`HEADING`, `PARAGRAPH`, `SEPARATOR`	(sem chave `answer`)	Apenas elementos de apresentação — mantidos em `items[]` para que o relatório preserve a mesma estrutura visual que o utilizador viu.

Um item interativo visível que o utilizador nunca tenha respondido é retornado com "answer": null.

Visibilidade condicional

Quando um questionário define um grafo (lógica condicional), são incluídos apenas os itens no percurso que o utilizador efetivamente seguiu. Um item ocultado por uma ramificação que o utilizador não seguiu não aparece em sections[].items — mesmo que exista no modelo. As secções que fiquem sem qualquer item visível são removidas por completo.

Valores de estado

O status ao nível da resposta é um de três valores. Internamente, o estado base (Approved, ou In Review quando o fluxo força a revisão manual) é combinado com quaisquer regras de estado personalizadas correspondentes usando a precedência global da plataforma Declined > In Review > Approved; um resultado Declined ao nível do questionário é depois mapeado para In Review para que os operadores façam a avaliação final durante a revisão.

Estado	Significado
`Not Finished`	O utilizador ainda não submeteu o questionário.
`In Review`	Submetido e a aguardar revisão manual (o fluxo força a revisão manual ou uma regra de estado escalou a resposta).
`Approved`	Submetido e aceite.

Avisos

Os questionários emitem um único código de aviso, gerado quando uma regra de estado personalizada configurada no nó do questionário corresponde a uma resposta:

Etiqueta	Descrição
`CUSTOM_STATUS_RULE_TRIGGERED`	Uma regra de estado do fluxo avaliou uma resposta do questionário e alterou (ou confirmou) o estado da funcionalidade.

O additional_data do aviso inclui field, operator, rule_value, actual_value, target_status e score quando a regra o define. O seu log_type segue o estado-alvo da regra: error para Declined, warning para In Review e information nos restantes casos. Ao contrário de outras funcionalidades, a entrada do questionário não inclui um array warnings[] — os registos de regras acionadas são guardados na sessão sob feature: "QUESTIONNAIRE" e surgem no ecrã de revisão da Consola (consulte também a lista de avisos da Verificação de empresas (KYB); o mesmo código aplica-se a sessões de KYC).

Exemplo — Questionário de origem dos fundos

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Approved",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Business Income", "value": "business_income" },
                { "label": "Savings", "value": "savings" },
                { "label": "Investments", "value": "investments" },
                { "label": "Inheritance/Gift", "value": "inheritance_gift" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "salary" }
            },
            {
              "uuid": "2d16b527-72be-42e0-8e96-b164b818386c",
              "value": "question_2",
              "element_type": "LONG_TEXT",
              "is_required": true,
              "title": "Provide details of the primary source.",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "Software engineer at Acme Ltd since 2018." }
            },
            {
              "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa",
              "value": "question_3",
              "element_type": "SINGLE_CHOICE",
              "is_required": true,
              "title": "Will any funds originate from third parties?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Yes", "value": "yes", "requires_text_input": true },
                { "label": "No", "value": "no" }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "yes", "text": "One-off gift from parents, EUR 8,000." }
            },
            {
              "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13",
              "value": "question_4",
              "element_type": "FILE_UPLOAD",
              "is_required": true,
              "title": "Upload a proof of funds document",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 3,
              "required_if": null,
              "repeatable_config": null,
              "answer": {
                "files": [
                  "https://<media-host>/.../payslip-jul.pdf",
                  "https://<media-host>/.../payslip-aug.pdf"
                ]
              }
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

Exemplo — Não concluído

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Not Finished",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": null
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

Quando o utilizador atinge o passo do questionário mas ainda não submeteu respostas, a resposta é devolvida com status: "Not Finished" e "answer": null em cada item visível. Uma sessão que nunca tenha chegado a este passo não produz qualquer entrada — questionnaire_responses permanece null quando não existe qualquer instância.

Notas

Os URLs de ficheiros expiram. As entradas em answer.files são URLs pré-assinados (validade de 4 horas por predefinição). Volte a chamar o endpoint de decisão quando precisar de URLs novos.
Localização. Os campos de item title, description, placeholder, o label de opção e o title/description de secção são devolvidos em inglês quando o questionário o suporta; caso contrário, no default_language do questionário. O value de uma opção permanece estável entre idiomas para que possa basear a lógica de negócio nele em segurança.
A description do item é o texto de ajuda do elemento. Qualquer item pode conter uma, incluindo perguntas, sendo null quando nenhuma estiver definida. Um SEPARATOR nunca tem nenhuma.

Relacionados

Visão geral dos questionários

Como criar, versionar e associar questionários a um fluxo.

Modelos de dados — Resposta do questionário

Esquema canónico campo a campo para este objeto.

Obter sessão

Referência do endpoint para o payload de decisão V3.

Autenticação

Verificação

Monitorização

Plataforma

Relatório de questionários: esquema JSON de respostas

Visão geral

Onde aparece

Formato do item

Tipos de elementos

Visibilidade condicional

Valores de estado

Avisos

Exemplo — Questionário de origem dos fundos

Exemplo — Não concluído

Notas

Relacionados

Visão geral dos questionários

Modelos de dados — Resposta do questionário

Obter sessão

​Visão geral

​Onde aparece

​Formato do item

​Tipos de elementos

​Visibilidade condicional

​Valores de estado

​Avisos

​Exemplo — Questionário de origem dos fundos

​Exemplo — Não concluído

​Notas

​Relacionados

Visão geral dos questionários

Modelos de dados — Resposta do questionário

Obter sessão

Visão geral

Onde aparece

Formato do item

Tipos de elementos

Visibilidade condicional

Valores de estado

Avisos

Exemplo — Questionário de origem dos fundos

Exemplo — Não concluído

Notas

Relacionados