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

Listar e consultar formulários

Lista os formulários da loja com filtros e consulta um formulário pelo id.

Listar formulários

Devolve os formulários da loja, do mais novo para o mais antigo, com filtros e paginação. Cada item já traz seus campos e configuração.

GET/api/v1/admin/formsAdmin

Lista os formulários personalizados

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 consulta

statusstring
draftactivearchived
Filtra pelo estado.
searchstring
Texto do nome ou do slug.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, 1 a 100; fora disso vale 20.
vendor_iduuid
Só formulários desse seller.
marketplace_onlyboolean
Com true, 1 ou yes, só formulários da loja.

Exemplo de requisição (Listar formulários)

bash
curl "$BASE_URL/api/v1/admin/forms?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar formulários)

200Formulários
json
{
  "forms": [
    {
      "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"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

formsarray

Formulários da página.

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.
totalinteger
Total que atende ao filtro.
pageinteger
Página devolvida.
per_pageinteger
Itens por página usados.
total_pagesinteger
Total de páginas.

Erros (Listar formulários)

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","privilege_required_any":["manage_content","view_content"]}
500Falha de banco.{"error":"FORM_LIST_FAILED","detail":"..."}

Consultar formulário

Devolve o formulário completo, com campos e configuração, em qualquer estado.

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

Devolve um formulário pelo id

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

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

Resposta (Consultar formulário)

200Formulário
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 (Consultar 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","privilege_required_any":["manage_content","view_content"]}
404Não existe formulário com esse id.{"error":"FORM_NOT_FOUND"}
500O id não é um UUID válido (500, não 404).{"detail":"o valor \"zz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie.","error":"FORM_GET_FAILED"}

Veja também

  • Criar formulário
  • Respostas
Anterior
Formulários
Próxima
Criar formulário
Nesta página
  • Listar formulários
  • Exemplo de requisição (Listar formulários)
  • Resposta (Listar formulários)
  • Erros (Listar formulários)
  • Consultar formulário
  • Exemplo de requisição (Consultar formulário)
  • Resposta (Consultar formulário)
  • Erros (Consultar formulário)
  • Veja também