Entwickler

Die Aequo API

Verbinden Sie Aequo mit Ihren anderen Systemen – IT-Benutzerverwaltung, Dienstplanung, Rechnungsstellung oder BI. REST, JSON, OpenAPI 3. Verfügbar in den Tarifen Business und Mittelstand.

API-Schlüssel mit Berechtigungen

Jeder Schlüssel darf nur, was er braucht – je Bereich lesen oder schreiben. Jederzeit widerrufbar.

Datenschutz eingebaut

Keine Gehalts-, Gesundheits- oder Hinweisgeberdaten. Krankheit erscheint nur als „abwesend“.

Fair begrenzt, lückenlos protokolliert

120 Anfragen pro Minute je Schlüssel. Jeder Aufruf wird 90 Tage für Ihre Administration protokolliert.

Anmeldung

Die Unternehmensadministration legt unter Einstellungen → API-Schlüssel einen Schlüssel an und wählt seine Berechtigungen. Der Schlüssel wird nur einmal angezeigt. Senden Sie ihn bei jedem Aufruf im Header „Authorization: Bearer aeq_…“.

Basis-URL: https://<workspace>.aequohr.com/api/public/v1

curl https://your-company.aequohr.com/api/public/v1/employees?per_page=100 \
  -H "Authorization: Bearer aeq_…" \
  -H "Accept: application/json"
{
  "data": [
    { "id": 12, "employee_number": "E-1042", "first_name": "Jonas", "last_name": "Weber",
      "work_email": "jonas.weber@example.de", "department": { "id": 3, "name": "Logistik" },
      "job_title": "Teamleitung Lager", "employment_status": "active", "hire_date": "2021-04-01" }
  ],
  "links": { "next": "…?page=2" },
  "meta": { "current_page": 1, "last_page": 3, "per_page": 100, "total": 248 }
}

Berechtigungen (Scopes)

Ein Aufruf ohne die nötige Berechtigung wird mit 403 abgelehnt.

  • employees:readMitarbeitende lesen (Arbeitsstammdaten)
  • departments:readAbteilungen lesen
  • absences:readAbwesenheiten lesen
  • working_time:readArbeitszeiten lesen
  • project_time:readProjekte und Projektzeiten lesen
  • project_time:writeProjektzeiten buchen
  • documents:readDokument-Metadaten lesen

Endpunkte

EndpunktBerechtigungInhalt
GET /employeesemployees:readMitarbeitende mit Arbeitsstammdaten – Name, dienstliche E-Mail, Abteilung, Position, Standort, Vorgesetzte, Status, Eintritt/Austritt. Filter: status, updated_since
GET /employees/{id}employees:readEine Person.
GET /departmentsdepartments:readAbteilungen mit Hierarchie und Leitung.
GET /absencesabsences:readAbwesenheiten mit Zeitraum, Tagen und Status. Krankheit erscheint als Typ „absent“ ohne Details. Filter: employee_id, status, from, to
GET /working-timeworking_time:readErfasste Arbeitszeit je Tag: Kommen, Gehen, Arbeits-, Pausen- und Überstunden-Minuten. Filter: employee_id, from, to
GET /projectsproject_time:readProjekte mit Kunde, Status und Stundenbudget – ohne Sätze und Eurobudgets. Filter: status
GET /time-entriesproject_time:readGebuchte Projektzeiten. Filter: employee_id, project_id, status, from, to, updated_since
POST /time-entriesproject_time:writeProjektzeit für eine Person buchen – als Entwurf für die Wochenfreigabe; die Person muss im Projektteam sein.
GET /documentsdocuments:readMetadaten von Personaldokumenten – nie die Datei, nie vertrauliche Dokumente. Filter: employee_id, updated_since

Seiten und Filter

Listen kommen seitenweise: ?page= und ?per_page= (höchstens 100, Standard 50). Die Antwort enthält „data“, „links“ und „meta“ mit Gesamtzahl. Mit updated_since holen Sie nur Änderungen seit Ihrem letzten Abgleich.

Fehlercodes

  • 401 – Schlüssel fehlt, ist ungültig, widerrufen oder abgelaufen
  • 403 – Berechtigung fehlt oder die API ist nicht im Tarif
  • 404 – Nicht gefunden
  • 422 – Ungültige Parameter – Details in „errors“
  • 429 – Zu viele Anfragen – warten Sie die Sekunden aus „Retry-After“

Was die API bewusst nie liefert

Gehälter und Vergütung, Gesundheitsdaten (Krankheit erscheint nur als Abwesenheit), Hinweisgeberfälle, Steuer-, Sozialversicherungs- und Bankdaten sowie private Adressen und Kontaktdaten. So können Sie Systeme anbinden, ohne besondere Kategorien personenbezogener Daten zu übertragen.