Relatório de questionário: schema JSON das respostas

O relatório de questionário contém o formulário estruturado exibido ao usuário, o caminho que ele percorreu pelas ramificações condicionais e a resposta de cada item visível. Ele é retornado por nó, então workflows com várias instâncias (por exemplo, um questionário por UBO) trazem uma entrada para cada ocorrência.

Relatório de questionário de KYC da Didit mostrando respostas estruturadas, seções e tipos de elementos

Visão geral

Cada resposta de questionário descreve:

A versão do questionário que o usuário viu (título, descrição, idiomas, metadados da versão, seções).
Os itens visíveis do caminho que o usuário de fato percorreu pelo grafo do formulário: os itens ocultados pela lógica condicional são removidos da resposta.
A resposta de cada item interativo visível, no formato correspondente ao seu element_type.
Um único status para a resposta como um todo.

Os elementos de layout são reestruturados em vez de respondidos: cada SECTION_HEADER se torna uma divisão de seção (seu título e sua descrição passam a ser o title/description da seçã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 usuário viu.

Onde aparece

O relatório de questionário aparece como o array questionnaire_responses[], que contém várias respostas em GET /v3/session/{sessionId}/decision/, tanto em sessões de KYC quanto de KYB, sempre que um recurso de questionário for executado. O campo é null até que pelo menos uma instância de questionário tenha sido iniciada. Cada entrada traz um node_id, para que fluxos com várias instâncias possam identificar qual etapa do grafo a gerou.

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

Formato do item

Consulte Resposta de questionário na referência de modelos de dados para ver 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[]: eles abrem uma nova seção e fornecem seu title e sua description.

Tipos de elementos

Tipo de elemento	Formato da resposta	Observações
`SHORT_TEXT`, `LONG_TEXT`	`{ value: string }`	Texto livre.
`EMAIL`, `DATE_PICKER`, `TIME`	`{ value: string }`	Variantes de texto com formato específico.
`NUMBER`	`{ value: number }`	Número JSON, validado como numérico no servidor.
`COUNTRY`	`{ value: string }`	Código ISO 3166-1 alpha-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 endereço estruturado.
`DROPDOWN`, `SINGLE_CHOICE`	`{ value: string, text?: string }`	`value` é o valor da opção; `text` é preenchido quando a opção escolhida 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 é uma URL pré-assinada.
`REPEATABLE_GROUP`	`{ items: Array<{ [fieldValue]: Answer }> }`	Um objeto por repetição, indexado pelo `value` de cada subcampo, com seu próprio objeto de resposta.
`HEADING`, `PARAGRAPH`, `SEPARATOR`	(sem a chave `answer`)	Apenas layout: mantidos em `items[]` para preservar a estrutura.

Um item interativo visível ao qual o usuário nunca respondeu é retornado com "answer": null.

Visibilidade condicional

Quando um questionário define um grafo (lógica condicional), somente os itens do caminho que o usuário de fato percorreu são incluídos. Um item ocultado por uma ramificação que o usuário não seguiu não aparece em sections[].items, mesmo que exista no modelo. As seções que ficam sem itens visíveis são removidas por completo.

Valores de status

O status no nível da resposta assume um de três valores. Internamente, o status base (Approved, ou In Review quando o fluxo exige revisão manual) é combinado com as regras de status personalizadas que se aplicarem, usando a precedência aplicada a toda a plataforma Declined > In Review > Approved; em seguida, um resultado Declined no nível do questionário é convertido em In Review, para que os operadores definam a decisão final durante a revisão.

Status	Significado
`Not Finished`	O usuário ainda não enviou o questionário.
`In Review`	Enviado e aguardando revisão manual (o fluxo exige revisão manual ou uma regra de status escalou a resposta).
`Approved`	Enviado e aceito.

Avisos

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

Tag	Descrição
`CUSTOM_STATUS_RULE_TRIGGERED`	Uma regra de status do fluxo avaliou uma resposta do questionário e alterou (ou confirmou) o status do recurso.

O additional_data do aviso traz field, operator, rule_value, actual_value, target_status e score, quando a regra define uma pontuação. O log_type acompanha o status de destino da regra: error para Declined, warning para In Review e information nos demais casos. Diferentemente de outros recursos, a entrada do questionário não inclui um array warnings[]: os registros das regras acionadas ficam gravados na sessão em feature: "QUESTIONNAIRE" e aparecem na tela de revisão do Console (veja também a lista de avisos da Verificação de empresas; o mesmo código se aplica a sessões de KYC).

Exemplo: questionário de origem dos recursos

{
  "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 finalizado

{
  "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 usuário chegou à etapa do questionário, mas ainda não enviou as respostas, a resposta é retornada com status: "Not Finished" e "answer": null em todos os itens visíveis. Uma sessão que nunca chegou à etapa não gera nenhuma entrada: questionnaire_responses permanece null quando não há nenhuma instância.

Observações

As URLs de arquivos expiram. As entradas em answer.files são URLs pré-assinadas (validade de 4 horas por padrão). Consulte novamente o endpoint de decisão quando precisar de URLs atualizadas.
Localização. Os campos title, description e placeholder do item, o label das opções e os campos title/description da seção são retornados em inglês quando o questionário oferece suporte a esse idioma; caso contrário, no default_language do questionário. O value de uma opção permanece estável entre idiomas, então você pode basear sua lógica de negócio nele com segurança.
A description do item é o texto de ajuda do elemento. Qualquer item pode ter uma, inclusive as perguntas, e ela é null quando nenhuma é definida. Um SEPARATOR nunca tem uma.

Relacionados

Visão geral dos questionários

Como criar, versionar e vincular questionários a um fluxo de verificação (workflow).

Modelos de dados — Resposta do questionário

Esquema canônico, campo a campo, deste objeto.

Recuperar sessão

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

Autenticação

Verificação

Monitoramento

Plataforma

Relatório de questionário: schema JSON das respostas

Visão geral

Onde aparece

Formato do item

Tipos de elementos

Visibilidade condicional

Valores de status

Avisos

Exemplo: questionário de origem dos recursos

Exemplo: não finalizado

Observações

Relacionados

Visão geral dos questionários

Modelos de dados — Resposta do questionário

Recuperar sessão

​Visão geral

​Onde aparece

​Formato do item

​Tipos de elementos

​Visibilidade condicional

​Valores de status

​Avisos

​Exemplo: questionário de origem dos recursos

​Exemplo: não finalizado

​Observações

​Relacionados

Visão geral dos questionários

Modelos de dados — Resposta do questionário

Recuperar sessão

Visão geral

Onde aparece

Formato do item

Tipos de elementos

Visibilidade condicional

Valores de status

Avisos

Exemplo: questionário de origem dos recursos

Exemplo: não finalizado

Observações

Relacionados