Bild: Hero Handwerkersoftware mit App & Cloud

Vollzugriff mit der HERO 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.

Empfohlen von

Authentifizierung

Zuerst benötigst du einen API-Schlüssel von uns. Trete 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

GraphQL API

Unser GraphQL-Endpunkt ist verfügbar unter der URL https://login.hero-software.de/api/external/v7/graphql

Unter dieser URL kannst du auch die automatisch generierte Dokumentation, das Schema und die vollständige API-Referenz abrufen. Hierfür benutzt du bitte einen GraphQL-Client deiner Wahl, wie z. B. Insomnia.

Für eine Anleitung, wie du GraphQL unter Insomnia benutzen kannst, klick bitte hier: GraphQL Queries via Insomnia

Bitte beachte, dass der Endpoint bereits mit API-Token geschützt ist, und du den obigen Authorization-Header auch in deinem Client hinterlegen musst.

Oft genutzte Anfragen

  • Queries:
    • contacts: Kontakte
    • project_matches: Projekte
    • customer_documents: Dokumente
    • calendar_events: Termine
    • supply_product_versions: Artikelstamm
  • Mutations:
    • create_contact: Anlegen eines Kontakts
    • create_project_match: Anlegen eines Projekts
    • add_logbook_entry: Logbucheintrag anlegen

Beispielanfragen

Da unsere GraphQL Zugriff auf alle Objekte bietet, sind hier nur einige wenige Beispiele aufgelistet. Bei Fragen zum Datenmodell komm gerne auf uns zu.

Kontakte auflisten

Folgendes Beispiel listet alle Kontakte inkl. deren Adresse im System auf:

query {
  contacts {
    id
    nr
    first_name
    last_name
    company_name
    email
    phone_home
    
    address {
      street
      city
      zipcode
    }
  }
}

Projekte auflisten

Folgendes Beispiel listet alle Projekte inkl. Ansprechpartner, Adresse und Status auf:

query {
  project_matches {
    id
    project_nr
    
    measure { # Gewerk
      short
      name
    }
    
    customer { # Kunde
      id
      first_name
      last_name
      email
    }
    
    contact { # Ansprechpartner
      id
      first_name
      last_name
      email
    }
    
    address { #Projektadresse
      street
      city
      zipcode
    }
    
    current_project_match_status { # Projektstatus
      status_code
      name
    }
  }
}

Projektdetails

Mit dem ids-Parameter kannst du einzelne Projekte abrufen, um z. B. die dazugehörigen Dokumente und Logbucheinträge aufzulisten:

query {
  # Filter nach bestimmten IDs
  project_matches(ids: [150798]) {
    id
    project_nr
    
    customer_documents {
      type
      nr
      value
      created
      
      file_upload {
        url
      }
    }
    
    histories {
      custom_title
      custom_text
      created
    }
  }
}

Dokumente auflisten

query {
  customer_documents {
    id
    created
    nr
    value
    vat
    status_code
    
    document_type {
      base_type
      name
    }
    
    file_upload {
      url
    }
  }
}

PHP-Beispielcode

Dieses PHP-Beispiel ruft die letzten 50 Kontakte vom Typ "Kunde" ab:

<?php
$url = 'https://login.hero-software.de/api/external/v7/graphql';
$apikey = 'YOUR_API_KEY'; // den API-Schlüssel bekommst du von unserem Support

// GraphQL-Query
$query = '
query ($category: CustomerCategoryEnum, $offset: Int) {
  contacts(category: $category, orderBy: "id", offset: $offset) {
    id
    nr
    last_name
    email
    modified

    address {
      street
      city
      zipcode
    }
  }
}
';

// Parameter für die Query
$variables = array(
    "category" => "customer",
    "offset" => 0,
);

$postdata = json_encode(array(
    'query' => $query,
    'variables' => $variables,
));

$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 (!empty($response['data'])) {
    echo "Abgerufene Kontakte:";
    var_dump($response['data']['contacts']);
} else {
    echo "Ein Fehler ist aufgetreten:";
    var_dump($response);
}

HERO & GraphQl - Weitere Infos

Mit der Abfragesprache GraphQL werden dir nur die Daten zur Verfügung gestellt, die du wirklich brauchst. APIs werden dank GraphQL flexibler, schneller und entwicklerfreundlicher. Alle Details zu GraphQL-Aktionen, möglichen Zuweisungen und Abfragen sowie Kontakterstellung und das Bezahlen von Rechnungen kannst du an dieser Stelle nachlesen.

Du hast Fragen zur HERO GraphQL API? Wir helfen dir gern | © 2021 Rymden/Shutterstock.com

Noch Fragen?

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

Bild: Hero Handwerkersoftware kostenlos testen

HERO: Handwerker Software für Profis

Kostenlose Beratung