Die Customer API ist die Hauptverbindung zu Ihrem HR AdSys-Konto. Die Schnittstelle teilt sich in verschiedene Module auf, gewährt breiten Zugriff auf Ihre Daten und bietet eine Vielzahl an Funktionen.
Einzelne Module der API sind aktuell noch in Entwicklung
Aufbau
Die Customer API teilt sich in verschiedene Zugriffsoptionen und APIs auf. Hierbei sieht die API Sie als User (Benutzer). Jeder Benutzer kann verschiedenen Unternehmen zugeordnet sein und verschiedene Rechte im Unternehmen haben.
Wie bieten zwei verschiedene Schlüssel:
- Master Token (Hauptschlüssel)
Schlüssel für den Zugriff auf die eigentliche Customer API, die nachfolgend beschrieben wird. Dieser Schlüssel lässt sich innerhalb der Customer API einsetzen und wird bei Abfragen im Anschluss an die Authentifizierung über den Master Token verwendet. - Customer Hashes (Unternehmensschlüssel)
Jedes Unternehmen hat zudem zwei Schlüssel, einen öffentlichen und einen privaten.
1. Public Key (öffentliche Schlüssel)
kann frei weiter gegeben werden und dienen in erster Linie für Lesezugriffe.
2. Private Key (privater Schlüssel) lässt sich innerhalb der Customer API einsetzen und wird bei Abfragen im Anschluss an die Authentifizierung über den Master Token verwendet.
Dieser private Schlüssel dient auch für Web Actions (HTTP Requests).Web-Actions (HTTP-Requests)
Der private Unternehmensschlüssel kann in einer Web-Action URL genutzt werden, z. B. für den Zugriff auf die Anzeigenvorschau über einen Direktlink (ohne weitere API-Authentifizierung oder Login). Diese Schlüssellinks können ohne weitere Authentifizierung direkt über den Browser aufgerufen werden, gewähren jedoch ebenfalls nur eingeschränkten Lesezugriff.Mehr zum Thema finden Sie in der Web-Actions Dokumentation.
Hinweis: Der Customer Hash dient sowohl für Aktionen nach der Master Token-Authentifizierung als auch für die genannten Web-Actions, aber nicht zur direkten Authentifizierung in der Customer API selbst.
Die Customer API gliedert sich in untergeordnete APIs, die je Unternehmen aufgeschaltet werden können:
- Jobposting API (in Entwicklung)
API zum Posten von Stellenanzeigen - Tracking API (in Entwicklung)
API zum Auslesen von Statistikdaten - Web-Actions (diese werden gesondert behandelt)
Man kann sich den Aufbau wie ein Bürokomplex vorstellen. Der Master Token ist der Schlüssel für den Haupteingang. Der Customer Hash ist der Schlüssel für den Briefkasten (außen) und das jeweilige Büro (Unternehmen) im Komplex.
Um umfassend agieren zu können, brauchen Sie beide Schlüssel. Möchten Sie aber nur die Post lesen, so können Sie dies auch nur über den Schlüssellink (Customer Hash) machen. Wenn Ihr Schlüssel einem Unternehmen zugeordnet ist, können alle APIs, die beim Unternehmen aktiviert sind, auch verwendet werden. Separate API-Authentifizierungen innerhalb des Unternehmens sind so nicht mehr nötig.
Schlüssel und Einstellungen
Die Schlüssel zur API und alle Einstellungen dazu finden Sie im Hauptmenüpunkt Einstellungen oder oben rechts im internen Benutzermenü.
Hinweis: Lesen Sie dazu auch den Handbucheintrag Einstellungen mit weiteren Informationen zu den Schnittstellen-Einstellungen.
Anbindung
Alle Customer APIs (ausgenommen Web Actions) sind über nachfolgende URL Adresse erreichbar und geben standardmäßig JSON zurück.
Achten Sie bitte darauf, dass sie mit einem application/json Header sowie mit dem spezifischen API-Header angefordert werden.
URL-Adresse:
https://hr-adsys.de/api/v1
IP-Adresse:
Der Server hat die öffentliche IPv4 37.202.5.13 und IPv6 2a03:2a00:1200:0000:0001:0000:0000:3334
Authentifizierung
Die eingebaute Authentifizierung für den Master Token verwendet eine Bearer-Token-Implementierung.
Das Token selbst ist ein Base64 Schlüssel (ein String-Algorithmus: user_id:hmac). Der Algorithmus sagt uns, welche kryptografische Hash-Funktion zur Erzeugung des HMAC verwendet wurde.
Wir greifen auf die Sicherheitsüberlegungen von RFC 6151 zu und verbieten die Verwendung der weniger sicheren kryptografischen Hash-Funktionen.
Einfacher Aufruf:
https://hr-adsys.de/api/v1/{component}/{view}/{task}
