Lead-API

Diese Seite richtet sich an Entwickler bei Lieferanten, die uns Leads übergeben. Sie beschreibt, wie eine Anbindung abläuft, welche Felder wir verarbeiten und woran Anbindungen erfahrungsgemäß scheitern.

1. Zugang

Basis-URL für die Produktion:

Sie erhalten von uns ein Zugangsgeheimnis, das Sie bei jeder Anfrage im Header x-lead-secret mitsenden. Es bestimmt zugleich, unter welcher Quelle Ihre Leads verbucht werden — ein Feld quelle im Rumpf wird ignoriert. Damit kann niemand unter fremder Herkunft einliefern, auch nicht versehentlich.

• Die Übergabe des Geheimnisses erfolgt über einen vereinbarten sicheren Kanal, nie per unverschlüsselter E-Mail.
• Niemals als URL-Parameter (?token=…): URLs werden protokolliert; ein so übergebenes Geheimnis gilt als kompromittiert und wird gewechselt.
• Halten Sie es konfigurierbar, nicht einkompiliert — wir können es jederzeit wechseln.
• Senden Sie keinen Cookie-, Origin- oder Referer-Header. Die Anlieferung ist ein reiner Server-zu-Server-Aufruf.

Was der Zugang erlaubt — und was nicht

Erlaubt: Leads Ihrer vereinbarten Quelle anliefern; denselben Lead mit derselben Lead-ID erneut senden, um Angaben zu ergänzen.

Nicht vorgesehen: Leads anderer Herkunft einliefern · bestehende Leads ändern, löschen oder deren Status setzen · Bestandsdaten oder den Bearbeitungsstand abfragen · ein Benutzerkonto im Portal. Lieferanten erhalten kein Login — unter anderem, weil ein Konto durch fremde Anmeldeversuche gesperrt werden und Ihre Lieferung dadurch stillstehen könnte.

Liefergeschwindigkeit

Es gibt keinen Sammel-Endpunkt — ein Aufruf, ein Lead. Die Annahme ist auf 60 Aufrufe pro Minute begrenzt; darüber antwortet der Endpunkt mit 429. Für Altbestände und Nachlieferungen ist die Dateilieferung vorgesehen, nicht ein schnellerer Takt.

• Bei 5xx oder Zeitüberschreitung mit wachsendem Abstand wiederholen, höchstens 5 Versuche.
• Bei 4xx nicht wiederholen — die Anfrage ist inhaltlich falsch, eine Wiederholung ändert daran nichts.
• Bei 429 warten und danach langsamer senden.

2. Einen Lead liefern

POST https://erp.sol-living.de/api/v2/lead-eingang
Content-Type: application/json; charset=utf-8
x-lead-secret: <Ihr Zugangsgeheimnis>

Beispiel

curl -sS -X POST "https://erp.sol-living.de/api/v2/lead-eingang" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "x-lead-secret: $LEAD_SECRET" \
  -d '{
    "leadId":    "AB-2026-000123",
    "vorname":   "Max",
    "nachname":  "Mustermann",
    "telefon":   "+491701234567",
    "email":     "max.mustermann@example.de",
    "strasse":   "Hauptstraße",
    "hausnummer":"12a",
    "plz":       "06846",
    "ort":       "Dessau-Roßlau"
  }'

Alle Werte als JSON-Strings senden. Das gilt besonders für die Postleitzahl: als Zahl geschrieben verliert 06846 die führende Null.

Antworten

3. Felder

4. Was nach dem Eingang passiert

Dublettenprüfung

Geprüft wird zuerst gegen Ihre leadId, danach gegen E-Mail und Telefonnummer (normalisiert, quellenübergreifend). Ein erkannter Doppelgänger wird kein zweiter Lead — Ihre Angaben ergänzen den vorhandenen. Sie erhalten duplicate mit der dealId des bestehenden Vorgangs.

Zuordnung

Die Quelle ergibt sich aus Ihrem Zugang. Der Lead landet unmittelbar in der Bearbeitungsliste des Callcenters und wird von dort einem Vertriebspartner zugewiesen — abhängig von Postleitzahl, Kapazität und Guthaben des Partners. „Angenommen" heißt nicht „sofort bearbeitet".

Reklamation

Gründe, Fristen und Meldeweg werden bei der Einrichtung vereinbart und richten sich nach dem Reklamationsgrund, nicht nach dem Lieferdatum. Ein reklamierter Lead wird Ihnen gemeldet.

5. Rückmeldung (Webhook)

Es gibt keine Abfrage-Schnittstelle — Sie fragen bei uns nichts ab. Stattdessen melden wir Ihnen, was aus einem gelieferten Lead geworden ist, sobald es feststeht. Sie hinterlegen dafür eine Adresse, wir senden dorthin.

Die Rückmeldung ist freiwillig. Ohne hinterlegte Adresse ändert sich für Sie nichts; Sie liefern wie bisher und erhalten Rückmeldungen auf dem vereinbarten Weg.

Was Sie hinterlegen

Nennen Sie Ihrem Ansprechpartner eine https-Adresse. Sie erhalten daraufhin ein zweites Geheimnis — das Signatur-Geheimnis. Es ist nicht dasselbe wie Ihr Zugangsgeheimnis:

Beide lassen sich unabhängig voneinander wechseln. Wer eines tauscht, muss das andere nicht anfassen.

Wie eine Meldung aussieht

POST https://ihre-adresse.example/hook
Content-Type: application/json
User-Agent: SolLiving-LeadWebhook/1
X-SolLiving-Ereignis: lead.terminiert
X-SolLiving-Signatur: sha256=<HMAC des Rumpfes>

{
  "ereignis":    "lead.terminiert",
  "externe_id":  "AB-2026-000123",
  "lead_id":     "cmf3k2p9x0001abcd",
  "quelle":      "IHRE_QUELLE",
  "termin_at":   "2026-08-20T09:00:00.000Z",
  "gemeldet_at": "2026-08-08T14:32:10.412Z"
}

externe_id ist Ihre ID aus dem Feld leadId der Lieferung — damit ordnen Sie die Meldung zu. lead_id ist unsere interne ID; nennen Sie sie bei Rückfragen, dann ist der Vorgang eindeutig.

Welche Ereignisse

Signatur prüfen

Der Wert in X-SolLiving-Signatur ist ein HMAC-SHA256 über den rohen Rumpf, mit Ihrem Signatur-Geheimnis als Schlüssel, hexadezimal, mit dem Präfix sha256=.

// Node.js
const erwartet = 'sha256=' + require('crypto')
  .createHmac('sha256', SIGNATUR_GEHEIMNIS)
  .update(rohBody)          // der unveränderte Rumpf, NICHT das geparste Objekt
  .digest('hex');

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $rohBody, $signaturGeheimnis);

Vergleichen Sie zeitkonstant (crypto.timingSafeEqual bzw. hash_equals). Stimmt die Signatur nicht, verwerfen Sie die Meldung.

Was Ihre Seite antworten muss

• Ein Status 2xx gilt als angenommen. Alles andere gilt als Fehlversuch.
• Antworten Sie innerhalb von 8 Sekunden. Danach brechen wir ab und werten es als Fehlversuch. Nehmen Sie die Meldung an und verarbeiten Sie sie hinterher.
• Der Rumpf Ihrer Antwort ist uns gleich — wir werten nur den Status.

Wiederholung und doppelte Meldungen

• Ein Fehlversuch wird automatisch wiederholt, im 5-Minuten-Takt, bis Ihre Seite ihn annimmt. Sie müssen nichts nachfordern.
• Eine angenommene Meldung senden wir nicht erneut.
• Trotzdem: bauen Sie Ihre Seite doppelfest. Nimmt sie eine Meldung an und Ihre Antwort geht auf dem Rückweg verloren, gilt sie bei uns als Fehlversuch und kommt noch einmal. Schlüsseln Sie auf externe_id + ereignis.
• Nach 20 Fehlversuchen in Folge ruht die Zustellung, damit eine tote Adresse nicht dauerhaft angefahren wird. Sie wird wieder aufgenommen, sobald die Adresse korrigiert oder der Weg neu eingeschaltet wird — melden Sie sich in dem Fall bei Ihrem Ansprechpartner.

Vor dem Scharfschalten

Wir können eine Probemeldung (lead.test) auslösen, bevor ein echter Lead durchläuft. Sie hat denselben Signatur- und Kopfzeilen-Aufbau wie eine echte Meldung — ein grüner Test sagt deshalb wirklich etwas über den Betrieb aus. Bitten Sie Ihren Ansprechpartner darum, sobald Ihre Seite steht.

6. Reklamationen

Beanstanden wir einen Lead, melden wir Ihnen das mit einem eigenen Code (SL-REK-…). Sie können darauf antworten — annehmen oder bestreiten.

Die Codes

Die Nummern werden nie neu vergeben. Ein Code, den Sie heute erhalten, bedeutet in zwei Jahren dasselbe. Neue Sachverhalte bekommen neue Nummern.

Wie eine Reklamation ankommt

X-SolLiving-Ereignis: lead.reklamiert

{
  "ereignis":    "lead.reklamiert",
  "externe_id":  "AB-2026-000123",
  "lead_id":     "cmf3k2p9x0001abcd",
  "quelle":      "IHRE_QUELLE",
  "termin_at":   null,
  "gemeldet_at": "2026-08-08T14:32:10.412Z",
  "rekla": {
    "code":              "SL-REK-001",
    "bedeutung":         "Dublette — derselbe Kontakt wurde bereits geliefert",
    "begruendung":       "Kontakt lag seit 04.08. unter AB-2026-000098 vor",
    "frist_bis":         "2026-08-12T00:00:00.000Z",
    "erstattungsfaehig": true
  }
}

Antworten

POST https://erp.sol-living.de/api/v2/lead-eingang/reklamation-antwort
Content-Type: application/json; charset=utf-8
x-lead-secret: <Ihr Zugangsgeheimnis>

{
  "lead_id":     "cmf3k2p9x0001abcd",
  "code":        "SL-REK-001",
  "antwort":     "bestritten",
  "begruendung": "Erstlieferung durch uns am 04.08., Protokoll liegt bei."
}

Beachten Sie: hier gilt das Zugangsgeheimnis (x-lead-secret) wie beim Liefern — nicht das Signatur-Geheimnis. Das dient nur dazu, unsere Meldungen zu prüfen.

Antworten: 200 mit {"status":"received"} bei Annahme, 200 mit {"status":"rejected","grund":"…"} wenn die Angaben nicht passen, 401 bei ungültigem Zugang. Ein rejected ist inhaltlich — wiederholen hilft nicht, ohne die Angaben zu korrigieren.

7. Vor dem ersten echten Lead

• Quellen-Schlüssel, Abrechnungsart und Preis vereinbart
• Reklamationsgründe und Fristen vereinbart
• Zugangsgeheimnis erhalten und sicher hinterlegt (konfigurierbar, nicht einkompiliert)
• Erwartete Liefermenge je Tag abgestimmt
• Technischer Ansprechpartner auf beiden Seiten benannt
• Testlieferung durchgeführt und Antwort geprüft
• Wiederholungslogik gebaut: 5xx mit Abstand, 4xx nie, 429 langsamer
• Datenschutz geklärt: Herkunft und Einwilligung der Leads nachweisbar

Zusätzlich, falls Sie Rückmeldungen möchten (Abschnitt 5):

• https-Adresse genannt und Signatur-Geheimnis sicher hinterlegt
• Signaturprüfung über den rohen Rumpf gebaut, zeitkonstanter Vergleich
• Antwort unter 8 Sekunden — Verarbeitung erst nach der Annahme
• Doppelte Meldungen abgefangen (Schlüssel: externe_id + ereignis)
• Probemeldung lead.test empfangen und Signatur erfolgreich geprüft