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

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"
  }
}'

Resposta

201Formulário criado

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"
}

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

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_content"}`
400	Validaçã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"}`
409	Já existe um formulário com esse `slug`.	`{"error":"SLUG_ALREADY_EXISTS"}`
500	Falha ao gravar.	`{"error":"FORM_CREATE_FAILED","detail":"..."}`

Veja também

POSTCriar formulário

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

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

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"
  }
}'

Resposta

201Formulário criado

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"
}

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

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_content"}`
400	Validaçã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"}`
409	Já existe um formulário com esse `slug`.	`{"error":"SLUG_ALREADY_EXISTS"}`
500	Falha ao gravar.	`{"error":"FORM_CREATE_FAILED","detail":"..."}`