VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Conteúdo da vitrine

Formulários

Lê a definição de um formulário personalizado da loja e envia as respostas do visitante.

Um formulário personalizado é um conjunto de campos que o administrador monta no painel, sem programar: contato, orçamento, cadastro de revenda, pesquisa. A vitrine lê a definição (quais campos existem, quais são obrigatórios) para desenhar a tela, e depois envia as respostas. Cada envio vira uma submissão que o administrador acompanha no painel.

Pontos principais
  • Depende do módulo custom-forms.
  • Só formulários active são lidos ou aceitam envio. Rascunho e arquivado respondem 404 FORM_NOT_FOUND.
  • As respostas vão em data, um objeto cujas chaves são os id dos campos (e não os rótulos).
  • A validação roda no servidor: obrigatório, formato de e-mail, opções de lista, tamanho mínimo e máximo, padrão (regex).
  • O envio é anônimo; o servidor guarda o IP e o User-Agent de quem enviou.
  • O administrador pode ser avisado por e-mail a cada envio; isso não altera a resposta da API.

Tipos de campo

typeUsoValidação feita pela API
textTexto de uma linhaTamanho mínimo/máximo e padrão, se definidos. O tamanho conta bytes, então letras acentuadas valem 2
textareaTexto longoIdem
emailE-mailFormato de endereço
phoneTelefoneTamanho/padrão, se definidos
selectLista suspensaO valor precisa ser um value das options
radioEscolha únicaO valor precisa ser um value das options
checkboxCaixa de seleçãoSomente obrigatório, quando definido
fileArquivoVer aviso de arquivos abaixo
dateDataSomente obrigatório, quando definido
numberNúmeroSomente obrigatório, quando definido
hiddenCampo ocultoSomente obrigatório, quando definido
GET/api/v1/storefront/forms/{slug}Pública

Ler a definição de um formulário

Parâmetros de caminho

slugstringobrigatório
Identificador do formulário, definido no painel (por exemplo contato).

Exemplo de requisição

Resposta

200Formulário

Campos da resposta

iduuid
Id do formulário.
namestring
Nome.
slugstring
Identificador na URL.
descriptionstring
Texto de apoio exibido no topo.
statusstring
Aqui sempre active.
fieldsarray
Campos do formulário. A API não os ordena: ordene por order no cliente.
fields[].idstring
Identificador do campo. É a chave que você usa em data no envio.
fields[].typestring
texttextareaemailphoneselectcheckboxradiofiledatenumberhidden
Tipo do campo.
fields[].labelstring
Rótulo para exibir.
fields[].placeholderstring
Texto de exemplo dentro do campo. Ausente quando não há.
fields[].requiredboolean
Se o campo é obrigatório.
fields[].orderinteger
Posição do campo na tela.
fields[].optionsarray
Opções de select, radio e checkbox: objetos com label e value.
fields[].validationobject
Regras opcionais: min_length, max_length, min, max, pattern (regex), file_types e max_file_size. Só min_length, max_length e pattern são exigidos pelo servidor.
settingsobject
Configuração do formulário. Pode trazer success_message, redirect_url, max_submissions, captcha_enabled, captcha_provider e notification_email.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo
403Módulo custom-forms desligado.{"error":"module_disabled","module":"custom-forms"}
404Não há formulário ativo com esse slug.{"error":"FORM_NOT_FOUND"}
500Falha ao ler.{"error":"FORM_GET_FAILED","detail":"..."}
settings pode trazer dados internos

O objeto settings é devolvido inteiro, e inclui notification_email (o e-mail que recebe os avisos de envio) e max_submissions. Use settings só para ler success_message, redirect_url e captcha_enabled, e nunca exiba o resto ao visitante.

POST/api/v1/storefront/forms/{slug}/submitPública

Enviar as respostas de um formulário

Parâmetros de caminho

slugstringobrigatório
Identificador do formulário.

Corpo da requisição

dataobjectobrigatório
Respostas, com os id dos campos como chaves e os valores preenchidos. Chaves que não são campos do formulário são aceitas e gravadas, sem erro. O corpo inteiro da requisição pode ter no máximo 10 MB.
_hpstring
Campo isca (honeypot) anti-spam. Deve ir vazio (ou ausente). Se o formulário tem captcha ativado com o provedor honeypot e este campo, ou data._hp, vier preenchido, o envio é recusado.

Exemplo de requisição

Resposta

201Envio recebido

Campos da resposta

submission.iduuid
Id do envio, útil como protocolo.
submission.form_iduuid
Formulário.
submission.dataobject
As respostas gravadas.
submission.ip_addressstring
IP registrado.
submission.user_agentstring
User-Agent registrado.
submission.statusstring
Estado do envio no painel. Nasce new.
submission.created_atstring
Quando foi recebido (RFC 3339).
success_messagestring
Mensagem de agradecimento definida no painel. Ausente quando não há.
redirect_urlstring
Endereço para onde levar o visitante depois do envio. Ausente quando não há.

Erros

Os erros de regra devolvem um código curto em maiúsculas; os de campo trazem o id do campo depois de dois pontos.

StatusQuandoCorpo
400JSON inválido.{"error":"INVALID_JSON","detail":"..."}
400Corpo acima de 10 MB, ou arquivo embutido grande demais.{"error":"FILE_TOO_LARGE"}
400Valor embutido (data:) com tipo que não é imagem permitida.{"error":"MALICIOUS_FILE_UPLOAD"}
400Campo isca preenchido (captcha honeypot).{"error":"CAPTCHA_FAILED"}
400Campo obrigatório vazio.{"error":"FIELD_REQUIRED:nome"}
400E-mail inválido.{"error":"INVALID_EMAIL:email"}
400Valor que não está nas opções.{"error":"INVALID_OPTION:assunto"}
400Menor que min_length.{"error":"MIN_LENGTH:mensagem"}
400Maior que max_length.{"error":"MAX_LENGTH:mensagem"}
400Fora do pattern.{"error":"PATTERN_MISMATCH:telefone"}
400data que não é um objeto JSON, ou formulário com campos corrompidos.{"error":"INVALID_SUBMISSION_DATA"} ou {"error":"INVALID_FORM_FIELDS"}
403Módulo custom-forms desligado.{"error":"module_disabled","module":"custom-forms"}
404Não há formulário ativo com esse slug.{"error":"FORM_NOT_FOUND"}
429O formulário atingiu max_submissions.{"error":"MAX_SUBMISSIONS_REACHED"}
500Falha ao gravar.{"error":"SUBMIT_FAILED","detail":"..."}
Arquivos: envie por outro caminho

O formulário aceita campos file, mas esta rota recebe só JSON. Um arquivo só pode ir como imagem embutida em texto (data:image/...;base64,...), e conta no limite de 10 MB do corpo. Qualquer data: que não seja uma imagem permitida é recusado como MALICIOUS_FILE_UPLOAD. Para anexos grandes, suba o arquivo antes e envie só o endereço.

Veja também

  • Páginas
  • Erros
  • Limites de requisições
Anterior
FAQ da plataforma
Próxima
Páginas do app
Nesta página
  • Tipos de campo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/forms/contato"
bash
curl -X POST "$BASE_URL/api/v1/storefront/forms/contato/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "nome": "Maria Souza",
      "email": "maria.souza@example.com",
      "assunto": "duvida",
      "mensagem": "Gostaria de saber o prazo de entrega."
    },
    "_hp": ""
  }'
json
{
  "id": "e1d2c3b4-a5f6-4789-8a9b-0c1d2e3f4a5b",
  "name": "Fale conosco",
  "slug": "contato",
  "description": "Responderemos em até 1 dia útil.",
  "status": "active",
  "fields": [
    { "id": "nome", "type": "text", "label": "Seu nome", "required": true, "order": 1 },
    { "id": "email", "type": "email", "label": "E-mail", "required": true, "order": 2 },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": false,
      "order": 3,
      "options": [
        { "label": "Dúvida", "value": "duvida" },
        { "label": "Reclamação", "value": "reclamacao" }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": true,
      "order": 4,
      "validation": { "min_length": 10, "max_length": 2000 }
    }
  ],
  "settings": {
    "success_message": "Recebemos sua mensagem!",
    "captcha_enabled": true,
    "captcha_provider": "honeypot"
  },
  "created_at": "2026-08-01T12:00:00Z",
  "updated_at": "2026-09-15T09:30:00Z"
}
json
{
  "submission": {
    "id": "f9e8d7c6-b5a4-4392-81a0-9f8e7d6c5b4a",
    "form_id": "e1d2c3b4-a5f6-4789-8a9b-0c1d2e3f4a5b",
    "data": {
      "nome": "Maria Souza",
      "email": "maria.souza@example.com",
      "assunto": "duvida",
      "mensagem": "Gostaria de saber o prazo de entrega."
    },
    "ip_address": "203.0.113.10",
    "user_agent": "Mozilla/5.0",
    "status": "new",
    "created_at": "2026-10-11T21:10:00Z"
  },
  "success_message": "Recebemos sua mensagem!"
}