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

Formulários de captação

Cria, edita, lista e apaga formulários do seller, com a definição de campos e configurações.

O formulário é definido por uma lista de campos (fields) e um objeto de configurações (settings). A vitrine monta a página a partir dessa definição e valida o que o visitante envia. Apagar um formulário apaga também todos os leads dele.

Campos do formulário

Campos de um item de `fields`

idstringobrigatório
Chave do campo, única no formulário. Aparece em data de cada lead. Obrigatória.
typestringobrigatório
texttextareaemailphoneselectcheckboxradiofiledatenumberhidden
Tipo do campo.
labelstring
Rótulo. Obrigatório, exceto em campos hidden.
placeholderstring
Texto de ajuda dentro do campo.
requiredboolean
O visitante precisa preencher.
orderinteger
Posição na página.
optionsarray
Opções {label, value}. Obrigatórias em select e radio; em checkbox podem faltar se houver label (caixa única).
validationobject
Regras opcionais: min_length, max_length, min, max, pattern, file_types, max_file_size.

Campos de `settings`

success_messagestring
Mensagem mostrada após o envio.
notification_emailstring
E-mail que recebe um aviso a cada lead. Se informado, precisa ser um e-mail válido.
redirect_urlstring
Para onde levar o visitante depois do envio.
max_submissionsinteger
Limite de envios. 0 ou ausente = sem limite.
captcha_enabledboolean
Liga a proteção anti-robô.
captcha_providerstring
honeypotturnstilerecaptcha-v3
honeypot (padrão), turnstile ou recaptcha-v3. O valor é gravado sem validação e hoje a plataforma só aplica a verificação honeypot (um campo oculto _hp que deve ficar vazio).
captcha_site_keystring
Chave pública do provedor de captcha.

Listar formulários

GET/api/v1/vendor/formsSeller

Lista os formulários do seller

Do mais novo para o mais antigo, sem paginação.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Exemplo de requisição

200Formulários

Campos da resposta

formsarray

Formulários do seller.

iduuid
Id do formulário.
namestring
Nome interno.
slugstring
Identificador na URL pública, único na loja inteira.
descriptionstring
Descrição interna.
statusstring
draftactivearchived
draft, active ou archived.
fieldsarray
Definição dos campos. Veja Campos do formulário.
settingsobject
Configurações do formulário. Veja a mesma seção.
vendor_iduuid
Seller dono.
created_atstring
Criação.
updated_atstring
Última alteração.
totalinteger
Quantidade de formulários.

Consultar formulário

GET/api/v1/vendor/forms/{id}Seller

Devolve um formulário

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do formulário.

Exemplo de requisição

200Formulário

Criar formulário

POST/api/v1/vendor/formsSeller

Cria um formulário

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Corpo da requisição

namestringobrigatório
Nome interno. Obrigatório.
slugstringobrigatório
Identificador na URL. Só a-z, 0-9 e hífens entre blocos (fale-com-a-loja). Único na loja inteira.
descriptionstring
Descrição interna.
statusstringpadrão: draft
draftactivearchived
draft, active ou archived.
fieldsarray
Lista de campos, como em "Campos do formulário". Omitida = lista vazia.
settingsobject
Configurações. Omitido = {}.

Exemplo de requisição

201Formulário criado

Alterar formulário

PUT/api/v1/vendor/forms/{id}Seller

Altera um formulário

Parcial. fields e settings, quando enviados, substituem o valor inteiro (não há mesclagem): reenvie a lista completa de campos.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do formulário.

Corpo da requisição

...object
Qualquer campo do corpo da criação, todos opcionais.

Exemplo de requisição

200Formulário atualizado

Apagar formulário

DELETE/api/v1/vendor/forms/{id}Seller

Apaga um formulário e seus leads

Remove o formulário e todos os leads recebidos por ele. Para parar de receber sem perder os leads, passe o status para archived.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do formulário.

Exemplo de requisição

200Formulário apagado

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário do seller (equipe) não tem nenhum dos privilégios exigidos. O dono da loja nunca recebe este erro.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
403O usuário autenticado não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}
400JSON inválido.{"error":"invalid request body","detail":"..."}
400Dados do formulário inválidos. Códigos: NAME_REQUIRED, SLUG_REQUIRED, INVALID_SLUG, INVALID_STATUS, SLUG_ALREADY_EXISTS, INVALID_FIELDS_JSON, INVALID_FIELD_ID:<posição>, DUPLICATE_FIELD_ID:<id>, INVALID_FIELD_TYPE:<tipo>, INVALID_FIELD_LABEL:<id>, FIELD_OPTIONS_REQUIRED:<id>, INVALID_SETTINGS_JSON, INVALID_NOTIFICATION_EMAIL.{"error":"SLUG_ALREADY_EXISTS"}
404Formulário inexistente ou de outro seller (GET).{"error":"form not found"}
404Formulário inexistente ou de outro seller (PUT e DELETE).{"error":"FORM_NOT_FOUND"}
Slug repetido não é 409

SLUG_ALREADY_EXISTS vem com status 400. Como o slug vale para a loja inteira, trate-o como "escolha outro nome" e não como falha do seu seller. O erro de formulário inexistente em GET é form not found; em PUT e DELETE é FORM_NOT_FOUND.

Veja também

  • Leads de um formulário
  • Newsletter
  • Visão geral
Anterior
Campanhas de newsletter
Próxima
Leads de um formulário
Nesta página
  • Campos do formulário
  • Listar formulários
  • Exemplo de requisição
  • Consultar formulário
  • Exemplo de requisição
  • Criar formulário
  • Exemplo de requisição
  • Alterar formulário
  • Exemplo de requisição
  • Apagar formulário
  • Exemplo de requisição
  • Erros
  • Veja também
bash
curl -X GET "$BASE_URL/api/v1/vendor/forms" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X GET "$BASE_URL/api/v1/vendor/forms/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/forms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Fale com a loja",
  "slug": "fale-com-a-loja",
  "description": "Dúvidas e pedidos de orçamento.",
  "status": "draft",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "email",
      "type": "email",
      "label": "E-mail",
      "required": true,
      "order": 2
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": false,
      "order": 3,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Orçamento",
          "value": "orcamento"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": true,
      "order": 4
    }
  ],
  "settings": {
    "success_message": "Recebemos sua mensagem.",
    "notification_email": "contato@exemplo.com.br",
    "captcha_enabled": true,
    "captcha_provider": "honeypot"
  }
}'
bash
curl -X PUT "$BASE_URL/api/v1/vendor/forms/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
bash
curl -X DELETE "$BASE_URL/api/v1/vendor/forms/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "forms": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "name": "Fale com a loja",
      "slug": "fale-com-a-loja",
      "description": "Dúvidas e pedidos de orçamento.",
      "status": "draft",
      "fields": [
        {
          "id": "nome",
          "type": "text",
          "label": "Nome",
          "required": true,
          "order": 1
        },
        {
          "id": "email",
          "type": "email",
          "label": "E-mail",
          "required": true,
          "order": 2
        },
        {
          "id": "assunto",
          "type": "select",
          "label": "Assunto",
          "required": false,
          "order": 3,
          "options": [
            {
              "label": "Dúvida",
              "value": "duvida"
            },
            {
              "label": "Orçamento",
              "value": "orcamento"
            }
          ]
        },
        {
          "id": "mensagem",
          "type": "textarea",
          "label": "Mensagem",
          "required": true,
          "order": 4
        }
      ],
      "settings": {
        "success_message": "Recebemos sua mensagem.",
        "notification_email": "contato@exemplo.com.br",
        "captcha_enabled": true,
        "captcha_provider": "honeypot"
      },
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Fale com a loja",
  "slug": "fale-com-a-loja",
  "description": "Dúvidas e pedidos de orçamento.",
  "status": "draft",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "email",
      "type": "email",
      "label": "E-mail",
      "required": true,
      "order": 2
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": false,
      "order": 3,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Orçamento",
          "value": "orcamento"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": true,
      "order": 4
    }
  ],
  "settings": {
    "success_message": "Recebemos sua mensagem.",
    "notification_email": "contato@exemplo.com.br",
    "captcha_enabled": true,
    "captcha_provider": "honeypot"
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Fale com a loja",
  "slug": "fale-com-a-loja",
  "description": "Dúvidas e pedidos de orçamento.",
  "status": "draft",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "email",
      "type": "email",
      "label": "E-mail",
      "required": true,
      "order": 2
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": false,
      "order": 3,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Orçamento",
          "value": "orcamento"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": true,
      "order": 4
    }
  ],
  "settings": {
    "success_message": "Recebemos sua mensagem.",
    "notification_email": "contato@exemplo.com.br",
    "captcha_enabled": true,
    "captcha_provider": "honeypot"
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Fale com a loja",
  "slug": "fale-com-a-loja",
  "description": "Dúvidas e pedidos de orçamento.",
  "status": "active",
  "fields": [
    {
      "id": "nome",
      "type": "text",
      "label": "Nome",
      "required": true,
      "order": 1
    },
    {
      "id": "email",
      "type": "email",
      "label": "E-mail",
      "required": true,
      "order": 2
    },
    {
      "id": "assunto",
      "type": "select",
      "label": "Assunto",
      "required": false,
      "order": 3,
      "options": [
        {
          "label": "Dúvida",
          "value": "duvida"
        },
        {
          "label": "Orçamento",
          "value": "orcamento"
        }
      ]
    },
    {
      "id": "mensagem",
      "type": "textarea",
      "label": "Mensagem",
      "required": true,
      "order": 4
    }
  ],
  "settings": {
    "success_message": "Recebemos sua mensagem.",
    "notification_email": "contato@exemplo.com.br",
    "captcha_enabled": true,
    "captcha_provider": "honeypot"
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}
json
{
  "message": "form deleted"
}