Vollzugriff mit der HERO GraphQL API

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.

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.

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

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