Für die korrekte Darstellung und Funktion dieser Website ist JavaScript erforderlich. Bitte aktiviere JavaScript in deinem Browser.

Zum Inhalt springen

Schnittstelle einfach erklärt

Anleitung: Neue Projekte anlegen mit der HERO Lead API

Die HERO Lead API ermöglicht es dir, externe Quellen wie Kontaktformulare, Partnerportale oder CRM-Systeme direkt an die HERO Handwerkersoftware anzubinden. In dieser Anleitung erfährst du, wie du die HERO Lead API einrichtest.

Jetzt testen

Endpunkt

POST https://login.hero-software.de/api/v1/Projects/create
Authorization: Bearer YOUR\_API\_KEY
Content-Type: application/json
Accept: application/json

Authentifizierung

Jede Anfrage muss im HTTP-Header einen gültigen Bearer-Token übermitteln:

Authorization: Bearer [dein-api-token]

Token erstellen

Zuerst benötigst du einen API-Schlüssel von uns. Dieser Service ist für dich kostenlos. Nimm dafür bitte mit unserem Support Kontakt auf. Der generierte Token wird einmalig ausgegeben und muss sicher gespeichert werden.

Anfrage-Format

Der Request-Body ist ein JSON-Objekt mit folgenden Feldern:

json
{
  "measure": "PVS",
  "customer": { ... },
  "address": { ... },
  "projectaddress": { ... },
  "project": { ... },
  "project\_match": { ... },
  "images": \[ ... ],
  "documents": \[ ... ]
}

Felder im Detail

`measure` (string, optional)

Beispiel für Gewerke-Kürzel des Projekts. Standard: PRJ.

Kürzel	Bedeutung
`PVS`	Photovoltaikanlage
`SSP`	Stromspeicher
`DOG`	Dachdeckung (Beispiel)
`UNB`	Unbekannt / Sonstiges
`PRJ`	Allgemeines Projekt (Standard)

Die verfügbaren Kürzel hängen von der HERO-Instanzkonfiguration ab.

`customer` (object, erforderlich)

Kundendaten. Mindestens email ist erforderlich.

Feld	Typ	Pflicht	Beschreibung
`email`	string	ja	E-Mail-Adresse des Kunden
`first_name`	string	nein	Vorname
`last_name`	string	nein	Nachname
`title`	string	nein	Anrede: `"Herr"`, `"Frau"` oder `"HerrFrau"` (Standard wenn leer)
`title_custom`	string	nein	Individuelle Anrede (z. B. `"Dr."`)
`company_name`	string	nein	Firmenname – wenn gesetzt, wird der Kunde automatisch als `commercial` angelegt
`phone_home`	string	nein	Festnetznummer (internationales Format empfohlen, z. B. `+4921112345`)
`phone_mobile`	string	nein	Mobilnummer

Beispiel:

json
"customer": {
  "email": "max.mustermann@example.com",
  "first\_name": "Max",
  "last\_name": "Mustermann",
  "title": "Herr",
  "phone\_home": "+4921112345678",
  "phone\_mobile": "+49171123456"
}

`address` (object, erforderlich)

Kundenadresse. zipcode ist zwingend erforderlich.

Feld	Typ	Pflicht	Beschreibung
`zipcode`	string	ja	Postleitzahl
`street`	string	nein	Straße und Hausnummer
`nr`	string	nein	Hausnummer separat (wird an `street` angehängt)
`city`	string	nein	Stadt
`country_code`	string	nein	ISO-Ländercode: `"DE"` (Standard), `"AT"`, `"CH"`
`country_id`	int	nein	Alternativer Länder-ID (wird durch `country_code` überschrieben)

Hinweis: Wenn country_code nicht angegeben wird, erkennt das System anhand der PLZ-Länge automatisch das Land (4-stellig → Schweiz/Österreich, 5-stellig → Deutschland).

Beispiel:

json
"address": {
  "street": "Musterstraße 42",
  "zipcode": "10115",
  "city": "Berlin",
  "country\_code": "DE"
}

`projectaddress` (object, optional)

Objektadresse, wenn diese von der Kundenadresse abweicht. Felder identisch mit address. Wenn projectaddress leer oder nicht angegeben ist, wird die address als Projektadresse übernommen.

Beispiel:

json
"projectaddress": {
  "street": "Gewerbepark 1",
  "zipcode": "80331",
  "city": "München",
  "country\_code": "DE"
}

`project` (object, optional)

Metadaten zum Projekt und zur Tracking-Quelle.

Feld	Typ	Beschreibung
`source`	string	Vollständige Bezeichnung der Quelle (z. B. `"example.org - Kontaktformular"`)
`source_sub`	string	Domain oder System (z. B. `"example.org"`)
`source_medium`	string	Kanal (z. B. `"Kontaktformular"`, `"CRM"`)
`partner_source`	string	Interner Quellenname des Partners
`lead_id`	string	Externe Lead-ID aus dem Quellsystem (Format: `"Quelle/UniqueId"`)

Beispiel:

json
"project": {
  "source": "mein-portal.de - Angebotsanfrage",
  "source\_sub": "mein-portal.de",
  "source\_medium": "Angebotsanfrage",
  "lead\_id": "MeinPortal/abc123"
}

`project\_match` (object, optional)

Steuert die Einordnung des Projekts beim Partner. Wird nur relevant, wenn der API-Token einem konkreten Partner/einer Firma zugewiesen ist.

Feld	Typ	Beschreibung
`status_code`	int	Anfangsstatus des Projekts (siehe unten). Standard: `201` (Erstkontakt)
`comment`	string	Kommentar, der als Logbucheintrag beim Projekt erscheint
`inform_partner`	bool	Wenn `true`, wird der Partner per E-Mail über das neue Projekt informiert

Erlaubte status\_code-Werte:

Code	Status
`201`	Neu – Erstkontakt
`400`	Vor-Ort Termin
`601`	Angebotserstellung
`801`	Auftrag
`1111`	Ausführung in Fortschritt

Beispiel:

json
"project\_match": {
  "status\_code": 201,
  "comment": "Kunde hat über unser Portal angefragt.",
  "inform\_partner": true
}

`images` (array, optional)

Bilder, die dem Projekt angehängt werden. Jedes Element ist ein Datei-Upload-Objekt (Multipart oder Base64, je nach Client-Implementierung).

`documents` (array, optional)

Dokumente (z. B. PDFs), die dem Projekt angehängt werden. Werden als generische Dokumente angelegt.

Vollständiges Beispiel

json
{
  "measure": "PVS",
  "customer": {
    "email": "anna.schmidt@example.com",
    "first\_name": "Anna",
    "last\_name": "Schmidt",
    "title": "Frau",
    "phone\_home": "+4930123456",
    "phone\_mobile": "+49170987654"
  },
  "address": {
    "street": "Hauptstraße 10",
    "zipcode": "10117",
    "city": "Berlin",
    "country\_code": "DE"
  },
  "project": {
    "source": "solarvergleich.de - Anfrageformular",
    "source\_sub": "solarvergleich.de",
    "source\_medium": "Anfrageformular",
    "lead\_id": "solarvergleich/XY789"
  },
  "project\_match": {
    "status\_code": 201,
    "comment": "Interesse an 10 kWp Anlage mit Speicher.",
    "inform\_partner": true
  },
}

Antwort-Format

Erfolg (`200 OK`)

json
{
  "status": "success",
  "id": 12345
}

id ist die HERO-interne Projekt-ID des neu angelegten Projekts.

Validierungsfehler (`422 Unprocessable Entity`)

json
{
  "status": "error",
  "message": "Fehlende Postleitzahl",
  "validationErrors": {}
}

Authentifizierungsfehler (`403 Forbidden`)

Wird geworfen, wenn kein oder ein ungültiger Token übermittelt wird.

Wichtige Hinweise

E-Mail-Adresse ist das primäre Deduplizierungsmerkmal. Existiert bereits ein Kunde mit dieser E-Mail (und der gleichen Firma), wird kein neuer Kunde angelegt.
Duplikaterkennung: Das System prüft auf doppelte E-Mail-Adressen und Telefonnummern. Bei einem Duplikat wird das Projekt trotzdem angelegt, aber ein Logbucheintrag als Hinweis erstellt.
E-Mail-Blacklist: Bestimmte E-Mail-Domains können serverseitig gesperrt sein. Anfragen mit gesperrten Adressen werden mit status: "error" abgewiesen, ohne HTTP-Fehlercode.
Länderkennung: Bei fehlender country\_code-Angabe wird das Land automatisch aus der PLZ-Länge abgeleitet (5 Stellen → Deutschland, 4 Stellen → Schweiz/Österreich).
Firmen-Kunden: Sobald company\_name gesetzt ist, wird der Kundentyp automatisch auf commercial gesetzt.

PHP-Beispielcode

<?php
$url = 'https://login.hero-software.de/api/v1/Projects/create';
$apikey = 'YOUR\_API\_KEY'; // den API-Schlüssel bekommst du von unserem Support

$data = array(
    "measure" => "PRJ",
    "customer" => array(
        "email" => "max.mustermann@example.org",
        "title" => "Herr",
        "first\_name" => "Max",
        "last\_name" => "Mustermann",
        "company\_name" => "Meine Firma",
    ),
    "address" => array(
        "street" => "Schwarzer Bär 2",
        "city" => "Hannover",
        "zipcode" => "30449",
        "country\_code" => "DE",
    ),
    "projectaddress" => array(
        "street" => "Schwarzer Bär 5",
        "city" => "Hannover",
        "zipcode" => "30449",
        "country\_code" => "DE",
    ),
    "project\_match" => array(
        "comment" => "Dieser Kommentar erscheint im Logbuch zu dem Projekt.",
        "partner\_notes" => "Optionale Hinweise für das Notizfeld.",
        "partner\_source" => "Mein Kontaktformular",
    ),
);

$postdata = json\_encode($data);

$ch = curl\_init($url); 
curl\_setopt($ch, CURLOPT\_POST, 1);
curl\_setopt($ch, CURLOPT\_POSTFIELDS, $postdata);
curl\_setopt($ch, CURLOPT\_RETURNTRANSFER, 1); 
curl\_setopt($ch, CURLOPT\_HTTPHEADER, array(
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer '.$apikey,
));
$result = curl\_exec($ch);
curl\_close($ch);

$response = json\_decode($result, true);
if (isset($response\['status']) \&\& $response\['status'] == 'success') {
    echo "Projekt erfolgreich angelegt";
} else {
    echo "Ein Fehler ist aufgetreten: ".$response\['message']."
\\n";
    var\_dump($response);
}

Noch Fragen?

Du hast noch Fragen zur HERO Lead API? Gern kannst du dich direkt an uns wenden. Hier findest du alle Kontaktmöglichkeiten.

Anleitung: Neue Projekte anlegen mit der HERO Lead API

Endpunkt

Authentifizierung

Token erstellen

Anfrage-Format

Felder im Detail

measure (string, optional)

customer (object, erforderlich)

address (object, erforderlich)

projectaddress (object, optional)

project (object, optional)

project\_match (object, optional)

images (array, optional)

documents (array, optional)

Vollständiges Beispiel

Antwort-Format

Erfolg (200 OK)

Validierungsfehler (422 Unprocessable Entity)

Authentifizierungsfehler (403 Forbidden)

Wichtige Hinweise

PHP-Beispielcode

Noch Fragen?

`measure` (string, optional)

`customer` (object, erforderlich)

`address` (object, erforderlich)

`projectaddress` (object, optional)

`project` (object, optional)

`project\_match` (object, optional)

`images` (array, optional)

`documents` (array, optional)

Erfolg (`200 OK`)

Validierungsfehler (`422 Unprocessable Entity`)

Authentifizierungsfehler (`403 Forbidden`)