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 noch Fragen zur HERO GraphQL API? Gern kannst du dich direkt an uns wenden. Hier findest du alle Kontaktmöglichkeiten.
Das könnte dich auch interessieren