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)

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

Resposta (Atualizar formulário)

200Formulário atualizado

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

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)

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

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)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/forms/71464e65-00e2-4dbc-b9c8-61c2966008fc" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar formulário)

204Formulário apagado

Corpo vazio.

Erros (Apagar formulário)

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

Veja também

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)

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

Resposta (Atualizar formulário)

200Formulário atualizado

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

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)

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

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)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/forms/71464e65-00e2-4dbc-b9c8-61c2966008fc" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar formulário)

204Formulário apagado

Corpo vazio.

Erros (Apagar formulário)

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