Website-Anfragen automatisch in HERO übernehmen: So funktioniert die Lead API

Was die Lead API macht

HERO bietet zwei Schnittstellen an. Die Lead API ist für genau einen Zweck gebaut: Anfragen aus Kontaktformularen, Partnerportalen oder anderen Systemen als neues Projekt anzulegen. Die GraphQL-API ist die große Variante mit Vollzugriff auf Kontakte, Projekte, Dokumente, Termine und Artikelstamm. Für Anfragen von der Website reicht die Lead API, und sie ist deutlich einfacher anzubinden.

Technisch ist es ein einziger Aufruf an die Adresse login.hero-software.de/api/v1/Projects/create, abgesichert mit einem API-Schlüssel. Den Schlüssel bekommst du laut HERO kostenlos über den Support. Er wird nur einmal angezeigt, also direkt sicher ablegen.

Klappt der Aufruf, antwortet HERO mit der Nummer des neuen Projekts. Fehlt eine Pflichtangabe, kommt eine Fehlermeldung mit dem Grund, etwa „Fehlende Postleitzahl“. Bei einem ungültigen Schlüssel wird der Zugriff abgelehnt.

Welche Formularfelder wohin gehören

Die folgende Zuordnung zeigt, wie die üblichen Felder eines Anfrageformulars in HERO ankommen. Die Feldnamen stammen aus der Dokumentation der Lead API.

So sieht ein vollständiger Aufruf aus. Die Werte sind Beispieldaten.

POST https://login.hero-software.de/api/v1/Projects/create
Authorization: Bearer <dein API-Schlüssel>

{
  "measure": "PRJ",
  "customer": {
    "email": "[email protected]",
    "first_name": "Anna",
    "last_name": "Beispiel",
    "phone_mobile": "+49170000000"
  },
  "address": {
    "street": "Musterstraße 1",
    "zipcode": "44135",
    "city": "Dortmund",
    "country_code": "DE"
  },
  "project": {
    "source": "Website - Anfrageformular",
    "source_sub": "meinbetrieb.de",
    "source_medium": "Anfrageformular"
  },
  "project_match": {
    "comment": "Bad komplett erneuern, ca. 8 m², Wunschtermin Frühjahr"
  }
}

Der Ablauf mit n8n

Man kann das Formular auch direkt an HERO schicken lassen. Dann steckt der API-Schlüssel aber im Code der Website, und wenn HERO einmal nicht erreichbar ist, ist die Anfrage weg. Sicherer ist ein Automatisierungswerkzeug dazwischen. Mit n8n auf einem eigenen Server sieht der Ablauf so aus:

1. 1

   Formular schickt die Anfrage an n8n

   Der API-Schlüssel für HERO liegt nur in n8n, nicht auf der Website.

2. 2

   Daten prüfen und vereinheitlichen

   Postleitzahl vorhanden? Telefonnummer im einheitlichen Format? Leere Felder entfernen.

3. 3

   Optional: Anfrage einordnen

   Eine KI kann aus der Beschreibung Gewerk und Dringlichkeit ableiten und daraus das passende Kürzel für HERO setzen.

4. 4

   Projekt in HERO anlegen

   Aufruf der Lead API mit allen Daten, inklusive Herkunft der Anfrage.

5. 5

   Kunden den Eingang bestätigen

   Eine E-Mail mit dem, was als Nächstes passiert und bis wann du dich meldest.

6. 6

   Fehler abfangen

   Antwortet HERO mit einem Fehler, geht die komplette Anfrage per E-Mail ans Büro. Keine Anfrage geht verloren.

Wie das Formular selbst aufgebaut sein sollte, damit Anfragen vollständig ankommen, beschreibt der Artikel Kontaktformular oder Fragebogen?

Worauf du achten solltest

Postleitzahl zur Pflicht machen

Ohne Postleitzahl lehnt HERO die Anfrage ab. Das Feld muss also schon im Formular Pflicht sein. Nebenbei hilft die Postleitzahl dir, Anfragen außerhalb deines Einzugsgebiets sofort zu erkennen.

Gewerk-Kürzel abstimmen

Das Feld measure ordnet die Anfrage einem Gewerk oder einer Maßnahme zu. Welche Kürzel es gibt, hängt davon ab, wie dein HERO-Konto eingerichtet ist. Frag vorher beim Support nach der Liste oder nutze das allgemeine Kürzel für Projekte.

Fotos testen

Die Lead API nimmt Bilder und Dokumente an. Die Dokumentation beschreibt die Übergabe allerdings knapp. Teste mit echten Handyfotos, bevor das Formular live geht, und prüfe, ob sie in HERO am Projekt hängen.

Datenschutz

Die Anfrage enthält personenbezogene Daten. Deine Datenschutzerklärung muss nennen, dass Anfragen an deine Handwerkersoftware übertragen werden, und mit HERO wie mit jedem Dienstleister, der Kundendaten verarbeitet, brauchst du einen Auftragsverarbeitungsvertrag. Läuft n8n auf einem eigenen Server in Deutschland, kommt kein weiterer Dienst dazu. Mehr dazu im Artikel zur DSGVO am Anfrageformular.

Wie sich das in der Praxis lösen lässt

Die Einrichtung ist überschaubar: API-Schlüssel beim HERO-Support anfordern, Formularfelder zuordnen, den Ablauf in n8n bauen und mit ein paar Testanfragen prüfen. Wer HERO nicht nutzt, findet im Artikel Handwerkersoftware mit Schnittstelle die Übersicht, welche anderen Programme sich ähnlich anbinden lassen.

Wenn du HERO nutzt und deine Website-Anfragen direkt dort haben willst, richte ich das für dich ein. Den Einstieg findest du bei der Prozessautomatisierung für Handwerksbetriebe.

Häufige Fragen