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

Alterar e apagar formulário

Altera um formulário (campos, estado, configuração) ou o apaga junto com as respostas.

Atualizar formulário

Atualiza só os campos enviados. As validações da criação valem de novo. Atenção: fields e settings são substituídos por inteiro, não mesclados.

PUT/api/v1/admin/forms/{id}Admin

Altera campos de um formulário

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.

Parâmetros de caminho

iduuidobrigatório
Identificador do formulário.

Corpo da requisição

namestring
Nome do formulário. Não pode ficar vazio.
slugstring
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 (Atualizar formulário)

Resposta (Atualizar formulário)

200Formulário atualizado

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 (Atualizar formulário)

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"}
404Não existe formulário com esse id.{"error":"FORM_NOT_FOUND"}
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, ou id que não é UUID.{"error":"FORM_UPDATE_FAILED","detail":"..."}
fields e settings substituem

Para mudar um campo, envie a lista completa de campos. Os campos que você omitir somem do formulário. As respostas já recebidas continuam guardadas.

Apagar formulário

Remove o formulário e todas as respostas recebidas por ele. Não há lixeira. Para só parar de receber respostas, mude o estado para archived.

DELETE/api/v1/admin/forms/{id}Admin

Apaga um formulário e as respostas dele

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.

Parâmetros de caminho

iduuidobrigatório
Identificador do formulário.

Exemplo de requisição (Apagar formulário)

Resposta (Apagar formulário)

204Formulário apagado

Corpo vazio.

Erros (Apagar formulário)

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"}
404Não existe formulário com esse id.{"error":"FORM_NOT_FOUND"}
500id que não é UUID, ou falha de banco.{"error":"FORM_DELETE_FAILED","detail":"..."}
Apaga as respostas junto

Exporte o que precisar antes. As respostas apagadas não voltam.

Veja também

  • Criar formulário
  • Respostas
Anterior
Criar formulário
Próxima
Respostas do formulário
Nesta página
  • Atualizar formulário
  • Exemplo de requisição (Atualizar formulário)
  • Resposta (Atualizar formulário)
  • Erros (Atualizar formulário)
  • Apagar formulário
  • Exemplo de requisição (Apagar formulário)
  • Resposta (Apagar formulário)
  • Erros (Apagar formulário)
  • Veja também
bash
curl -X PUT "$BASE_URL/api/v1/admin/forms/71464e65-00e2-4dbc-b9c8-61c2966008fc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "archived"
}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/forms/71464e65-00e2-4dbc-b9c8-61c2966008fc" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "id": "71464e65-00e2-4dbc-b9c8-61c2966008fc",
  "name": "Fale conosco",
  "slug": "fale-conosco",
  "description": "Contato com a loja",
  "status": "archived",
  "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"
}