JavaScript und fetch

Jeder Code, der eine HTTP-Anfrage senden kann, kann an Ikiform senden. Sende JSON, FormData oder urlencoded Daten an https://ikiform.com/f/<formId> und lies eine JSON-Antwort. Das SDK verpackt das in einer Funktion, ist aber optional. Für eine Schritt-für-Schritt-Einrichtung auf einem bestimmten Stack siehe Anleitungen nach Plattform.

Mit fetch

const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({
    name: "Ada Lovelace",
    email: "ada@example.com",
    message: "Hello",
  }),
});

const result = await response.json();
if (!result.ok) console.error(result.error.code, result.error.fields);

Ausprobieren

curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","message":"Hello from the Ikiform docs."}'

Endpunkte

Wenn du /f/<formId> selbst in einem Browser-Tab öffnest, ist das ein GET, der mit 404 not_found beantwortet wird. Das ist so gewollt: Der Endpunkt nimmt nur Posts an.

Body-Formate

Bodies müssen UTF-8 sein. Ein anderes charset als utf-8 bekommt 415 unsupported_charset, und Bytes, die kein gültiges UTF-8 sind, bekommen denselben Code. Ein JSON-Array oder ein fehlerhafter Body bekommt 400 invalid_body.

Header

Request-Header

Response-Header

CORS

Der Einsendungs-Endpunkt akzeptiert Cross-Origin-Posts von jeder Website. Preflights sind immer erfolgreich und geben den Origin der Anfrage zurück. Es werden keine Cookies oder Zugangsdaten verwendet, also schützt nicht CORS dein Formular, sondern die erlaubten Domains. Sind erlaubte Domains gesetzt, wird ein Post von einer anderen Website je nach Einstellung des Formulars als Spam gespeichert oder abgelehnt. Siehe Erlaubte Domains.

OPTIONS /f/frm_xxxxxxxxxxxxxxxx HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, Accept, Idempotency-Key, Authorization
Access-Control-Max-Age: 86400
Vary: Origin

Antworten

Erfolg ist 201 mit der neuen Einsendungs-ID. Fehler verwenden überall dasselbe Format, mit Feldfehlern nach Feld-ID, wenn die Validierung fehlschlägt. Alle Codes stehen unter Fehler.

{ "ok": true, "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" }

Idempotenz

Sende einen Idempotency-Key-Header oder ein _idempotency-Feld, um erneute Versuche sicher zu machen. Schlüssel sind bis zu 255 Zeichen lang und gelten 24 Stunden lang für das Formular. Werden beide gesendet, gewinnt der Header.

Posts, die fehlschlagen, bevor die Einsendung gespeichert ist, etwa bei Validierungsfehlern, behalten den Schlüssel nicht, sodass du die Daten korrigieren und es mit demselben Schlüssel erneut versuchen kannst. Eine sichere Retry-Schleife:

const key = crypto.randomUUID();

async function send(attempt = 1) {
  const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Idempotency-Key": key },
    body: JSON.stringify({ email: "ada@example.com" }),
  }).catch(() => null);
  if (response && response.status < 500 && response.status !== 429) return response.json();
  if (attempt === 3) throw new Error("Ikiform is unreachable");
  const wait = Number(response?.headers.get("Retry-After")) || attempt * 2;
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  return send(attempt + 1);
}

Anleitungen nach Plattform

Frameworks

• Next.jsEine Client-Komponente oder eine Server Action.
• ReactLade-, Fehler- und Erfolgszustände.
• VueEine Single-File-Komponente.
• NuxtPosts vor der Hydration und danach mit $fetch.
• SvelteEine Svelte-5-Komponente und eine Server Action.
• SvelteKitEine vorgerenderte Seite mit Progressive Enhancement.
• AstroEin Formular ohne JavaScript, optional erweitert.
• GatsbyEin statisches Formular oder eine Gatsby Function.
• Reines JavaScriptfetch mit Inline-Fehlern.

Statische Website-Generatoren

• HugoEin Partial und ein Shortcode für Inhaltsdateien.
• JekyllEin Include und die Einrichtung für GitHub Pages.
• EleventyEin Shortcode für Nunjucks, Liquid und Markdown.

Website-Baukästen

• WebflowDer Form Block mit einer eigenen Action.
• FramerEin Formular-Webhook oder eine Code-Komponente.
• WordPressDer Custom-HTML-Block oder ein Shortcode.
• WixEin HTML-Embed, das mit fetch sendet.
• SquarespaceEin Code-Block, mit oder ohne JavaScript.
• CarrdEin eigenes Formular, das an eine URL sendet.