Möchtest du die HERO Handwerkersoftware mit deiner Website verbinden, um z. B. automatisiert Projekte aus einem Kontaktformular zu generieren? Oder ist es dein Wunsch, aus beliebigen Lead-Portalen Anfragen in HERO zu importieren?
Das und vieles mehr ist möglich mit unseren Schnittstellen. Hier verraten wir dir, wie du die HERO APIs nutzen kannst.
Generell bieten wir zwei kostenfreie APIs an:
Lead-API
Die HERO Lead API ermöglicht es dir, automatisch neue Projekte mit Kundendaten und Dateien anzulegen, z. B. um ein Kontaktformular auf deiner Website anzubieten oder ein anderes Leadqualifizierungs-Tool vor HERO zu schalten.
Authentifizierung
Zuerst benötigst du einen API-Schlüssel von uns. Dieser Service ist für dich kostenlos. Trete dafür bitte mit unserem Support (support@hero-software.de) in Kontakt. Der API-Schlüssel muss bei jeder Anfrage als HTTP-Header mitgeliefert werden:
Authorization: Bearer YOUR_API_KEY
Projekt anlegen
Das Anlegen eines neuen Projekts erfolgt via POST-Request zu folgender URL:
POST https://login.hero-software.de/api/v1/Projects/create
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Die Projektdaten werden dabei als JSON-Objekt im HTTP-Body übermittelt:
{
"measure": "PRJ",
"customer": {
"email":
"max.mustermann@example.org",
"title": "Herr",
"first_name": "Max",
"last_name": "Mustermann",
"company_name": "Meine Firma"
},
"address": {
"street": "Schwarzer Bär 2",
"city": "Hannover",
"zipcode": "30449",
"country_code": "DE"
},
"projectaddress": {
"street": "Schwarzer Bär 5",
"city": "Hannover",
"zipcode": "30449",
"country_code": "DE"
},
"project_match": {
"comment": "Dieser Kommentar erscheint im Logbuch zu dem Projekt.",
"partner_notes": "Optionale Hinweise für das Notizfeld.",
"partner_source": "Mein Kontaktformular"
}
}
Datenmodell
Folgende Datenfelder unterstützen wir bei der Einliferung:
-
measure
: Kürzel des Gewerks für das Projekt. Die verfügbaren Gewerkskürzel kannst du als Teil der Projektnummer sehen, wenn du dir ein Projekt anlegst. Hier als Beispiel: "PRJ" -
customer
: Objekt mit Kundendaten. Pflichtfeld ist hier lediglich die Emailadresse. -
address
: Adresse des Kunden. -
projectaddress
: Optionale abweichende Objektadresse des Projekts. Falls leer, wird die Kundenadresse genommen. -
project_match
: Optionale weitere Projektdaten:-
partner_source
: Projektquelle, wie z. B. das Kontaktformular auf deiner Website.
-
-
partner_notes
: Ergänzende Informationen, die im Notizfeld im Projekt erscheinen. -
comment
: Ergänzende Informationen, die im Logbuch erscheinen.
Fehlerbehandlung
Wenn das Projekt erfolgreich angelegt werden konnte, dann gibt der Server einen HTTP-Status von 200
und "status": "success"
zurück. In allen anderen Fällen erscheint eine Fehlermeldung im JSON unter status
.
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);
}
GraphQL API
Die HERO GraphQL API ermöglicht dir einen Vollzugriff auf dein Konto und alle Objekte, womit du Kundendaten, Projekte oder Dokumente einsehen, herunterladen, erstellen oder verändern kannst.
Du kannst damit z. B. deine Kunden zwischen HERO und anderen Systemen synchronisieren, Rechnungen automatisiert sichern oder erweiterte Workflows von Projekten abbilden.
Alles rund um GraphQL findest du hier
Bei Interesse wende dich gern an support@hero-software.de