Vollzugriff mit der HERO GraphQL API

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

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.

• 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

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
    }
  }
}

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);
}

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.