Zurück zu Site Services

ENTWICKLER-ANLEITUNG · KONTAKTFORMULARE

Ein Astro-Kontaktformular verbinden

Behalte dein Astro-Frontend. Verbinde ein eingerichtetes Formular über den Same-Origin-Proxy der Kundenwebsite, lies sein Schema und sende JSON.

API-ReferenzOpenAPI JSON

Die öffentliche OpenAPI-Quelle ist für Coding-Agents und API-Werkzeuge direkt ohne Anmeldung lesbar. Sie beschreibt die öffentlichen Formularschema- und Anfrage-Endpunkte sowie authentifizierte Admin-Operationen. Ihr servers-Eintrag nennt Produktion; konfiguriere dein Werkzeug für andere Umgebungen mit der eingerichteten Backend-Origin.

01Mit persönlicher Einrichtung starten

Zugang erfolgt auf Einladung. Frage frühen Zugang für ein Projekt an; damit wird weder ein Konto erstellt noch ein Dienst aktiviert. Bevor dieses Beispiel an ein echtes Backend senden kann, müssen Workspace, Umgebung und eine aktive Formular-Umgebungszuordnung eingerichtet sein.

  1. Vereinbare Feldschlüssel, Typen, Grenzen, Sprachen, Spam-Schutz und Aufbewahrung. Das Schema unten setzt die Pflichtfelder email und message voraus; es ist keine bereits vorhandene Kontovorlage.
  2. Erlaube die exakte Website-Origin inklusive Protokoll und abweichendem Port: https://www.example.com ist nicht https://example.com. Richte Vorschau und Produktion getrennt ein.
  3. Hole die UUID der Formular-Umgebungszuordnung; das Backend ist immer app.site-services.squibble.ch. Die UUID ist eine öffentliche Routing-Kennung, gelegentlich Formular-Token genannt; sie ist weder geheim noch ein API-Key.
  4. Erstelle den API-Key der Formular-Umgebung. Dein Server sendet ihn als Authorization: Bearer mit – nie der Browser. Einen öffentlichen oder publizierbaren Key gibt es nicht: Der Key berechtigt für genau eine Formular-Umgebung und gilt nur von Server zu Server. Er wird einmalig angezeigt; speichere ihn als Geheimnis (zum Beispiel als CI/CD-Variable SITE_SERVICES_API_KEY) und committe ihn nie. Wo du beide Werte findest, zeigt der Proxy-Schritt unten.

Validierung und Speicherung sind im Quellcode implementiert. Der für den frühen Zugang geplante Kontaktformular-Ablauf umfasst API, Speicherung und E-Mail-Benachrichtigungen. Die operative E-Mail-Einrichtung steht aus; eine Posteingangsoberfläche ist separat geplant. Vereinbare und teste vor dem Kunden-Go-live, wie die zuständige Person legitime Anfragen erhält und bearbeitet.

Frühzeitigen Zugang anfragen →

02Proxy der Kundenwebsite einrichten

Diese nginx-Konfiguration gehört zur Kundenwebsite, die Astro ausliefert. Sie besteht aus drei Dateien: einer kleinen Datei auf http-Ebene mit dem Limit pro Besuchenden, einem Template mit den drei Locations (Schema, Einsendungen und Key-Prüfung), das dein Server-Block einbindet, und einem Snippet, das jede Location einbindet. Die markierten Zeilen enthalten die zwei Werte, die du einsetzt; die nummerierten Hinweise unter dem Template sagen, wo du sie findest. Der Backend-Host app.site-services.squibble.ch ist fest. Die exakten Locations begrenzen den Zugriff auf eine UUID und drei Routen. Der eigene Marketing-Ingress stellt nur seinen eingerichteten Submission-POST bereit; er ist kein Schema-Proxy für Kundenprojekte.

/etc/nginx/conf.d/site-services-limits.confnginx
# /etc/nginx/conf.d/site-services-limits.conf
# One bucket per visitor for the Site Services form routes, so a single visitor cannot use up
# the budget Site Services gives your whole proxy. Same budget as Site Services' own per-visitor limit.
limit_req_zone $binary_remote_addr zone=site_services_forms:10m rate=6r/m;

Das Limit gibt allen Besuchenden ein eigenes Budget am Proxy, damit eine einzelne Person nicht aufbraucht, was Site Services deinem ganzen Proxy erlaubt. Steht nginx hinter einem CDN oder Load Balancer, konfiguriere zuerst set_real_ip_from und real_ip_header: Sonst ist $remote_addr die Edge, und alle Besuchenden teilen sich ein Budget, hier und bei Site Services.

/etc/nginx/templates/site-services.locations.templatenginx
# Keep this file as /etc/nginx/templates/site-services.locations.template. The official nginx
# image renders it with envsubst at start to /etc/nginx/conf.d/site-services.locations, filling
# ${SITE_SERVICES_API_KEY} from the server environment; the key never reaches the browser or the build.
# No .conf suffix, so nginx does not load it at http level. Inside the CLIENT WEBSITE's HTTPS
# server block: include /etc/nginx/conf.d/site-services.locations;
location = /api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/schema {
    limit_except GET { deny all; }
    proxy_pass https://app.site-services.squibble.ch/api/v1/forms/<YOUR_FORM_ENVIRONMENT_UUID>/schema;
    include /etc/nginx/snippets/site-services-upstream.conf;
    # The schema is public; never forward a visitor's Authorization header.
    proxy_set_header Authorization "";
}
location = /api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/submissions {
    limit_except POST { deny all; }
    limit_req zone=site_services_forms burst=5 nodelay;
    limit_req_status 429;
    proxy_pass https://app.site-services.squibble.ch/api/v1/forms/<YOUR_FORM_ENVIRONMENT_UUID>/submissions;
    include /etc/nginx/snippets/site-services-upstream.conf;
    # Submissions require the form environment's API key, added here on the server.
    proxy_set_header Authorization "Bearer ${SITE_SERVICES_API_KEY}";
}
location = /api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/key {
    limit_except GET { deny all; }
    limit_req zone=site_services_forms burst=5 nodelay;
    limit_req_status 429;
    proxy_pass https://app.site-services.squibble.ch/api/v1/forms/<YOUR_FORM_ENVIRONMENT_UUID>/key;
    include /etc/nginx/snippets/site-services-upstream.conf;
    # The key check answers 204 when the key below works for this form; it never counts towards a ban.
    proxy_set_header Authorization "Bearer ${SITE_SERVICES_API_KEY}";
}
# Reject every other Site Services route; do not expose admin or auth.
location /api/site-services/ { return 404; }
  1. <YOUR_FORM_ENVIRONMENT_UUID>: die UUID der Formular-Umgebung, an allen sechs Stellen. Öffne im Site-Services-Admin unter app.site-services.squibble.ch Workspace → Formulare → dein Formular → Aufschaltungen → die Aufschaltung dieser Umgebung; die Karte „Verbindung“ zeigt sie als „Endpunkt-ID“ mit Kopier-Schaltfläche.
  2. ${SITE_SERVICES_API_KEY}: so stehen lassen; nginx setzt den Wert beim Start ein. Öffne auf derselben Aufschaltungsseite „API-Schlüssel“ → „API-Schlüssel erstellen“. Der Schlüssel erscheint einmalig im Dialog „API-Schlüssel kopieren“: speichere ihn als Server-Umgebungsvariable (oder CI/CD-Geheimnis) SITE_SERVICES_API_KEY.

Der API-Key bleibt auf dem Server

Die Locations für Einsendungen und Key-Prüfung fügen den Key hinzu, gelesen aus der Umgebungsvariable SITE_SERVICES_API_KEY beim Start von nginx. Nutzt du den Template-Mechanismus des nginx-Images nicht, gehören diese Zeilen in eine Include-Datei, die nur root lesen kann. Jeder andere serverseitige Proxy (ein Astro-SSR-Endpunkt, eine Edge-Funktion) macht dasselbe: Header ergänzen, Origin weiterreichen, X-Site-Services-Visitor-Ip auf die Adresse der Besuchenden setzen und nie einen Wert weitergeben, den die Besuchenden selbst gesendet haben, Key aus Client-Code und Build heraushalten.

Jede Location bindet das gemeinsame Upstream-Snippet unten ein. Es nennt das Backend für Host, X-Forwarded-Host und TLS-SNI, prüft sein Zertifikat und verwirft Cookies. Übernimm es unverändert. Ausserdem gibt es die Adresse der Besuchenden als X-Site-Services-Visitor-Ip weiter und überschreibt dabei, was die Besuchenden selbst gesendet haben, damit Limits und Sperren für einzelne Besuchende gelten statt für deinen ganzen Proxy.

/etc/nginx/snippets/site-services-upstream.confnginx
# /etc/nginx/snippets/site-services-upstream.conf
proxy_set_header Host app.site-services.squibble.ch;
proxy_set_header X-Forwarded-Host app.site-services.squibble.ch;
proxy_set_header Origin $http_origin;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Site-Services-Visitor-Ip $remote_addr;
proxy_set_header Cookie "";
proxy_ssl_server_name on;
proxy_ssl_name app.site-services.squibble.ch;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_intercept_errors off;
proxy_cache off;

Der Browser ruft /api/site-services/… auf seiner eigenen Origin auf; nginx leitet über geprüftes TLS an /api/v1/… weiter. Host und TLS-SNI müssen das Backend benennen, nicht die Kundenwebsite. Die eingehende Origin bleibt erhalten; ersetze sie nie durch eine erlaubte Konstante. Antwortstatus, JSON und Retry-After werden ohne Abfangen weitergereicht.

Dieses Beispiel setzt voraus, dass nginx öffentliches HTTPS selbst terminiert und das System-CA-Bundle am gezeigten Linux-Pfad verwendet. Leite öffentliches HTTP auf HTTPS um. Bei TLS-Terminierung am Loadbalancer musst du vertrauenswürdige Proxys und Real-IP konfigurieren und das externe Protokoll ausschliesslich von dort ableiten; ungeprüfte Client-Header weiterzureichen ist unsicher. Setze das nginx-Body-Limit mindestens auf das vereinbarte Formularlimit; zusätzlich gilt ein globales Backend-Limit. Rein statisches Hosting benötigt einen entsprechenden Server-/Edge-Proxy. Astro dev und preview installieren diese nginx-Routen nicht.

03Vertrag lesen, dann Nutzdaten aufbauen

GET/api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/schema

Ein erfolgreicher GET liefert ein unverpacktes JSON Schema nach Draft 2020-12, keine data/meta-Hülle. Es ist öffentlich und 60 Sekunden cachebar. Diese illustrative Antwort entspricht den vereinbarten Beispielfeldern; lies immer dein tatsächlich eingerichtetes Schema.

Beispielschema · 43 Zeilen
Antwort auf GET …/schemaJSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Contact",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254,
      "x-labels": {
        "en": "Email",
        "de": "E-Mail"
      },
      "x-placeholders": {}
    },
    "message": {
      "type": "string",
      "maxLength": 2000,
      "x-labels": {
        "en": "Message",
        "de": "Nachricht"
      },
      "x-placeholders": {}
    }
  },
  "required": [
    "email",
    "message"
  ],
  "additionalProperties": false,
  "x-site-services": {
    "locales": [
      "en",
      "de"
    ],
    "honeypot_field": "website",
    "started_at_field": "started_at",
    "min_elapsed_ms": 3000,
    "max_elapsed_ms": 3600000,
    "max_body_bytes": 8192,
    "form_key": "contact"
  }
}

properties und required beschreiben nur fachliche Felder. locale und die beiden Spam-Schutz-Felder sind Transportmetadaten auf oberster Ebene und werden vor der Feldvalidierung entfernt. Lies ihre Namen und Zeitgrenzen aus x-site-services. Validiere bei additionalProperties: false nur die fachlichen Felder, nicht den gesamten Transport-Body. Das Backend bleibt massgeblich.

POST/api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/submissionsContent-Type: application/json

Body von POST …/submissionsJSON
{
  "email": "alex@example.com",
  "message": "Können wir sprechen?",
  "locale": "de",
  "website": "",
  "started_at": 1790000000000
}

Dieser Zeitstempel dient nur der Illustration: Erfasse Date.now(), wenn das Browserformular bereit ist, niemals beim Build oder erst beim Absenden. Für menschliche Besucher bleibt der Honeypot leer. Sende flaches JSON, weder { data: … } noch FormData oder URL-kodiertes HTML. Konvertiere Boolean- und Integer-Werte explizit; erforderliche Boolean-Felder müssen true sein. Unbekannte fachliche Schlüssel scheitern an der Validierung.

04Kleinen Browser-Transport in Astro verwenden

Lade dieses Modul als src/lib/contact-form.js in dein Astro-Projekt und importiere seine beiden Funktionen in einem clientseitigen <script> deiner .astro-Komponente, nicht im Build-Time-Frontmatter. Der angezeigte Quelltext ist exakt die herunterladbare Datei, die von den Browsertests dieser Anleitung ausgeführt wird. Es ist ein Transportmodul, keine vollständige Formularkomponente und kein JSON-Schema-Validator.

contact-form.js herunterladen

src/lib/contact-form.jsJavaScript
// Browser transport only. The caller owns the form UI and catches rejected promises.
export async function loadContactForm(id, locale) {
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
    throw new Error('Use the provisioned form-environment UUID');
  }
  const base = `/api/site-services/forms/${id}`;
  const response = await fetch(`${base}/schema`, {
    credentials: 'omit', signal: AbortSignal.timeout(20000),
  });
  if (!response.ok) throw new Error(`Schema unavailable: ${response.status}`);
  const schema = await response.json(); // Raw JSON Schema, not result.data.
  const rules = schema['x-site-services'];
  if (!rules?.locales?.includes(locale)) throw new Error('Unsupported form locale');
  return { base, schema, rules, locale, startedAt: Date.now() };
}

export async function submitContactForm(session, fields, honeypot = '') {
  const { base, rules, locale, startedAt } = session;
  const elapsed = Date.now() - startedAt;
  if (rules.time_trap_enabled !== false) {
    if (elapsed < rules.min_elapsed_ms) return { kind: 'wait' };
    if (elapsed > rules.max_elapsed_ms) return { kind: 'expired' };
  }
  const body = JSON.stringify({
    ...fields, locale,
    [rules.honeypot_field]: honeypot,
    [rules.started_at_field]: startedAt,
  });
  if (new TextEncoder().encode(body).length > rules.max_body_bytes) {
    return { kind: 'failed', status: 413 };
  }
  const response = await fetch(`${base}/submissions`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    credentials: 'omit', body, signal: AbortSignal.timeout(20000),
  });
  const result = await response.json();
  if (response.status === 202 && result?.data?.status === 'accepted') {
    return { kind: 'accepted' };
  }
  if (response.status === 422 && result?.errors && typeof result.errors === 'object') {
    return { kind: 'invalid', errors: result.errors };
  }
  return { kind: 'failed', status: response.status };
}
  1. Rufe bei der Browser-Initialisierung einmal await loadContactForm(publicFormEnvironmentId, "de") (oder "en") auf und behalte die zurückgegebene Sitzung. Die öffentliche UUID stammt aus deiner Komponentenkonfiguration. Gleiche session.schema mit gerenderten Feldschlüsseln, Typen und Einschränkungen ab; bei Einrichtungsfehlern bleibt Senden deaktiviert.
  2. Verwende im Submit-Handler preventDefault(), prüfe native Validität, verhindere paralleles Senden und rufe await submitContactForm(session, { email: emailInput.value, message: messageInput.value }, honeypotInput.value) auf. Verwende deine eigenen Input-Referenzen und tatsächlichen Schema-Schlüssel. Nimm den Honeypot mit tabindex="-1", aria-hidden="true" und autocomplete="off" am versteckten Wrapper/Input entsprechend aus Tastatur- und Accessibility-Abläufen.
  3. Behandle jedes Ergebnis unten und fange Netzwerk-, Timeout- und Nicht-JSON-Fehler ab. Beende den Busy-Zustand immer in finally. Behalte Eingaben bei Fehlern, nutze einen aria-live-Status, ordne Fehler bekannten Feldern zu und fokussiere das erste ungültige Feld oder den Status. Rendere Meldungen als Text, niemals als Server-HTML. Erkläre ohne JavaScript, dass Senden nicht verfügbar ist, und biete eine echte Kontaktalternative; natives HTML-Absenden wird von diesem JSON-Endpunkt nicht unterstützt.

05Bestätigung und Fehler präzise behandeln

Antwort 202 AcceptedJSON
{ "data": { "status": "accepted" }, "meta": {} }

Nur HTTP 202 mit data.status === "accepted" ergibt kind: "accepted". Dieselbe Antwort gilt für still erkannten Spam, etwa einen gefüllten Honeypot oder zu schnelles Absenden. Sie beweist weder legitime Speicherung noch E-Mail-Zustellung, menschliche Antwort, Kontoerstellung oder Einladung.

HTTP 422 verwendet application/problem+json (RFC 9457). Lies die errors-Map auf oberster Ebene, nicht data.errors. Unten steht ein Ausschnitt des errors-Members, nicht das gesamte Problemdokument; Meldungen sind lokalisiert und konfigurierbar.

Antwort 422 · errors-MemberJSON
{
  "errors": {
    "email": [
      {
        "code": "required",
        "message": "Dieses Feld ist erforderlich."
      }
    ]
  }
}

Ergebnisarten

kind: "accepted"
Zeige «Anfrage angenommen» und verhindere erneutes Senden. Still erkannter Spam erhält dieselbe Antwort; sie beweist also weder Speicherung noch Zustellung.
kind: "invalid"
Ordne bekannte Feldschlüssel deiner Oberfläche zu. Ein Zeitstempelfehler (expired, required oder invalid), ein locale-Fehler oder ein unbekannter Schlüssel benötigt Sitzungs- oder Konfigurationswiederherstellung statt unsichtbarer Feldmarkierung.
kind: "wait"
Warte, bis min_elapsed_ms verstrichen ist; datiere den Zeitstempel nie zurück.
kind: "expired"
Biete einen ausdrücklichen Neustart über loadContactForm an, behalte Eingaben und warte die neue Mindestzeit. Sende nie automatisch erneut.
kind: "failed"
Die Anfrage wurde abgelehnt; status enthält den HTTP-Code unten. Korrigiere Konfiguration oder Nutzdaten statt blind zu wiederholen.

HTTP-Status bei kind: "failed"

StatusBedeutung und Vorgehen
400Fehlerhaftes JSON. Korrigiere die Nutzdaten.
401Der Proxy hat keinen gültigen API-Key mitgesendet. Der code des Problems nennt den Grund: unauthorized (fehlt oder unbekannt), api_key_revoked, api_key_expired oder api_key_wrong_form_environment. Korrigiere die Serverumgebung sofort (siehe Warnung unten).
403Inaktive Zuordnung, nicht erlaubte oder fehlende Origin, eine Sperre einzelner Besuchender nach gefülltem Honeypot oder eine Sperre der Proxy-IP-Adresse nach wiederholt unbekannten Keys.
404Unbekannte UUID der Formular-Umgebung.
413Body grösser als das vereinbarte Formularlimit.
415Falscher Medientyp; sende application/json.
429Zu viele Anfragen – von einer besuchenden Person (an deinem Proxy oder bei Site Services), für den Key oder für das Formular. Pausiere und beachte Retry-After, falls vorhanden.
5xxDienstfehler. Behalte Eingaben und biete einen späteren Versuch an.

Prüfe den Key vor dem Go-live: Nur ein unbekannter Key kann das Formular sperren

Ein fehlender, vertippter oder nie ausgestellter Key zählt als Fehlversuch: Standardmässig sperren zehn davon innert zehn Minuten die IP-Adresse des Proxys für eine Stunde (403), und das blockiert das Formular für alle Besuchenden. Ein widerrufener oder abgelaufener Key oder einer für eine andere Formular-Umgebung antwortet mit 401 und eigenem code (api_key_revoked, api_key_expired oder api_key_wrong_form_environment) und sperrt nie. Wer den Honeypot wiederholt füllt, wird allein gesperrt. Die Key-Prüfung in der Prüfliste zählt keine Fehlversuche: Führe sie nach jedem Deploy und jeder Key-Rotation aus.

Das minimale Modul liefert status, nicht Retry-After; ergänze die Header-Auswertung im UI-Adapter, falls du zeitgesteuerte Wiederholungen einbaust. Ein abgelehntes Promise bedeutet, dass die Annahme nicht bestätigt werden konnte. Behalte Eingaben und biete manuelle Wiederherstellung; die Anfrage könnte bereits angekommen sein, automatische Wiederholung kann sie duplizieren.

06Auf der tatsächlichen Kunden-Origin prüfen

Die automatisierten Browserprüfungen dieser Anleitung führen das herunterladbare Modul gegen simulierte API-Antworten aus. Sie stellen keine Live-Verbindung von nginx zu Rails her und beweisen keine Zustellung. Schema und Anfragevertrag sind auf die öffentlichen Backend-Controller, den Schema-Generator und ausführende Request-Specs zurückgeführt.

  1. Prüfe nach der Einrichtung nginx-Konfiguration und Zertifikate.
  2. Rufe nach jedem Deploy und jeder Key-Rotation curl -i https://<kunden-origin>/api/site-services/forms/<YOUR_FORM_ENVIRONMENT_UUID>/key auf und erwarte 204. Ein 401 nennt die Ursache in seinem code; diese Prüfung zählt nie zu einer Sperre.
  3. Lade das Schema per GET von der Kunden-Origin und gleiche jedes gerenderte Feld und Limit ab.
  4. Prüfe, dass ein fremder /api/site-services/-Pfad 404 liefert.
  5. Sende nach der Mindestzeit eine gültige Anfrage und prüfe die exakte 202-Hülle. Bestätige den legitimen gespeicherten Datensatz unabhängig über den vereinbarten Betreiberablauf.
  6. Prüfe nach Ablauf der Zeitsperre, dass ein bekanntes ungültiges Feld 422 liefert.
  7. Ein 401 mit code unauthorized heisst, dass der Key in der Serverumgebung fehlt oder vertippt ist: Halte an, korrigiere ihn und wiederhole die Key-Prüfung, bevor du wieder Einsendungen sendest.
  8. Prüfe, dass fremde oder fehlende Origins abgewiesen werden, abgelaufene Sitzungen Eingaben behalten und Netzwerkfehler nichts löschen.
  9. Prüfe Tastatur, Mobilgeräte und Fehleransagen.
  10. Vereinbare Datenschutzhinweise und den operativen Bearbeitungsweg vor dem Go-live.