Saltar para o conteúdo

Guia para programadores · Formulários de inscrição

Crie a sua própria experiência de inscrição.

Mantenha o seu HTML, estilo e framework do site. Ligue o formulário personalizado a um formulário publicado em smartest.email através do ponto de acesso público de inscrição.

Este guia inclui

Configuração pública de formulários e inscrições a partir de qualquer origem de site

Consentimento, validação, respostas e limites de pedidos

Use o URL do formulário.

Crie um formulário em Formulários de inscrição, inclua um campo de e-mail obrigatório e uma caixa de consentimento obrigatória e publique-o. O separador Instalar apresenta o URL exato do formulário.

URL base

https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Utilize o URL apresentado no separador Instalar do formulário. Substitua FORM_ID pelo ID do formulário publicado nos exemplos abaixo.

1

Criar

Defina os campos e um texto de consentimento claro.

2

Publicar

Os novos formulários começam como rascunhos; as rotas públicas devolvem 404 até à publicação.

3

Integrar

Use o código de incorporação ou chame os dois pontos de acesso públicos abaixo.

Use o seu próprio formulário HTML.

A submissão direta é suportada. Crie e publique um formulário em smartest.email para definir os campos e o texto de consentimento e use o respetivo ID no formulário existente do site. Pode escolher o tipo de formulário incorporado sem instalar o widget.

O seu site pode enviar através de JavaScript fetch(), ou o seu servidor pode encaminhar a inscrição como JSON. O ponto de acesso público não exige chave de API, token de acesso nem script incorporado de smartest.email.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Substitua FORM_ID pelo UUID do formulário publicado. Envie Content-Type: application/json com os dados abaixo.

Pedido JSON · após o visitante dar consentimento
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

Defina consent a partir da escolha explícita do visitante e apresente o texto de consentimento e o aviso de privacidade do formulário. Mantenha consent no nível superior; coloque os campos de contacto configurados dentro de data. Inclua todos os campos obrigatórios do formulário publicado.

A ação de um formulário HTML simples precisa de um adaptador

O ponto de acesso aceita apenas JSON. Um <form method="post" action="…"> normal envia dados codificados em URL ou multipart e recebe 415 JSON body required. Use o exemplo de JavaScript para navegador abaixo, ou envie para o seu servidor e faça-o enviar JSON para smartest.email.

Consultar a configuração pública mantém os textos e a validação alinhados com o formulário publicado. Não é obrigatório fazê-lo para cada submissão. A integração gere a própria mensagem de sucesso ou redirecionamento; este ponto de acesso responde sempre em JSON.

Apresente os campos que publicou.

Este ponto de acesso público não exige token de acesso. Consulte-o ao apresentar um formulário e use os nomes dos campos, o texto de consentimento e o URL de privacidade devolvidos na sua interface.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Devolve 200 com dados seguros para apresentar um formulário ativo. Cada consulta bem-sucedida incrementa o número de visualizações; evite consultas repetitivas.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

Script de widget pronto a usar, incorporado na página ou em popup. Use o URL exato do script apresentado em Instalar se não precisar de uma interface personalizada.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

Página de inscrição alojada para um formulário ativo.

GET /api/v1/public/forms/{FORM_ID} · exemplo de resposta
{
  "id": "FORM_ID",
  "name": "Newsletter",
  "organizationName": "Example Studio",
  "type": "embedded",
  "fields": [
    { "name": "email", "type": "email", "label": "Email address", "required": true },
    { "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
  ],
  "styling": {},
  "successAction": {},
  "privacyUrl": "https://example.com/privacy"
}

A resposta pode incluir outros campos, opções e regras de validação configurados. successAction descreve o comportamento do widget pronto a usar; a submissão direta continua a devolver a resposta JSON genérica abaixo. O script e a página alojada devolvem 404 para formulários em rascunho, não publicados, inválidos ou desconhecidos.

Envie o consentimento com os dados.

Envie JSON depois de o visitante escolher explicitamente receber e-mails de marketing. A indicação de consentimento deve estar no nível superior; não coloque consent dentro de data.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Sem token de acesso. Envie Content-Type: application/json e {data:{email:...},consent:true}. Devolve a mesma resposta genérica de sucesso para endereços novos e existentes.

HTML + JavaScript no navegador · formulário de e-mail e consentimento
<form id="signup-form">
  <fieldset id="signup-fields" disabled>
    <legend>Subscribe to email updates</legend>
    <label id="email-label" for="signup-email">Email address</label>
    <input id="signup-email" type="email" autocomplete="email" required>
    <label for="signup-consent">
      <input id="signup-consent" type="checkbox" required>
      <span id="consent-label"></span>
    </label>
    <a id="privacy-link" href="/privacy">Privacy notice</a>
    <button id="signup-submit" type="submit">Subscribe</button>
  </fieldset>
  <p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
  const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
  const form = document.querySelector("#signup-form");
  const fields = document.querySelector("#signup-fields");
  const button = document.querySelector("#signup-submit");
  const status = document.querySelector("#signup-status");
  let ready = false;
  let submitting = false;

  form.addEventListener("submit", async event => {
    event.preventDefault();
    if (!ready || submitting || !form.reportValidity()) return;
    submitting = true;
    button.disabled = true;
    try {
      const response = await fetch(endpoint + "/submit", {
        method: "POST",
        credentials: "omit",
        headers: { "Content-Type": "application/json", "Accept": "application/json" },
        body: JSON.stringify({
          data: { email: document.querySelector("#signup-email").value.trim() },
          consent: document.querySelector("#signup-consent").checked
        })
      });
      const result = await response.json();
      status.textContent = result.message || "Please try again.";
      if (response.ok) form.reset();
    } catch {
      status.textContent = "Please try again.";
    } finally {
      submitting = false;
      button.disabled = false;
    }
  });

  try {
    const response = await fetch(endpoint, { credentials: "omit" });
    if (!response.ok) throw new Error("Signup form unavailable");
    const config = await response.json();
    document.querySelector("#email-label").textContent =
      config.fields.find(field => field.name === "email").label;
    document.querySelector("#consent-label").textContent =
      config.fields.find(field => field.name === "consent").label;
    if (config.privacyUrl) {
      document.querySelector("#privacy-link").href = config.privacyUrl;
    }
    ready = true;
    fields.disabled = false;
  } catch (error) {
    status.textContent = error.message;
  }
</script>

Substitua FORM_ID pelo UUID do formulário e defina a ligação alternativa /privacy para o seu aviso caso o formulário não tenha um privacyUrlconfigurado. Este exemplo trata dos dois campos obrigatórios; apresente e envie quaisquer outros campos obrigatórios da configuração publicada.

Resposta de aceitação

JSON
{"success":true,"message":"Thank you for subscribing."}

A resposta não indica propositadamente se o endereço já existe. Os contactos existentes, inscritos ou com inscrição cancelada, mantêm o estado atual; apenas um novo endereço aceite adiciona um subscritor e um registo de consentimento.

Envie apenas nomes presentes na lista publicada fields . Os campos obrigatórios têm de ser enviados. Para campos adicionais, envie caixas de seleção como booleanos, números como cadeias numéricas, datas como YYYY-MM-DDe valores de seleção ou escolha única exatamente como indicados em options. A API volta a validar os dados no servidor.

A propriedade opcional de nível superior website é uma armadilha antisspam. Omita-a ou deixe-a vazia numa submissão normal. Um valor não vazio devolve a resposta genérica de sucesso sem adicionar um contacto; não é um campo para o URL do site do visitante.

Trate as falhas e os limites de tráfego.

Os pontos de acesso públicos de formulários permitem pedidos GET, POST e OPTIONS entre origens a partir de sites externos com os cabeçalhos Content-Type e Accept. Use credentials: omit nos pedidos do navegador; não são necessários cookies de conta, cabeçalho Authorization nem chave de API.

EstadoSignificado
200Configuração ou submissão aceite; um endereço duplicado recebe a mesma resposta de submissão.
400 / 415JSON malformado / o pedido não é application/json.
404Formulário desconhecido, em rascunho, não publicado ou inválido.
409A conta atingiu o limite de contactos.
413 / 422O corpo excede 16 KiB / o consentimento ou os dados dos campos são inválidos.
429Limite de pedidos atingido; o código no navegador pode usar retry_after no corpo JSON. As integrações de servidor também podem ler Retry-After.

Os erros usam {"error":true,"message":"..."}; os erros de limite de pedidos também incluem retry_after em segundos. Os formulários permitem até 30 pedidos por IP por minuto, incluindo até 10 envios. A política de segurança de conteúdos do seu website tem de permitir https://api.smartest.email em connect-src; o código de incorporação pronto a usar também precisa dessa permissão em script-src.

Quando o seu próprio servidor reencaminha envios, estes partilham o IP de saída desse servidor para efeitos de limitação de pedidos.

Consentimento e entrega

Uma nova inscrição aceite cria um contacto inscrito e guarda o texto de consentimento do formulário, a hora e a origem fornecida no pedido. A interface personalizada deve apresentar o texto de consentimento e o aviso de privacidade antes da submissão. A origem registada do pedido não é prova de identidade. Este ponto de acesso usa inscrição simples; não envia um e-mail de confirmação nem verifica a titularidade do endereço.