> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Questionários KYC: Formulários dinâmicos

> Crie questionários KYC na Didit com construtor drag-and-drop, lógica condicional e revisão manual. Multi-idioma. $0.10 por chamada.

Os Questionários da Didit permitem-lhe conceber formulários estruturados e dinâmicos para recolher informações adicionais dos utilizadores durante a verificação. Utilize o nosso construtor visual para arrastar e largar elementos, organizar conteúdo em secções, localizar texto para múltiplos idiomas e encaminhar resultados para revisão manual quando necessário.

Prompt de integração de Questionários
        Copiar o prompt para a área de transferência



      
      

\<pre>

\````# Goal
Integrate Didit Questionnaires (custom KYC/KYB forms with conditional logic and manual-review routing) into your app.

\# Delivery mode
Questionnaires are **session-only**. The form is designed in the Business Console (drag-and-drop builder) and bound to a workflow via the QUESTIONNAIRE feature. There is no standalone questionnaire submission API — answers are collected through the hosted Didit flow.

\# Steps
1\. Build the questionnaire in the Business Console (Questionnaires tab). Define sections, fields, conditional visibility, multi-language labels, and **custom status rules** (e.g. "if source_of_funds = 'crypto' set status to In Review").
2\. Add the QUESTIONNAIRE feature to a workflow and select the questionnaire id (POST /v3/workflows/ or the Console).
3\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
4\. Open session.url for the user (or mount the Web/Mobile SDK) — the form renders inside the flow.
5\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-1234",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `questionnaire_responses[]` on the decision payload (one entry per questionnaire node). Each entry includes:
\- `status` — final status for this questionnaire instance (driven by your custom status rules).
\- `answers` — array of { question_id, question_label, value } pairs (or nested sections).
\- `warnings` — any rule-triggered warnings.

\# Status enum (per questionnaire_responses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.QUESTIONNAIRE)
The dominant risk code is CUSTOM_STATUS_RULE_TRIGGERED — emitted whenever an answer matches a Console-configured rule that escalates the status. The warning's `additional_data` carries the rule id and matched answer so reviewers can see why the session was routed.

Full catalogue: questionnaire warnings are documented inside the report page — see /core-technology/questionnaires/report-questionnaire.

\# Failure modes to handle
\- questionnaire_responses[] empty — user abandoned the form. The session status will reflect "Abandoned"; treat per your retention policy.
\- status="In Review" with CUSTOM_STATUS_RULE_TRIGGERED — answers crossed your manual-review rule; surface the relevant answers in your reviewer UI.
\- status="Declined" — answers crossed a decline rule (e.g. user declared they are a sanctioned-country resident); do not approve.

\# See also
\- Canonical schema: /reference/data-models#questionnaire-response
\- Per-feature report: /core-technology/questionnaires/report-questionnaire
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Colar em

Na aula da Academy sobre a leitura de um resultado de verificação, o capítulo aos 11:54 aborda o Document AI e os questionários.[Document AI e questionários — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## Duas formas de criar questionáriosO Didit oferece **duas abordagens distintas** para criar questionários, permitindo-lhe escolher o nível de complexidade adequado às suas necessidades:![Modos de criação simples e avançado de questionários KYC do Didit lado a lado](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple-and-complex.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=71d18d67b4684cca46c7809ba43cfcb6)### 1. Modo Simples: Criador Rápido de FormuláriosO **Modo Simples** é perfeito para criar formulários diretos e simples rapidamente. Utilize a nossa interface intuitiva de arrastar e largar para adicionar elementos, definir campos obrigatórios e publicar em minutos.![Interface do criador de formulários por arrastar e largar do modo simples de questionários do Didit](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=8e777d8fc72ca16e8e2deb65a0a66e92)**Ideal para:**- Formulários rápidos de recolha de dados
- Inquéritos simples e atestações
- Equipas sem experiência na criação de formulários
- Questionários num único idioma**Como funciona:**1) Abra o Criador de Questionários
2) Arraste elementos da paleta para o seu formulário
3) Configure cada elemento (etiqueta, obrigatório, marcador de posição)
4) Pré-visualize e publique***### 2. Modo Avançado: Criador Visual de GrafosO **Modo Avançado** desbloqueia funcionalidades poderosas para cenários complexos de recolha de dados através de um **editor visual baseado em nós**. Crie questionários sofisticados com lógica condicional, caminhos de ramificação e controlo total sobre o fluxo.![Editor visual de grafos baseado em nós para questionários avançados do Didit com lógica de ramificação](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-node-based.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=7ff0c1d79f500ed3f78dca4ff89b0698)**Ideal para:**- Questionários em múltiplos idiomas
- Formulários complexos com ramificação condicional
- Recolha de dados orientada pela conformidade com diferentes caminhos
- Formulários que exigem fluxos de revisão manual**Principais capacidades:**- **Editor visual de nós**: arraste, largue e ligue nós numa área de trabalho infinita
- **Ligações inteligentes**: arraste a partir do ponto de ligação de um nó para um espaço vazio para criar e ligar instantaneamente um novo nó
- **Ramificação condicional**: encaminhe os utilizadores para diferentes perguntas com base nas respostas anteriores e, em seguida, [reúna os caminhos num passo partilhado](#reunir-caminhos-de-ramificação-num-passo-partilhado)
- **Suporte a múltiplos idiomas**: traduza todo o conteúdo apresentado aos utilizadores
- **Atalhos de teclado**: Anular (Ctrl/Cmd+Z), Refazer (Ctrl/Cmd+Shift+Z), Eliminar (Delete/Backspace)
- **Zoom e deslocamento**: navegue por formulários complexos utilizando o deslocamento para ampliar e arrastando para deslocar#### Tipos de nós do criador de grafos| Tipo de nó | Cor | Descrição | Quando utilizar |
| - | - | - | - |
| **Nós de Pergunta** | Azul | Elementos de entrada que recolhem dados do utilizador | Campos de texto, menus suspensos, carregamentos de ficheiros, datas, etc. |
| **Nós de Texto** | Verde | Conteúdo só de leitura apresentado aos utilizadores | Instruções, explicações, texto legal |
| **Nós de Ramificação** | Laranja | Encaminhamento condicional com base nas respostas | "Se o país for US, mostrar formulário fiscal" |
| **Nós de Secção** | Cinzento | Agrupamento visual de elementos relacionados | Organizar perguntas em secções lógicas |> **Regras de ligação:** Os nós de Secção e de Texto podem ligar-se a nós de Pergunta e a outros nós de Texto, mas não diretamente a nós de Ramificação. Os nós de Ramificação podem ligar-se a qualquer tipo de nó.#### Operadores de condiçãoUma condição de ramificação compara uma resposta anterior com um valor.
Combine várias condições com `and` ou `or`.| Operador | Corresponde quando a resposta |
| - | - |
| `equals` | É igual ao valor |
| `not_equals` | Não é igual ao valor |
| `contains` | Contém o valor |
| `greater_than` | É superior ao valor |
| `greater_than_or_equals` | É superior ou igual ao valor |
| `less_than` | É inferior ao valor |
| `less_than_or_equals` | É inferior ou igual ao valor |
| `in` | É um de uma lista de valores |
| `not_in` | Não é nenhum de uma lista de valores |
| `is_empty` | Foi deixada em branco |
| `is_not_empty` | Foi preenchida |#### Reunir caminhos de ramificação num passo partilhadoA ramificação não tem de ser unidirecional. O fim de vários caminhos pode ligar-se ao mesmo nó a jusante, e o questionário continua a partir daí uma única vez. As perguntas partilhadas são criadas e mantidas num único local, em vez de serem repetidas no final de cada caminho.**Exemplo prático: perguntas adicionais no Sim, seguidas de uma parte final partilhada**1) Adicione um **nó de Pergunta** com uma pergunta de **Escolha Única** com as opções Sim e Não e, em seguida, um **nó de Ramificação** a seguir com um caminho `Yes` e um caminho `No`.
2) No caminho `Yes`, adicione as perguntas adicionais que apenas se aplicam quando a resposta for Sim.
3) No final desse caminho, adicione a primeira pergunta que todos os inquiridos têm de responder após a ramificação — o início da parte final partilhada.
4) Aponte o caminho `No` para essa pergunta: abra o menu **+** no final do caminho `No` e selecione **Ligar a um passo existente**, ou arraste a partir do conector do caminho `No` e solte na extremidade superior da pergunta partilhada. A área de trabalho liga-se apenas ao pequeno alvo na parte superior do cartão, pelo que soltar no meio do cartão não tem qualquer efeito.
5) Continue a adicionar as restantes perguntas partilhadas após a primeira e, em seguida, publique. A área de trabalho apresenta a parte final partilhada uma única vez, abaixo dos caminhos que conduzem a ela.Um caminho pode juntar-se a um nó que já existe desta forma, e vários caminhos podem apontar para o mesmo nó. A junção define onde esse caminho continua, pelo que o menu **+** oferece a opção **Ligar a um passo existente** enquanto o caminho termina aí. Uma ligação que fecharia um ciclo de volta para um nó anterior é recusada.Os inquiridos respondem às perguntas partilhadas uma única vez, qualquer que tenha sido o caminho percorrido; as perguntas do caminho que não seguiram são ignoradas. O payload de decisão segue a mesma regra: `questionnaire_responses[].sections[].items` lista apenas os itens no caminho que o inquirido seguiu. Consulte [Visibilidade condicional](https://docs.didit.me/pt/core-technology/questionnaires/report-questionnaire.md#visibilidade-condicional).***## Modelos de questionárioOs modelos ajudam-no a começar rapidamente com formulários pré-configurados para casos de utilização comuns. Pode utilizá-los tal como estão ou personalizá-los para se adaptarem às suas necessidades.![Modelos pré-construídos de questionários da Didit para origem dos fundos e conformidade de KYC](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=97a45bd55692379ffc057e11f4530a54)### Modelos pré-construídos| Modelo | Descrição | Elementos típicos |
| - | - | - |
| **Origem dos fundos** | Registar origens de rendimento e documentação de suporte | Menu suspenso, Texto longo, Envio de ficheiros |
| **Detalhes de emprego** | Recolher cargo, empregador, intervalo de rendimentos | Texto curto, Menu suspenso, Número |
| **Propósito da conta** | Compreender a utilização prevista da conta | Escolha única, Escolha múltipla, Texto longo |
| **Propriedade efetiva** | Identificar UBOs e estrutura de propriedade | Texto curto, Número, Envio de ficheiros |
| **Residência fiscal** | Recolher declarações de âmbito fiscal | País, Consentimento, Envio de ficheiros |
| **Avaliação de risco** | Reunir informação relevante para o risco | Escolha múltipla, Menu suspenso, Texto longo |***## Como funcionaO nosso fluxo de questionários foi concebido para oferecer flexibilidade e auditabilidade:### 1. Construir na Consola (sem código)- Arraste e largue elementos para criar o seu questionário
- Organize o conteúdo em várias secções para maior clareza
- Marque elementos como obrigatórios ou opcionais
- Configure marcadores de posição e descrições de ajuda
- Adicione opções (com texto livre complementar opcional) para menus suspensos e escolha única
- Configure limites de envio de ficheiros/imagens por elemento### 2. Localizar conteúdo- Escreva o seu conteúdo uma única vez no `default_language` do questionário
- Defina os `languages` suportados — ao publicar, cada título, descrição, marcador de posição, etiqueta de opção e mensagem de validação é **traduzido automaticamente** para todos eles
- Ajuste manualmente qualquer tradução no construtor; as edições manuais são preservadas até que o texto de origem seja alterado
- O utilizador final visualiza o conteúdo automaticamente no melhor idioma disponível### 3. Publicar e recolher- Ative o questionário e incorpore-o no seu fluxo de verificação
- Os utilizadores finais preenchem as secções e submetem as respostas
- Os envios de ficheiros (documentos, imagens) são armazenados e associados à resposta### 4. Rever e decidir* As respostas são guardadas com um `status`: `Approved`, `In Review` ou `Not Finished`
* Pode forçar todas as respostas do questionário a irem para `In Review`, para que uma pessoa as aprove manualmente
* Reveja as respostas e os ficheiros na consola e, em seguida, marque como `Approved`> Nota: Os questionários não geram avisos de risco. A governação é assegurada através de campos obrigatórios, validação e fluxos de revisão.***## Principais capacidades| Capacidade | Modo simples | Modo avançado |
| - | - | - |
| Construtor de arrastar e largar | ✅ | ✅ |
| Campos obrigatórios/opcionais | ✅ | ✅ |
| Marcadores de posição e descrições | ✅ | ✅ |
| Várias secções | ✅ | ✅ |
| Limites de envio de ficheiros | ✅ | ✅ |
| Editor visual de grafos | ❌ | ✅ |
| Ramificação condicional | ❌ | ✅ |
| Traduções em múltiplos idiomas | ❌ | ✅ |
| Lógica de escolha (exigir texto) | ❌ | ✅ |
| Forçar revisão manual | ❌ | ✅ |
| Suporte para Desfazer/refazer | ❌ | ✅ |
| Atalhos de teclado | ❌ | ✅ |**Lista completa de funcionalidades:**- **Construtor visual**: Crie e faça a gestão de questionários com um editor intuitivo de arrastar e largar
- **Secções**: Agrupe perguntas relacionadas; adicione cabeçalhos e separadores para orientar os utilizadores
- **Traduções automáticas**: Escreva o conteúdo num idioma — todo o texto visível ao utilizador é traduzido para todos os outros idiomas selecionados aquando da publicação, permitindo ajustes manuais
- **Validação**: Marque campos como obrigatórios; imponha um número máximo de ficheiros por elemento de envio
- **Lógica de escolha**: Para menus suspensos/escolha única, exija opcionalmente texto adicional consoante a opção selecionada
- **Envios**: Recolha documentos e imagens com limites no número de ficheiros (por exemplo, até 3 ficheiros)
- **Revisão manual**: Opcionalmente, force todas as respostas para `In Review`, aguardando aprovação humana
- **Comutador de ativação**: Ative ou desative o questionário por aplicação
- **Integração no fluxo**: Adicione questionários a fluxos de KYC ou execute-os de forma autónoma através de um fluxo de Verificação de questionários
- **APIs e Webhooks**: Leia resultados estruturados através da API e receba atualizações***## Tipos de elementosPode adicionar os seguintes tipos de elementos no construtor (selecionáveis a partir da consola):### Elementos de introdução de dados| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **SHORT\_TEXT** | Texto livre de linha única | Placeholder, obrigatório |
| **LONG\_TEXT** | Texto livre de várias linhas | Placeholder, obrigatório |
| **NUMBER** | Entrada numérica | Placeholder, obrigatório |
| **EMAIL** | Entrada de e-mail com validação | Placeholder, obrigatório |
| **PHONE** | Entrada de número de telefone | Placeholder, obrigatório |
| **ADDRESS** | Entrada de morada | Placeholder, obrigatório |
| **DATE\_PICKER** | Seleção de data | Placeholder, obrigatório |
| **TIME** | Entrada de hora | Placeholder, obrigatório |### Elementos de escolha| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **DROPDOWN** | Seleção única a partir de uma lista | Escolhas, `requires_text_input` por escolha |
| **SINGLE\_CHOICE** | Seleção única tipo botão de rádio | Escolhas, `requires_text_input` por escolha |
| **MULTIPLE\_CHOICE** | Lista de verificação de seleção múltipla | Escolhas |
| **COUNTRY** | Seletor de país | Obrigatório |
| **CONSENT** | Caixa de seleção ou tomada de conhecimento | Obrigatório, etiqueta personalizada |### Elementos de carregamento| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **IMAGE** | Carregamento de imagem | `max_files` (1-5), obrigatório |
| **FILE\_UPLOAD** | Carregamento de documento | `max_files` (1-5), obrigatório |### Elementos de estrutura| Elemento | Descrição | Notas |
| - | - | - |
| **PARAGRAPH** | Texto explicativo só de leitura | Não permite resposta |
| **SECTION\_HEADER** | Cabeçalho de secção visual | Não permite resposta, não obrigatório |
| **SEPARATOR** | Divisor visual | Não permite resposta, não obrigatório |**Notas de comportamento:**- `SECTION_HEADER` e `SEPARATOR` destinam-se apenas à apresentação. Ignoram as definições de obrigatório, placeholder e escolhas, bem como os limites de ficheiros.
- Para elementos de escolha, defina as opções como `{ label, value, requires_text_input? }`.
- Para elementos de carregamento, defina `max_files` (1–5) para controlar quantos ficheiros podem ser anexados.***## Forçar revisão manualAlguns fluxos de conformidade exigem a revisão humana de cada resposta. A partir da consola, pode configurar os questionários para resultarem sempre em `In Review`. Em seguida, um revisor aprova ou solicita alterações, após o que a resposta passa a `Approved`.**Quando utilizar a revisão manual:**- Onboarding de clientes de alto risco
- Recolha de dados sensíveis (origem dos fundos, declarações de beneficiários efetivos)
- Requisitos regulamentares de supervisão humana
- Garantia de qualidade durante a implementação inicial***## Exemplos de casos de utilização### Origem dos fundosRegiste origens de rendimento, montantes e carregue documentos comprovativos (por exemplo, recibos de vencimento, extratos). Combine listas pendentes, texto longo e carregamentos de ficheiros.**Estrutura típica:**- Secção 1: Situação profissional (Lista pendente)
- Secção 2: Origens de rendimento (Escolha múltipla + Texto longo)
- Secção 3: Documentos comprovativos (Carregamento de ficheiro)
- Secção 4: Declaração (Consentimento)***### Associação ou adesãoRegiste filiações, funções e comprovativos de associação; inclua elementos de consentimento para declarações.**Estrutura típica:**- Nome da organização (Texto curto)
- Função/Cargo (Lista pendente)
- Duração da adesão (Seletor de data)
- Comprovativo de adesão (Carregamento de ficheiro)
- Declaração (Consentimento)***### Objetivo da relação e atividade de conta previstaRecolha a finalidade, volumes de transação previstos, países de atividade e contrapartes antecipadas. Utilize seleção única/múltipla, entradas numéricas e parágrafos para contexto.**Estrutura típica:**- Secção 1: Finalidade da conta (Escolha múltipla)
- Secção 2: Volume mensal previsto (Número + Lista pendente para a moeda)
- Secção 3: Países de atividade (País - múltipla seleção)
- Secção 4: Tipos de transação (Escolha múltipla)
- Secção 5: Informações adicionais (Texto longo)***## Modo Simple vs Modo Advanced: quando utilizar cada um| Cenário | Modo recomendado |
| - | - |
| Formulário básico num único idioma | Simple |
| Necessidade de suporte a vários idiomas | Advanced |
| Inquérito interno rápido | Simple |
| Questionário de conformidade | Advanced |
| Recolha de dados pontual | Simple |
| Caminhos de ramificação condicional | Advanced |
| Forçar revisão manual | Advanced |
| Formulários complexos com várias secções | Advanced |***## Como começar1. **É a primeira vez que utiliza questionários?** Comece com o **Simple Mode** para conhecer o construtor
2. **Precisa de traduções ou de lógica condicional?** Mude para o **Advanced Mode** para utilizar o editor visual de grafos> Veja como os resultados são estruturados na página do [relatório de questionários](https://docs.didit.me/pt/core-technology/questionnaires/report-questionnaire.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.