Coletar respostas de formulários e levar ao BI

Pesquisa de satisfação de clientes, inscrição em evento, checklist de visita, NPS pós-treinamento: Pesquisas → Formulários monta formulários com seções, 21 tipos de pergunta e lógica condicional, distribuídos por link público (qualquer pessoa, sem login) ou por convite a colaboradores. A integração típica cria o formulário a partir de um modelo do seu sistema, publica o link no seu site ou e-mail marketing e traz as respostas para o BI.


Quando usar	Pesquisas recorrentes geradas por outro sistema, respostas que precisam ir para o BI ou para um CRM, consolidado de NPS
Porta	REST · Página pública · Agente (MCP)
Você vai precisar	Módulo `PESQUISAS`; permissão `PESQUISA` (com nível de edição para criar e publicar; leitura basta para respostas e exportação); token JWT de um usuário de integração

Como funciona

seu sistema ── POST /pesquisa → /secao-pesquisa → /pergunta-pesquisa ─▶ TAI  (rascunho)
seu sistema ── POST /pesquisa/{id}/publicar ─────────────────────────▶ TAI  (linkPublico)
respondentes ── link público  ou  convite por e-mail ─────────────────▶ TAI
seu BI ── GET /pesquisa/{id}/respostas?status=CONCLUIDA ──────────────▶ TAI  (respostas)
seu BI ── GET /pesquisa/{id}/analytics  ·  /pesquisa/{id}/exportar ───▶ TAI  (consolidado, xlsx)

Passo a passo

Crie o formulário. Ele nasce em RASCUNHO.

POST /pesquisa
Authorization: Bearer $TAI_TOKEN
Content-Type: application/json

{
  "titulo": "Satisfação pós-atendimento",
  "descricao": "Leva menos de um minuto.",
  "permitirAcessoPublico": true,
  "modoIdentificacao": "ANONIMA",
  "dataFim": "2026-12-31",
  "mensagemConclusao": "Obrigado!",
  "redirectUrl": "https://www.suaempresa.com.br/obrigado"
}

modoIdentificacao é ANONIMA (padrão) ou IDENTIFICADA; requerIdentificacao: true pede nome e e-mail no link e torna a resposta identificada. Outros campos úteis: dataInicio, limiteRespostas, lembreteDias (1 a 30), corPrimaria e corFundo (#RRGGBB), logoUrl.

Crie uma seção e as perguntas. Perguntas de escolha levam as opções no mesmo corpo.

POST /secao-pesquisa

{ "pesquisaId": 52, "titulo": "Sua experiência", "ordem": 0 }

POST /pergunta-pesquisa

{
  "secaoId": 88,
  "textoPergunta": "De 0 a 10, quanto você recomendaria nosso atendimento?",
  "tipo": "NPS",
  "obrigatoria": true,
  "ordem": 0
}

POST /pergunta-pesquisa

{
  "secaoId": 88,
  "textoPergunta": "Por qual canal você foi atendido?",
  "tipo": "MULTIPLA_ESCOLHA",
  "obrigatoria": true,
  "ordem": 1,
  "opcoes": [ { "texto": "Telefone" }, { "texto": "WhatsApp" }, { "texto": "E-mail" } ]
}

Os tipos aceitos estão em tipo na referência: TEXTO_CURTO, TEXTO_LONGO, MULTIPLA_ESCOLHA, CAIXAS_SELECAO, DROPDOWN, ESCALA_LINEAR, NPS, DATA, NUMERO, ARQUIVO, SIM_NAO, MATRIZ e outros. A lógica condicional fica em /logica-condicional.

Publique.
```
POST /pesquisa/52/publicar
```
A publicação confere a estrutura: precisa haver ao menos uma pergunta para responder, e cada pergunta de escolha precisa de ao menos duas opções — senão 400 com a lista do que falta. A resposta traz linkPublico (quando permitirAcessoPublico é true): é o endereço para pôr no seu site, no e-mail ou num QR code.
Ou convide colaboradores. Cada um recebe um link pessoal por e-mail e vê a pesquisa em Minhas pesquisas.
```
POST /pesquisa-convite/52/convidar

{ "publicoTipo": "DEPARTAMENTO", "publicoId": 40 }
```
Ou {"colaboradorIds": [1043, 1051]}. Quem já foi convidado é pulado, então repetir a chamada não duplica convites. A adesão fica em GET /pesquisa-convite/52/adesao.
Traga as respostas. Só as concluídas, as mais recentes primeiro:
```
GET /pesquisa/52/respostas?status=CONCLUIDA&sort=dataConclusao,desc&page=0&size=50
```
Cada item traz id, status, canal (LINK, CONVITE, APP), dataConclusao e, no modo identificado, nome, email ou colaboradorId. O valor de cada pergunta vem em GET /pesquisa/52/respostas/{respostaId}, na lista respostas, cada item com perguntaId e o valor no campo do tipo (valorTexto, valorNumero, opcaoSelecionadaId, opcoesSelecionadasIds…). Arquivos enviados se baixam em GET /pesquisa/52/respostas/{respostaId}/arquivo/{perguntaId}.

Ou leve o consolidado.

Rota	Traz
`GET /pesquisa/52/analytics`	Totais, taxa de conclusão, tempo médio, NPS (promotores, neutros, detratores) e a distribuição de cada pergunta
`GET /pesquisa/52/exportar`	Planilha `.xlsx` com uma linha por resposta concluída e o resumo
`GET /pesquisa/52/completo`	A estrutura inteira — seções, perguntas, opções e regras — para traduzir ids em textos

Para responder pela sua própria interface em vez do link pronto — um app, um totem —, use as rotas públicas descritas em Formulários públicos.

Automatize

Rotina	O que faz	Começa ligada?
Ciclo das pesquisas (`pesquisa-ciclo`)	A cada 15 minutos, encerra o formulário cuja `dataFim` passou (convites pendentes expiram); sessões de resposta sem atividade há 48 horas viram `ABANDONADA`	Sim
Lembrete das pesquisas (`pesquisa-lembrete`)	Todo dia, lembra os convidados que ainda não responderam, a cada `lembreteDias` dias	Sim

Lembrete avulso: POST /pesquisa-convite/{pesquisaId}/enviar-lembretes.

O formulário publica eventos no início e no fim: Uma pesquisa é publicada (PESQUISA_PUBLICADA) e Uma pesquisa é encerrada (PESQUISA_ENCERRADA) — este também quando a rotina encerra pela dataFim. Assine o encerramento num webhook para o BI fazer a carga final na hora certa:

{
  "id": "evt_64230",
  "tipo": "PESQUISA_ENCERRADA",
  "descricao": "Uma pesquisa é encerrada",
  "versao": 1,
  "ocorridoEm": "2027-01-01T03:15:02.118Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "pesquisaId": 52,
    "titulo": "Satisfação pós-atendimento",
    "tipo": "GENERICA",
    "totalRespostas": 238
  }
}

Uma resposta concluída não publica evento — o formulário pode ser anônimo. Para levar respostas a outro sistema logo que chegam, consulte a lista periodicamente e pare quando encontrar um id que já conhece.

Pelo seu agente de IA

“Monte um formulário de inscrição para o workshop de 20/11 com nome, área e restrição alimentar, publique e me passe o link.”

Com escopo de escrita, o agente cria o formulário, as perguntas com as opções e publica — o seu cliente de IA pede aprovação a cada passo. Somente leitura, ele resume resultados e NPS e gera a planilha. Veja Escrita e segurança.

Cuidados

Anônimo é anônimo. No modo ANONIMA, a resposta não guarda colaborador, nome, e-mail nem IP, e a lista nominal de convidados não existe (GET /pesquisa-convite/{id} recusa); a adesão vem só em contagens. O modo não muda depois que chegam respostas.
Estrutura trava com respostas. Um formulário que já recebeu respostas recusa mudanças que alterariam o que foi respondido. Para uma versão nova, use POST /pesquisa/{id}/duplicar.
Opções por id. Respostas de escolha guardam o id da opção; traduza com GET /pesquisa/{id}/completo e não recrie opções de um formulário publicado.
Analytics e exportação contam só respostas concluídas.
Estados: RASCUNHO → PUBLICADA ⇄ PAUSADA → ENCERRADA → ARQUIVADA. Só rascunho ou arquivado pode ser excluído.
Corpos acima de 8 KB são barrados pelo firewall: crie as perguntas uma a uma — veja Limites.

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade