Przejdź do treści

Przewodnik programisty · Formularze zapisu

Stwórz własny proces zapisu.

Zachowaj własny HTML, styl i framework witryny. Połącz własny formularz z opublikowanym formularzem smartest.email przez jego publiczny punkt końcowy zapisu.

Ten przewodnik obejmuje

Publiczna konfiguracja formularzy i zapisy z dowolnej witryny

Zgoda, walidacja, odpowiedzi i limity żądań

Użyj adresu URL swojego formularza.

Utwórz formularz w sekcji Formularze zapisu, dodaj wymagane pole e-mail i wymagane pole wyboru zgody, a następnie opublikuj. Karta Instalacja pokazuje dokładny adres URL formularza.

Bazowy adres URL

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

Użyj adresu URL z karty Instalacja formularza. W poniższych przykładach zastąp FORM_ID identyfikatorem opublikowanego formularza.

1

Utwórz

Ustaw pola i jasną treść zgody.

2

Opublikuj

Nowe formularze są wersjami roboczymi; publiczne trasy zwracają 404 do czasu publikacji.

3

Zintegruj

Użyj kodu osadzania lub wywołaj dwa publiczne punkty końcowe poniżej.

Użyj własnego formularza HTML.

Bezpośrednie zgłoszenia są obsługiwane. Utwórz i opublikuj formularz w smartest.email, aby określić pola i treść zgody, a następnie użyj jego identyfikatora w istniejącym formularzu witryny. Możesz wybrać typ osadzony bez instalowania widżetu.

Twoja witryna może przesyłać dane przez JavaScript fetch(), a Twój serwer może przekazać zapis w JSON. Publiczny punkt końcowy nie wymaga klucza API, tokenu dostępu ani skryptu osadzania smartest.email.

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

Zastąp FORM_ID identyfikatorem UUID opublikowanego formularza. Wyślij Content-Type: application/json z poniższą treścią.

Żądanie JSON · po wyrażeniu zgody przez odwiedzającego
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

Ustaw consent na podstawie wyraźnego wyboru odwiedzającego i wyświetl treść zgody oraz informację o prywatności formularza. Zachowaj consent na najwyższym poziomie; skonfigurowane pola kontaktu umieść w data. Uwzględnij każde wymagane pole opublikowanego formularza.

Zwykła akcja formularza HTML wymaga adaptera

Punkt końcowy przyjmuje tylko JSON. Zwykły <form method="post" action="…"> wysyła dane URL-encoded lub multipart i otrzymuje 415 JSON body required. Użyj poniższego przykładu JavaScript dla przeglądarki, lub wyślij do własnego serwera, który przekaże JSON do smartest.email.

Pobieranie publicznej konfiguracji utrzymuje etykiety i walidację zgodne z opublikowanym formularzem. Nie jest wymagane przy każdym zgłoszeniu. Twoja integracja obsługuje własny komunikat sukcesu lub przekierowanie; ten punkt końcowy zawsze odpowiada w JSON.

Wyświetl opublikowane pola.

Ten publiczny punkt końcowy nie wymaga tokenu dostępu. Pobierz konfigurację podczas wyświetlania formularza, a następnie użyj zwróconych nazw pól, treści zgody i adresu prywatności we własnym interfejsie.

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

Zwraca 200 z bezpiecznymi danymi do wyświetlania aktywnego formularza. Każde udane pobranie zwiększa licznik wyświetleń; unikaj odpytywania w pętli.

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

Gotowy skrypt widżetu osadzonego lub wyskakującego. Jeśli nie potrzebujesz własnego interfejsu, użyj dokładnego adresu skryptu z karty Instalacja.

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

Hostowana strona zapisu dla aktywnego formularza.

GET /api/v1/public/forms/{FORM_ID} · przykładowa odpowiedź
{
  "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"
}

Odpowiedź może zawierać dodatkowe skonfigurowane pola, opcje i reguły walidacji. successAction opisuje działanie gotowego widżetu; bezpośrednie zgłoszenie nadal zwraca ogólną odpowiedź JSON poniżej. Skrypt i hostowana strona zwracają 404 dla formularzy roboczych, nieopublikowanych, nieprawidłowych lub nieznanych.

Wyślij zgodę razem z danymi.

Wyślij JSON po wyraźnej zgodzie odwiedzającego na wiadomości marketingowe. Flaga zgody należy do najwyższego poziomu; nie umieszczaj consent wewnątrz data.

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

Bez tokenu dostępu. Wyślij Content-Type: application/json i {data:{email:...},consent:true}. Zwraca tę samą ogólną odpowiedź sukcesu dla nowych i istniejących adresów.

HTML + JavaScript przeglądarki · formularz e-mail i zgody
<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>

Zastąp FORM_ID identyfikatorem UUID formularza i ustaw zapasowy /privacy link do własnej informacji, jeśli formularz nie ma skonfigurowanego privacyUrl. Ten przykład obsługuje dwa wymagane pola; wyświetl i wyślij również wszystkie dodatkowe wymagane pola z opublikowanej konfiguracji.

Odpowiedź akceptacji

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

Odpowiedź celowo nie ujawnia, czy adres już istnieje. Istniejące kontakty zapisane i wypisane zachowują swój stan; tylko nowy zaakceptowany adres dodaje subskrybenta i zapis zgody.

Wysyłaj tylko nazwy obecne w opublikowanej fields tablicy. Wymagane pola muszą zostać podane. Dodatkowe pola wyboru wysyłaj jako wartości logiczne, liczby jako ciągi liczbowe, daty jako YYYY-MM-DD, a wartości select lub radio dokładnie tak, jak w options. API ponownie sprawdza dane na serwerze.

Opcjonalna właściwość najwyższego poziomu website to pułapka antyspamowa. Pomiń ją lub pozostaw pustą przy zwykłym zgłoszeniu. Niepusta wartość zwraca ogólną odpowiedź sukcesu bez dodawania kontaktu; nie jest to pole adresu witryny odwiedzającego.

Obsługuj błędy i limity ruchu.

Publiczne punkty końcowe formularzy dopuszczają żądania GET, POST i OPTIONS z zewnętrznych witryn z nagłówkami Content-Type i Accept. W żądaniach przeglądarki używaj credentials: omit; nie są potrzebne pliki cookie konta, nagłówek Authorization ani klucz API.

StatusZnaczenie
200Konfiguracja lub zaakceptowane zgłoszenie; powtórzony adres otrzymuje tę samą odpowiedź.
400 / 415Nieprawidłowy JSON / żądanie nie jest application/json.
404Nieznany, roboczy, nieopublikowany lub nieprawidłowy formularz.
409Konto osiągnęło limit kontaktów.
413 / 422Treść przekracza 16 KiB / zgoda lub dane pól są nieprawidłowe.
429Osiągnięto limit żądań; kod przeglądarki może użyć retry_after w treści JSON. Integracje serwerowe mogą również odczytać Retry-After.

Błędy używają {"error":true,"message":"..."}; błędy limitów zawierają również retry_after w sekundach. Formularze dopuszczają do 30 żądań na adres IP na minutę, w tym do 10 przesłań. Polityka zabezpieczeń treści Twojej strony musi zezwalać na https://api.smartest.email w connect-src; gotowy kod osadzania wymaga go również w script-src.

Gdy Twój serwer przekazuje przesłania, współdzielą one jego wychodzący adres IP na potrzeby limitu żądań.

Zgoda i dostarczanie

Nowy zaakceptowany zapis tworzy kontakt z subskrypcją i zapisuje treść zgody formularza, czas oraz podane pochodzenie żądania. Twój interfejs musi wyświetlać treść zgody i informację o prywatności przed wysłaniem. Zapisane pochodzenie żądania nie jest dowodem tożsamości. Ten punkt końcowy stosuje pojedyncze potwierdzenie zapisu; nie wysyła wiadomości potwierdzającej ani nie weryfikuje własności adresu.