VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Formulários

POSTCriar formulário

Cria um formulário personalizado com campos e configuração.

Cria um formulário (contato, orçamento, cadastro de parceiro...) que a vitrine serve em /api/v1/storefront/forms/{slug} quando o estado é active. Os campos e a configuração são validados na hora: um formulário inválido não é gravado.

POST/api/v1/admin/formsAdmin

Cria um formulário personalizado

Rota ligada ao módulo custom-forms: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_content.

Corpo da requisição

namestringobrigatório
Nome do formulário. Não pode ficar vazio.
slugstringobrigatório
Identificador na URL: minúsculas, números e hífens (fale-conosco). Único na loja.
descriptionstring
Descrição.
statusstringpadrão: draft
draftactivearchived
Estado. Só active aceita respostas dos clientes.
fieldsarray
Lista de campos (veja a página inicial da seção). Ids de campo não podem se repetir.
settingsobject
Configuração do formulário (veja a página inicial da seção).

Exemplo de requisição

Resposta

201Formulário criado

Campos da resposta

iduuid
Identificador do formulário.
namestring
Nome interno.
slugstring
Identificador na URL pública do formulário. Só minúsculas, números e hífens. Único.
descriptionstring
Descrição.
statusstring
draft, active ou archived.
fieldsarray
Campos do formulário, na ordem de order. Veja a seção "Campos" na página inicial desta seção.
settingsobject
Configuração: mensagem de sucesso, e-mail de aviso, redirecionamento, limite de envios, antispam.
vendor_iduuid
Seller dono do formulário. Ausente em formulário da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_content"}
400Validação: SLUG_REQUIRED, INVALID_SLUG, NAME_REQUIRED, INVALID_STATUS, INVALID_FIELD_ID, INVALID_FIELD_TYPE:<id>, INVALID_FIELD_LABEL:<id>, DUPLICATE_FIELD_ID:<id>, FIELD_OPTIONS_REQUIRED:<id>, INVALID_FIELDS_JSON, INVALID_SETTINGS_JSON, INVALID_NOTIFICATION_EMAIL.{"error":"FIELD_OPTIONS_REQUIRED:assunto"}
409Já existe um formulário com esse slug.{"error":"SLUG_ALREADY_EXISTS"}
500Falha ao gravar.{"error":"FORM_CREATE_FAILED","detail":"..."}
Comece em rascunho

Crie como draft, confira o resultado na vitrine de teste e só então mude para active.

Veja também

  • Alterar e apagar formulário
  • Listar e consultar formulários
Anterior
Listar e consultar formulários
Próxima
Alterar e apagar formulário
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/forms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Fale conosco",
  "slug": "fale-conosco",
  "description": "Contato com a loja",
  "status": "active",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": true,
      "order": 2,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Troca",
          "value": "troca"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": false,
      "order": 3,
      "validation": {
        "max_length": 500
      }
    }
  ],
  "settings": {
    "success_message": "Obrigado! Responderemos em breve.",
    "notification_email": "loja@example.com",
    "redirect_url": "",
    "captcha_enabled": false,
    "captcha_provider": "honeypot"
  }
}'
json
{
  "id": "71464e65-00e2-4dbc-b9c8-61c2966008fc",
  "name": "Fale conosco",
  "slug": "fale-conosco",
  "description": "Contato com a loja",
  "status": "active",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": true,
      "order": 2,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Troca",
          "value": "troca"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": false,
      "order": 3,
      "validation": {
        "max_length": 500
      }
    }
  ],
  "settings": {
    "success_message": "Obrigado! Responderemos em breve.",
    "notification_email": "loja@example.com",
    "redirect_url": "",
    "captcha_enabled": false,
    "captcha_provider": "honeypot"
  },
  "created_at": "2026-10-11T21:05:13.186855Z",
  "updated_at": "2026-10-11T21:05:13.186855Z"
}