Formulários públicos

Processos (BPM) e Pesquisas publicam formulários por link com token, respondidos sem login. A plataforma já oferece a página pronta; as rotas abaixo servem para quem quer embutir o formulário na própria interface — um app, um totem, um portal.

Quando usar	Pessoas de fora (clientes, fornecedores, candidatos) abrem pedidos ou completam etapas sem usuário na TAI
Porta	Página pública · rotas públicas com token
Você vai precisar	módulo GESTAO_PROCESSOS; o formulário habilitado e público na configuração do fluxo (aba Formulário Público); o token do link

Como funciona

seu app ──► GET  /public/bpm/form/{token}                       (estrutura: campos e regras)
        ──► POST /public/bpm/ged/upload/{token}/{fieldSchemaId} (arquivos → tempUrl)
        ──► POST /public/bpm/form/{token}/submit                (cria o card na 1ª fase)
TAI     ──► automações de "Solicitação Criada" do fluxo (e-mail, webhook…)

Formulário de entrada de um processo

Cada fluxo pode ter um formulário público de abertura. Cada envio cria um card na primeira fase do fluxo. O token é o do Link Público gerado na aba Formulário Público da configuração do fluxo; Regenerar Token invalida o link anterior.

Rota	O que faz
GET /public/bpm/form/{token}	Estrutura do formulário: título, campos e regras
GET /public/bpm/form/{token}/status	Se o formulário está aberto (prazo e limite de envios)
GET /public/bpm/form/{token}/centros-custo	Opções para um campo do tipo centro de custo
POST /public/bpm/ged/upload/{token}/{fieldSchemaId}	Envia um arquivo de um campo (multipart, parte arquivo); devolve tempUrl
POST /public/bpm/form/{token}/submit	Envia as respostas

Corpo do envio:

{
  "nomeSolicitante": "Fernanda Alves",
  "emailSolicitante": "fernanda@cliente.com.br",
  "fieldValues": [
    { "fieldSchemaId": 501, "valorTexto": "Troca de equipamento" },
    { "fieldSchemaId": 502, "valorNumero": 3 },
    { "fieldSchemaId": 503, "valorData": "2026-10-20" },
    { "fieldSchemaId": 504, "valorArquivoTempUrl": "…", "valorArquivoNome": "orcamento.pdf" }
  ]
}

Cada campo usa o valor do seu tipo: valorTexto, valorNumero, valorData, valorBoolean, valorJson (listas e seleções múltiplas) ou valorArquivoTempUrl. Os fieldSchemaId vêm da estrutura devolvida pelo GET.

Resposta de sucesso:

{ "sucesso": true, "cardNumero": 1287, "mensagem": "…" }

Uma recusa (campo obrigatório vazio, formulário encerrado) responde 400 com {"sucesso": false, "erro": "…"}.

Para ser avisado de cada card criado, assine o evento Um card é aberto num fluxo (CARD_CRIADO) num webhook e filtre pelo pipeId do fluxo — ele sai para todos os fluxos da empresa. Para receber os valores do formulário no corpo, no formato do seu sistema, use uma automação do fluxo no gatilho Solicitação Criada com a ação Webhook e as variáveis {{campo.<identificador>}}.

Formulário de uma fase

Um fluxo também pode pedir que alguém de fora complete uma etapa de um card que já existe — o fornecedor envia a cotação, o candidato manda os documentos. O link chega pela variável {{formulario.link}} num e-mail de automação. Quando o formulário exige e-mail confirmado, a pessoa recebe um código antes de abrir:

Rota	O que faz
GET /public/bpm/phase-form/{token}/status	Se o formulário está disponível
POST /public/bpm/phase-form/{token}/request-access	{"email": "…"} → envia o código por e-mail
POST /public/bpm/phase-form/{token}/verify	{"email", "codigo"} → devolve o accessToken
GET /public/bpm/phase-form/{token}?accessToken=…	Os campos da fase, com os valores do card
POST /public/bpm/phase-form/{token}/submit	{"fieldValues": […], "accessToken": "…", "motivo": "…"} → salva, valida e avança o card

fieldValues segue o mesmo formato do formulário de entrada.

Cuidado

Fora das rotas de upload, o firewall recusa com 403 (sem JSON) corpos acima de 8 KB. No formulário de entrada, mande arquivos pela rota /public/bpm/ged/upload/… e envie no submit só a tempUrl; textos longos também contam para o limite. Veja Limites de uso.

Pesquisas e formulários

Pesquisas têm lógica condicional: a próxima pergunta depende da resposta anterior. Por isso a resposta é uma sessão, pergunta a pergunta.

Rota	O que faz
GET /public/pesquisa/{token}/status	Se a pesquisa está aberta
GET /public/pesquisa/{token}	Seções e perguntas
POST /public/pesquisa/{token}/iniciar?nome=&email=	Abre a sessão; devolve respostaPesquisaId, identificadorAnonimo e a pergunta atual
POST /public/pesquisa/responder	Responde uma pergunta e devolve a próxima
POST /public/pesquisa/finalizar/{respostaId}?identificador=	Conclui

Cada responder leva respostaPesquisaId, identificadorAnonimo, perguntaId e o valor no campo do tipo da pergunta (valorTexto, valorNumero, valorData, valorBoolean, opcaoSelecionadaId, opcoesSelecionadasIds, rankingOrdemIds, respostasMatriz). A resposta traz a próxima pergunta, o percentual concluído e se a pesquisa já pode ser finalizada.

Limites por IP

Rota	Por minuto
iniciar	20
responder	180
finalizar	30
status e estrutura	60

Para as jornadas de pesquisas e clima, veja Pesquisas.

Cuidados

• O token é o portão. Quem tem o link abre o formulário. Se vazar, regenere o token na configuração do fluxo.
• Prazo e limite de envios valem também para a sua interface: consulte status antes de mostrar o formulário.
• O card criado pelo formulário dispara as mesmas automações de um card criado na tela.