Formulários
Formulários personalizados da loja (contato, orçamento, parceiros) e as respostas que os clientes enviam.
Um formulário personalizado é uma página de coleta de dados que o lojista monta sem programar: fale conosco, pedido de orçamento, cadastro de parceiro. Você define os campos e a configuração; o cliente preenche na vitrine; cada envio vira uma resposta que o lojista consulta no painel.
Como funciona
O fluxo é criar o formulário em draft, definir os campos, ativar, acompanhar as respostas e, ao fim da campanha, arquivar. Cada resposta guarda os valores em data, com uma chave por campo, e passa por três andamentos: nova, lida, respondida.
| Estado | Significado |
|---|---|
draft | Rascunho. Não recebe respostas. |
active | Publicado e recebendo respostas. |
archived | Arquivado. Não recebe respostas, mas as já recebidas continuam consultáveis. |
| Andamento da resposta | Significado |
|---|---|
new | Ainda não vista. |
read | Vista. |
replied | Já respondida ao cliente. |
Conceitos importantes
Campos
fields é uma lista. Cada campo tem:
| Chave | Obrigatória | Significado |
|---|---|---|
id | sim | Nome do campo, único no formulário. É a chave em data nas respostas. |
type | sim | text, textarea, email, phone, select, checkbox, radio, file, date, number ou hidden. |
label | sim (exceto hidden) | Rótulo mostrado ao cliente. |
required | não | Se o cliente precisa preencher. |
placeholder | não | Dica dentro do campo. |
options | em select e radio | Lista de {label, value}. Pelo menos uma opção útil. Um checkbox sem opções é a caixa simples de sim/não e pede label. |
validation | não | min_length, max_length, min, max, pattern (expressão regular), file_types (tipos MIME separados por vírgula) e max_file_size (bytes). |
order | não | Posição do campo. |
Configuração
settings aceita: success_message (texto após o envio), notification_email (e-mail avisado a cada resposta; precisa ser um endereço válido), redirect_url (para onde levar o cliente), max_submissions (limite de respostas; vazio ou 0 = sem limite), captcha_enabled e captcha_provider (hoje só honeypot funciona: um campo invisível que, se preenchido, marca o envio como spam). A chave require_captcha é um apelido de captcha_enabled, e captcha_site_key é aceita e guardada, mas ainda não é usada.
Slug
O slug deve ser formado por minúsculas, números e hífens (fale-conosco) e é único. Repetir devolve 409.
Respostas
As respostas têm dados pessoais. Ver, marcar como lidas ou apagar uma resposta individual usa rotas próprias (/api/v1/admin/form-submissions/...) que não fazem parte desta seção.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/forms | Lista os formulários personalizados | admin |
| GET | /api/v1/admin/forms/{id} | Devolve um formulário pelo id | admin |
| POST | /api/v1/admin/forms | Cria um formulário personalizado | admin |
| PUT | /api/v1/admin/forms/{id} | Altera campos de um formulário | admin |
| DELETE | /api/v1/admin/forms/{id} | Apaga um formulário e as respostas dele | admin |
| GET | /api/v1/admin/forms/{id}/submissions | Lista as respostas recebidas por um formulário | admin |
Erros comuns
- Enviar só um campo em
fieldsnuma atualização, achando que ele se soma aos outros: a lista inteira é substituída. - Criar um
selectouradiosemoptions: recusado comFIELD_OPTIONS_REQUIRED:<id>. - Usar o mesmo
idem dois campos: recusado comDUPLICATE_FIELD_ID:<id>. - Usar
slugcom maiúsculas, espaço ou acento: recusado comINVALID_SLUG. - Apagar o formulário para "limpar a lista": as respostas vão junto. Arquive.
- Passar um
idque não é UUID e esperar 404: a consulta responde 500.