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
GraphQL API
Unser GraphQL-Endpunkt ist verfügbar unter der URL https://login.hero-software.de/api/external/v7/graphql
Unter dieser URL können Sie auch die automatisch generierte Dokumentation, das Schema und die vollständige API-Referenz abrufen. Hierfür benutzen Sie bitte einen GraphQL-Client Ihrer Wahl, wie z. B. Insomnia.
Für eine Anleitung, wie Sie GraphQL unter Insomnia benutzen können, klicken Sie bitte hier: GraphQL Queries via Insomnia
Bitte beachten Sie, dass der Endpoint bereits mit API-Token geschützt ist, und
Sie den obigen Authorization
-Header auch in Ihrem Client hinterlegen müssen.
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 kommen Sie 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 können Sie 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 bekommen Sie 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);
}