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ätzlichpriceTables./customers/{customer_number}enthält zusätzlichaddresses,managersundpriceTables. Die Liste hat stattdessen Zähler, zum Beispieladdresses_count,contacts_countundmanagers_count./employees/{username}enthält zusätzlichabsences_count. Die Liste versteht dasselbeincludewie 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-Objekt | Flach | Filter | modified_after |
|---|---|---|---|
/projects/{id}/employees | /project-employees | project_id, employee_id (einzeln oder als Liste), project_status, project_start_date, project_end_date | nein, eingrenzen mit /projects?modified_after |
/employees/{username}/projects | /project-employees?employee_id={username} | wie oben | nein, eingrenzen mit /projects?modified_after |
/receipts/{id}/amounts | /receipts-amounts | receipt_id, employee_id, date_from, date_to | ja, Wasserzeichen aus /receipts |
/invoices/{invoice_number}/items | /invoice-items | project_id, id, status (einzeln oder als Liste), planned_from, planned_to | nein |
/projects/{id}/invoice-items | /invoice-items?project_id={id} | wie oben | nein |
/employees/{username}/absences | /absences?employee_id={username} | employee_id, start_date, end_date | ja |
/employees/{username}/employment-periods, /regular-working-times, /internal-rates | /employees?include=… | personal_number, employed, employed_on | ja |
/projects/{id}, /customers/{customer_number}, /employees/{username} nach der Liste | /projects, /customers, /employees | siehe Filter | ja |
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. Mitinclude=internal_ratesliefert 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, derentasks_countin/projects0ist. Für die Stammdaten der Vorgänge fragen Sie nur die Projekte ab, die/projects?modified_afterliefert; gebuchte Stunden ändern nurmodifieddes Vorgangs selbst und brauchen deshalb den Abruf pro Projekt. - Mitarbeiter eines Vorgangs:
/projects/{id}/tasks/{task_id}/employeesnur für Vorgänge mitall_project_employees: falseabrufen. Beitrueist 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}/activitiesnur für Projekte, derenactivities_countüber0liegt, und nach der ersten Ladung nur für die, die/projects?modified_afterliefert. - Preistabellen:
/projects/{id}/price-tablesund/customers/{customer_number}/price-tables. Der Einzelabruf/projects/{id}enthält sie bereits alspriceTables(dieselbe Liste wie/projects/{id}/price-tables?fallback=true), rufen Sie also nicht beides ab. - Ansprechpartner von Kunden:
/customers/{customer_number}/contactsnur für Kunden, derencontacts_countin/customersüber0liegt. - Angebotspositionen:
/offers/{id}/items, eine Anfrage pro Angebot./offershat weder einen Positionszähler nochmodified_after. - Belegdateien:
/receipts/{id}/attachmentsnur für Belege mitfilename. Ohnefilenamehat 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.