REST DokumentationBest Practices

Best Practices

Weniger Anfragen, schnellere Abgleiche, kein 429. Sechs Gewohnheiten, die am meisten sparen, jeweils mit Beispiel zum Kopieren.

Große Seiten abrufen

Ohne limit liefert eine Liste nur 15 Ergebnisse pro Seite, eine lange Liste braucht also viele Anfragen.

Stattdessen so: limit=200 senden, das Maximum. Ein Wert ab 201 wird mit 422 abgelehnt.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Spart rund 93 % der Anfragen bei einer langen Liste (1 statt 14 für 200 Einträge).

Nur Änderungen abrufen

Wer bei jedem Lauf alles neu lädt, holt Daten, die sich nicht geändert haben.

Stattdessen so: den größten empfangenen modified-Wert merken und beim nächsten Lauf als modified_after senden (Wasserzeichen).

Diese Endpunkte akzeptieren modified_after: /absences, /attendances, /categories, /customers, /employees, /folders, /invoices, /plannings, /projects, /projects/{id}/tasks, /receipts, /receipts-amounts, /resource-plannings, /tickets, /workhour-balances.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Bei /attendances ist der Cursor inklusiv: Datensätze mit genau dem gesendeten modified-Wert kommen erneut zurück, so geht keiner verloren. Ihr Code muss das Duplikat ignorieren. Teilen sich viele Datensätze einen Zeitstempel, setzen Sie mit id_after hinter der zuletzt verarbeiteten ID fort. Alle anderen Endpunkte liefern nur Datensätze, die strikt nach dem Wert geändert wurden. Die Liste ist nicht nach modified sortiert: alle Seiten lesen und das Maximum nehmen; das Wasserzeichen erst nach der letzten Seite speichern. Ausnahme: Bei /plannings verliert der Next-Link vorerst modified_after und limit, folgen Sie ihm dort nicht, sondern senden Sie page selbst und wiederholen Sie die Filter.

Spart rund das gesamte Datenvolumen unveränderter Datensätze, sobald die erste Komplettladung durch ist.

Datumsbereich eingrenzen

Ein Bereich wie 2000 bis 2026 lässt den Server Jahre an Daten lesen und senden, die Sie nicht brauchen.

Stattdessen so: start_date und end_date (YYYY-MM-DD) für den Zeitraum senden, den Sie wirklich brauchen.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?start_date=2026-10-01&end_date=2026-10-31&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Spart rund den Anteil der gekürzten Jahre: ein Monat statt 26 Jahre sind etwa 99,7 % weniger Daten.

Rate Limits einhalten

Über den Limits antwortet die API mit 429 und Ihr Abgleich bleibt stehen.

Stattdessen so: Mit X-RateLimit-Remaining das restliche Budget prüfen und bei 429 die Sekunden aus Retry-After abwarten, bevor Sie es erneut versuchen. Limits und Header stehen unter Authentifizierung.

curl -i 'https://www.zep-online.de/zepinstanz/next/api/v1/projects?limit=1' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Spart rund jeden Wiederholversuch, der ohnehin abgelehnt würde: einmal warten ist billiger als Dauerfeuer.

Flach filtern statt über Eltern-Objekte zu laufen

Eine Anfrage pro Projekt, Mitarbeiter, Beleg oder Rechnung vervielfacht Ihre Anfragezahl um die Zahl der Eltern-Objekte. Ein Mandant darf 1000 Anfragen pro 5 Minuten senden, alle seine Tokens zusammen (siehe Rate Limiting). Eine Schleife über einige tausend Eltern-Objekte verbraucht also mehrere Zeitfenster, und Ihr Abgleich wartet.

Stattdessen so: die flache Liste einmal mit limit=200 lesen und die Zeilen nach der Eltern-ID gruppieren, zum Beispiel project_id. Jede Zeile enthält diese ID. Brauchen Sie nur einige Eltern-Objekte, filtern Sie nach deren IDs.

Projektzuordnungen

Gut: eine Anfrage pro Projekt, GET /projects/{id}/employees, oder pro Mitarbeiter, GET /employees/{username}/projects.

Besser: eine flache Liste für alle Projekte. /project-employees liefert dieselben Zeilen mit denselben Feldern.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/project-employees?limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Bei einem Mandanten mit 1.650 Projekten und 16.000 Zuordnungen: 80 Seiten statt 1.650 Aufrufen.

Für einige Projekte oder einen Mitarbeiter senden Sie project_id oder employee_id (den Benutzernamen), einmal oder als Liste. curl braucht -g für die eckigen Klammern:

curl -g 'https://www.zep-online.de/zepinstanz/next/api/v1/project-employees?project_id[]=2&project_id[]=3&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'
curl 'https://www.zep-online.de/zepinstanz/next/api/v1/project-employees?employee_id=jdoe&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

/project-employees kennt kein modified_after, aber jede angelegte, geänderte oder gelöschte Zuordnung aktualisiert modified des Projekts (siehe „Welche Änderungen das Eltern-Objekt aktualisieren“ unten). Fragen Sie nach der ersten Komplettladung /projects?modified_after=… ab und laden Sie die Zuordnungen nur für die Projekte neu, die dabei zurückkommen:

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/projects?modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Einzelabrufe nach der Liste

Gut: /projects auflisten, dann GET /projects/{id} für jede Zeile. Ebenso bei /customers und /employees.

Besser: die Zeilen der Liste verwenden. Sie haben dieselben Felder wie der Einzelabruf, mit diesen Ausnahmen:

  • /projects/{id} enthält zusätzlich priceTables.
  • /customers/{customer_number} enthält zusätzlich addresses, managers und priceTables. Die Liste hat stattdessen Zähler, zum Beispiel addresses_count, contacts_count und managers_count.
  • /employees/{username} enthält zusätzlich absences_count. Die Liste versteht dasselbe include wie der Einzelabruf.

Rufen Sie den Einzelabruf nur für die Zeilen auf, bei denen Sie diese Felder brauchen. Bei 1.650 Projekten: 9 Seiten statt 1.659 Aufrufen.

Belegbeträge

Gut: GET /receipts/{id}/amounts für jeden Beleg.

Besser: /receipts-amounts, gefiltert nach receipt_id oder employee_id, wenn Sie nur einen Teil brauchen. Ein Betrag hat kein eigenes modified: Ein angelegter oder geänderter Betrag aktualisiert modified seines Belegs. Senden Sie deshalb das Wasserzeichen Ihres /receipts-Abgleichs als modified_after:

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/receipts-amounts?modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Rechnungspositionen

Gut: GET /invoices/{invoice_number}/items für jede Rechnung oder GET /projects/{id}/invoice-items für jedes Projekt.

Besser: /invoice-items einmal. Jede Position enthält invoice_number und project_id. Für einige Projekte senden Sie project_id einmal oder als Liste; planned_from und planned_to grenzen nach dem geplanten Datum ein. Es gibt kein modified_after und keinen Filter nach Rechnung.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/invoice-items?project_id=2&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Abwesenheiten

Gut: GET /employees/{username}/absences für jeden Mitarbeiter.

Besser: /absences mit modified_after, für alle Mitarbeiter auf einmal, oder mit employee_id (dem Benutzernamen) für einen. Die flache Liste enthält zusätzlich absenceReason und leaveApprovalApplication, die in der Liste pro Mitarbeiter fehlen.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/absences?modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Beschäftigungszeiträume, Regelarbeitszeiten, interne Stundensätze

Gut: drei Anfragen pro Mitarbeiter: /employees/{username}/employment-periods, /employees/{username}/regular-working-times, /employees/{username}/internal-rates.

Besser: include an der Mitarbeiterliste bettet alle drei vollständig und ungeblättert in jeden Mitarbeiter ein. internal_rates gibt es nicht mit einer ZEP-Clock-Lizenz.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/employees?include=employment_periods,regular_working_times,internal_rates&modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Bei 700 Mitarbeitern: 4 Seiten statt 2.100 Aufrufen.

Übersicht

Pro Eltern-ObjektFlachFiltermodified_after
/projects/{id}/employees/project-employeesproject_id, employee_id (einzeln oder als Liste), project_status, project_start_date, project_end_datenein, eingrenzen mit /projects?modified_after
/employees/{username}/projects/project-employees?employee_id={username}wie obennein, eingrenzen mit /projects?modified_after
/receipts/{id}/amounts/receipts-amountsreceipt_id, employee_id, date_from, date_toja, Wasserzeichen aus /receipts
/invoices/{invoice_number}/items/invoice-itemsproject_id, id, status (einzeln oder als Liste), planned_from, planned_tonein
/projects/{id}/invoice-items/invoice-items?project_id={id}wie obennein
/employees/{username}/absences/absences?employee_id={username}employee_id, start_date, end_dateja
/employees/{username}/employment-periods, /regular-working-times, /internal-rates/employees?include=…personal_number, employed, employed_onja
/projects/{id}, /customers/{customer_number}, /employees/{username} nach der Liste/projects, /customers, /employeessiehe Filterja

Welche Änderungen das Eltern-Objekt aktualisieren

Die Datenbank aktualisiert modified eines Eltern-Objekts, wenn sich bestimmte Kind-Datensätze ändern. Damit grenzen Sie Abrufe pro Eltern-Objekt über dessen modified_after ein:

  • /projects?modified_after=… liefert ein Projekt auch dann, wenn eine Mitarbeiterzuordnung des Projekts oder eines seiner Vorgänge oder eine Tätigkeit oder ein Ort des Projekts angelegt, geändert oder gelöscht wurde, und wenn ein Vorgang angelegt oder geändert wurde. Eine Änderung der gebuchten Stunden eines Vorgangs (plan_hours_done, plan_hours_invoiced) zählt nicht.
  • /employees?modified_after=… liefert einen Mitarbeiter auch dann, wenn ein Beschäftigungszeitraum oder eine Regelarbeitszeit angelegt, geändert oder gelöscht wurde. Mit include=internal_rates liefert es auch einen Mitarbeiter, dessen interner Stundensatz angelegt oder geändert wurde; ein gelöschter Stundensatz wird nicht erkannt.
  • /receipts?modified_after=… liefert einen Beleg auch dann, wenn einer seiner Beträge angelegt oder geändert wurde.

Für gelöschte Vorgänge und gelöschte Belegbeträge, für Preistabellen und für Ansprechpartner von Kunden gibt es diese Garantie nicht. Lesen Sie diese von Zeit zu Zeit vollständig.

Daten, die es nur pro Eltern-Objekt gibt

Hierfür gibt es keine flache Liste. Am günstigsten lesen Sie sie so:

  • Vorgänge: /projects/{id}/tasks?modified_after=…&limit=200. Überspringen Sie Projekte, deren tasks_count in /projects 0 ist. Für die Stammdaten der Vorgänge fragen Sie nur die Projekte ab, die /projects?modified_after liefert; gebuchte Stunden ändern nur modified des Vorgangs selbst und brauchen deshalb den Abruf pro Projekt.
  • Mitarbeiter eines Vorgangs: /projects/{id}/tasks/{task_id}/employees nur für Vorgänge mit all_project_employees: false abrufen. Bei true ist die Liste immer leer, und jeder Mitarbeiter aus /project-employees?project_id={id} darf buchen. Das spart eine Anfrage pro Vorgang, bis zu 12.800 bei einem Mandanten mit 12.800 Vorgängen.
  • Tätigkeiten eines Projekts: /projects/{id}/activities nur für Projekte, deren activities_count über 0 liegt, und nach der ersten Ladung nur für die, die /projects?modified_after liefert.
  • Preistabellen: /projects/{id}/price-tables und /customers/{customer_number}/price-tables. Der Einzelabruf /projects/{id} enthält sie bereits als priceTables (dieselbe Liste wie /projects/{id}/price-tables?fallback=true), rufen Sie also nicht beides ab.
  • Ansprechpartner von Kunden: /customers/{customer_number}/contacts nur für Kunden, deren contacts_count in /customers über 0 liegt.
  • Angebotspositionen: /offers/{id}/items, eine Anfrage pro Angebot. /offers hat weder einen Positionszähler noch modified_after.
  • Belegdateien: /receipts/{id}/attachments nur für Belege mit filename. Ohne filename hat der Beleg keine Datei.

In den Beispielen oben summiert sich der Weg pro Eltern-Objekt für Projektzuordnungen, Projekt-Einzelabrufe und die drei Mitarbeiterlisten auf 5.409 Aufrufe, mehr als fünf Zeitfenster des Rate Limits. Der flache Weg braucht 93, ein Zehntel eines Zeitfensters.

Spart rund eine Anfrage je Eltern-Objekt, über das Sie nicht mehr laufen: 80 statt 1.650 für die Projektzuordnungen des Beispiel-Mandanten, etwa 95 %.

Generierte Clients

Den HTTP-Code müssen Sie nicht selbst schreiben: Erzeugen Sie einen Client aus der OpenAPI-Spezifikation. Unsere CI erzeugt und kompiliert bei jeder Änderung einen Java-Client aus der Spezifikation.