Neue Projekte anlegen mit der HERO Lead API

Die HERO Lead API ermöglicht es Ihnen, automatisch neue Projekte mit Kundendaten und Dateien anzulegen, z. B. um ein Kontaktformular auf Ihrer Website anzubieten oder ein anderes Leadqualifizierungs-Tool vor HERO zu schalten.

Kostenlos testen
Bild: Die HERO App für Android und Tablet

Inhalt

Authentifizierung

Zuerst benötigen Sie einen API-Schlüssel* von uns. Treten Sie dafür bitte mit unserem Support in Kontakt. Der API-Schlüssel muss bei jeder Anfrage als HTTP-Header mitgeliefert werden:

Authorization: Bearer YOUR_API_KEY

*Für die Bereitstellung der Schnittstelle berechnen wir einmalig 199,00 € zzgl. MwSt.

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": "DOG",
    "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 Einlieferung:

  • measure: Kürzel des Gewerks für das Projekt. Die verfügbaren Gewerkskürzel können Sie als Teil der Projektnummer sehen, wenn Sie sich ein Projekt anlegen. Beispiel: "DOG" = "Dach und oberste Geschossdecke".
  • 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 Ihrer 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 message.

PHP-Beispielcode

<?php
$url = 'https://login.hero-software.de/api/v1/Projects/create';
$apikey = 'YOUR_API_KEY'; // den API-Schlüssel bekommen Sie von unserem Support

$data = array(
    "measure" => "DOG",
    "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);
}

GRATIS DEMOTERMIN