Leads von Ihrer Website empfangen

Anleitung zur Integration des Formulars Ihrer Website mit ReactiveCRM: Erfassung von Formularübermittlungen als Leads, Senden von Marketing-Attributionsereignissen und Überprüfung der Ergebnisse.

1. Überblick

Das empfohlene Szenario besteht aus zwei Anfragen:

Die Website sendet die Formulardaten an ihr eigenes Backend.
Das Website-Backend erstellt einen Lead in der CRM über POST /api/leads/create.
Nach erfolgreicher Erstellung sendet das Backend das Marketing-Ereignis lead_submitted über POST /api/dashboard/marketing/events und übergibt dabei die erhaltene leadId.
Die CRM speichert UTM-Tags, Werbe-IDs und Referrer für die Marketing-Attribution.

text

Website-Formular
    |
    v
Website-Backend / serverseitiger Proxy
    |  POST /api/leads/create
    v
ReactiveCRM -> leadId
    |  POST /api/dashboard/marketing/events
    v
Marketing-Attribution und Dashboard

Senden Sie CRM-JWT und Geheimnisse nicht direkt aus dem Browser. Verwenden Sie das Website-Backend oder eine Serverless-Funktion, damit das CRM-Token und interne IDs niemals an den Besucher gelangen.

2. Authentifizierung und Basis-URL

Alle Anfragen werden im Kontext des entsprechenden Mandanten ausgeführt und erfordern eine CRM-Autorisierung:

http

Authorization: Bearer <CRM_ACCESS_TOKEN>
Content-Type: application/json

In den Beispielen wird verwendet:

text

CRM_BASE_URL=https://crm.example.com

Ersetzen Sie dies durch die URL Ihrer Umgebung.

3. Auf der Website zu sammelnde Daten

Lead-Daten

Für die Lead-Erstellung unterstützt die API:

Feld	Erforderlich	Beschreibung
`message`	nein	Nachricht oder Anfragetext aus dem Formular
`ownerId`	ja	UUID des für den Lead verantwortlichen CRM-Benutzers
`authorId`	ja	UUID des CRM-Benutzers, der den Lead erstellt hat
`clientId`	nein	UUID eines vorhandenen Kunden
`contactId`	nein	UUID eines vorhandenen Kontakts
`leadSourceId`	nein	UUID eines Knotens im Lead-Quellen-Baum
`statusId`	nein	UUID des Anfangsstatus
`quality`	nein	`HOT`, `WARM`, `COOL` oder `COLD`

ownerId und authorId sind UUIDs von CRM-Benutzern. Erlauben Sie dem Besucher bei einem öffentlichen Formular auf der Website nicht, diese Werte selbst zu setzen: Das Backend sollte sie aus der Integrationskonfiguration übernehmen.

Daten des Marketing-Besuchs

Speichern Sie vor dem Absenden des Formulars Folgendes in Cookies, Session Storage oder im Backend:

utm_source → utmSource
utm_medium → utmMedium
utm_campaign → utmCampaign
utm_content → utmContent
utm_term → utmTerm
gclid — Google Ads-Kennung
fbclid — Meta/Facebook-Kennung
URL der Landingpage → landingUrl
URL der vorherigen Seite → referrer
Eigene Besucher- und Sitzungskennungen → visitorId, sessionId

Speichern Sie die Werte beim ersten Besuch und überschreiben Sie sie nicht mit leeren Parametern bei der Navigation auf der Website.

4. Lead erstellen

Endpunkt

http

POST /api/leads/create

Beispielanfrage

bash

curl -X POST "$CRM_BASE_URL/api/leads/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Website-Anfrage: Beratungsanfrage",
    "ownerId": "11111111-1111-1111-1111-111111111111",
    "authorId": "11111111-1111-1111-1111-111111111111",
    "quality": "WARM"
  }'

Beispielantwort `201 Created`

json

{
  "id": "22222222-2222-2222-2222-222222222222",
  "message": "Website-Anfrage: Beratungsanfrage",
  "quality": "WARM",
  "dealId": null,
  "createdAt": "2026-09-05T20:00:00Z",
  "updatedAt": "2026-09-05T20:00:00Z",
  "version": 0,
  "author": {
    "id": "11111111-1111-1111-1111-111111111111",
    "firstName": "CRM",
    "lastName": "Bot"
  },
  "owner": {
    "id": "11111111-1111-1111-1111-111111111111",
    "firstName": "CRM",
    "lastName": "Bot"
  }
}

Speichern Sie die id aus der Antwort: Dieser Wert wird im Feld leadId des Marketing-Ereignisses übergeben.

5. Ereignis „Lead gesendet“ senden

Endpunkt

http

POST /api/dashboard/marketing/events

Beispielanfrage

bash

curl -X POST "$CRM_BASE_URL/api/dashboard/marketing/events" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "lead_submitted",
    "occurredAt": "2026-09-05T20:00:00Z",
    "visitorId": "visitor-8b7f",
    "sessionId": "session-31ac",
    "leadId": "22222222-2222-2222-2222-222222222222",
    "externalId": "site-form-submit-20260905-000123",
    "source": "website",
    "channel": "paid",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-consulting",
    "utmContent": "banner-a",
    "utmTerm": "crm consultation",
    "gclid": "EAIaIQobChMI-example",
    "landingUrl": "https://www.example.com/consultation",
    "referrer": "https://www.google.com/",
    "metadata": {
      "formName": "consultation",
      "pageType": "landing"
    }
  }'

Beispielantwort

json

{
  "accepted": true,
  "duplicate": false,
  "eventId": "33333333-3333-3333-3333-333333333333"
}

Wenn dieselbe externalId bereits für dieses Paar aus source und Mandant verarbeitet wurde, gibt die API eine erfolgreiche Antwort mit duplicate: true zurück. Betrachten Sie dies als Erfolg, nicht als Fehler, und erstellen Sie keinen zweiten Lead.

6. Beispiel für einen Server-Handler

Nachfolgend ein vereinfachtes Beispiel in Node.js. Die Formulardaten sollten an das Website-Backend gesendet werden, nicht direkt vom Browser an die CRM.

async function createWebsiteLead(form, attribution) {
  const headers = {
    Authorization: `Bearer ${process.env.CRM_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  };

  const leadResponse = await fetch(
    `${process.env.CRM_BASE_URL}/api/leads/create`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        message: form.message || `Website-Anfrage: ${form.subject || 'kein Betreff'}`,
        ownerId: process.env.CRM_LEAD_OWNER_ID,
        authorId: process.env.CRM_LEAD_AUTHOR_ID,
        quality: 'WARM',
      }),
    },
  );

  if (!leadResponse.ok) {
    throw new Error(`CRM-Lead-Erstellung fehlgeschlagen: ${leadResponse.status}`);
  }

  const lead = await leadResponse.json();
  const externalId = `website-${form.requestId}`;

  const eventResponse = await fetch(
    `${process.env.CRM_BASE_URL}/api/dashboard/marketing/events`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        eventType: 'lead_submitted',
        occurredAt: new Date().toISOString(),
        visitorId: attribution.visitorId,
        sessionId: attribution.sessionId,
        leadId: lead.id,
        externalId,
        source: 'website',
        channel: attribution.channel || 'direct',
        utmSource: attribution.utmSource,
        utmMedium: attribution.utmMedium,
        utmCampaign: attribution.utmCampaign,
        utmContent: attribution.utmContent,
        utmTerm: attribution.utmTerm,
        gclid: attribution.gclid,
        fbclid: attribution.fbclid,
        landingUrl: attribution.landingUrl,
        referrer: attribution.referrer,
        metadata: { formName: form.formName || 'website' },
      }),
    },
  );

  if (!eventResponse.ok) {
    // Lead wurde bereits erstellt. Stellen Sie das Ereignis in eine Warteschlange und wiederholen Sie es
    // mit derselben externalId, anstatt einen zweiten Lead zu erstellen.
    throw new Error(`CRM-Marketing-Ereignis fehlgeschlagen: ${eventResponse.status}`);
  }

  return { leadId: lead.id, marketingEvent: await eventResponse.json() };
}

7. Idempotenz und Wiederholungen

Generieren Sie für jede Formularübermittlung eine stabile externalId. Verwenden Sie z. B. eine UUID, die vor der ersten Anfrage erstellt wurde, oder eine eindeutige requestId des Formulars.
Wiederholen Sie bei einem Netzwerkfehler die Anfrage für das Marketing-Ereignis mit derselben externalId.
Generieren Sie bei einer Wiederholung keine neue externalId: Dies würde ein doppeltes Ereignis erzeugen.
Wenn die Anfrage zur Lead-Erstellung aufgrund eines Timeouts mit unbestimmtem Ergebnis endet, erstellen Sie nicht blind einen neuen Lead. Verwenden Sie zunächst Ihre eigene requestId und einen Deduplizierungsmechanismus im Website-Backend oder suchen Sie den erstellten Lead in der CRM.
Ein Fehler beim Senden des Ereignisses sollte den Benutzer nicht dazu zwingen, das Formular erneut zu senden, ohne das Ergebnis der Lead-Erstellung zu überprüfen.

8. Personenbezogene Daten und metadata

Es ist verboten, personenbezogene Daten und Formularinhalte in metadata zu übermitteln:

E-Mail
Telefon
Vor- und Nachname
Adresse
Nachrichtentext
Cookies mit personenbezogenen Kennungen

Personenbezogene Daten dürfen nur in den dafür vorgesehenen CRM-Entitäten übermittelt werden — z. B. in zuvor erstellten contactId/clientId. Belassen Sie in metadata nur technische Attribute: Formularname, Seitentyp, Bannervariante usw.

9. Typische Antworten und Fehler

HTTP	Situation	Maßnahme
`201`	Lead erstellt	Speichern Sie `id` und senden Sie `lead_submitted`
`200` + `duplicate: false`	Ereignis angenommen	Speichern Sie `eventId` im Integrationsprotokoll
`200` + `duplicate: true`	Ereignis bereits angenommen	Als verarbeitet betrachten; nicht erneut senden
`400`	Ungültige Daten oder personenbezogene Daten in `metadata`	Daten korrigieren; Wiederholung ohne Änderungen hilft nicht
`401`	Ungültiges oder fehlendes Token	CRM-Token im Backend aktualisieren
`403`	Token hat keine Berechtigung für die Operation	Rolle und Mandant prüfen
`5xx` / Timeout	Vorübergehender CRM- oder Netzwerkfehler	Mit derselben `externalId` wiederholen; für Leads eine Warteschlange verwenden

10. Ergebnisse im CRM überprüfen

Nach der Integration prüfen Sie:

Der Lead wird über GET /api/leads/{id} oder in der Liste GET /api/leads/paged angezeigt.
Besitzer, Autor und Erstellungszeitpunkt des Leads sind korrekt.
Die Antwort des Marketing-Ereignisses bei der ersten Sendung enthält duplicate gleich false.
Das erneute Senden derselben Anfrage gibt duplicate: true zurück.
Im Marketing-Dashboard erscheinen die Daten im richtigen Zeitraum, Kanal und Kampagne.

Erstellten Lead abrufen

bash

curl "$CRM_BASE_URL/api/leads/$LEAD_ID" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Leads für Listen oder Abgleiche abrufen

bash

curl "$CRM_BASE_URL/api/leads/paged?page=0&size=20&createdAtFrom=2026-09-05T00:00:00Z&createdAtTo=2026-09-05T23:59:59Z&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Der Parameter page beginnt bei 0; der Standardwert für size ist 20. Um Leads von der Website zu erhalten, verwenden Sie zusätzlich die Filter message, createdAtFrom/createdAtTo, contactEmail oder search, falls die entsprechenden Daten bereits in der CRM gespeichert sind.

Leads von Ihrer Website empfangen

1. Überblick

2. Authentifizierung und Basis-URL

3. Auf der Website zu sammelnde Daten

Lead-Daten

Daten des Marketing-Besuchs

4. Lead erstellen

Endpunkt

Beispielanfrage

Beispielantwort 201 Created

5. Ereignis „Lead gesendet“ senden

Endpunkt

Beispielanfrage

Beispielantwort

6. Beispiel für einen Server-Handler

7. Idempotenz und Wiederholungen

8. Personenbezogene Daten und metadata

9. Typische Antworten und Fehler

10. Ergebnisse im CRM überprüfen

Erstellten Lead abrufen

Leads für Listen oder Abgleiche abrufen

Beispielantwort `201 Created`