Inkrementeller Abgleich

Fünf Endpoints unterstützen Zeitstempel-Filter für einen inkrementellen Abgleich: createdSince, createdUntil, updatedSince, updatedUntil und deletedSince. Welche Filter an welchem Endpoint verfügbar sind, steht in der Parameter-Tabelle des jeweiligen Endpoints.

Erlaubte Zeitformate

Erlaubt sind drei Formate: ISO 8601 mit Offset (2026-08-01T00:00:00+02:00), ISO 8601 ohne Offset (2026-08-01T00:00:00) oder ein reines Datum (2026-08-01). Bruchteilsekunden sind ebenfalls erlaubt (2026-08-24T10:00:00.123+02:00).

Das ist genau das Format, das new Date().toISOString() in JavaScript erzeugt. Gängige Rust- und Python-Serializer liefern dasselbe Format.

Bei einem reinen Datum setzt die API *Since-Parameter auf 00:00:00 und *Until-Parameter auf 23:59:59. Unterstützt ein Endpoint einen Parameter nicht, ignoriert die API ihn still.

Ungültige Werte

Ein ungültiger Wert wird mit 400 validation_error abgelehnt und nicht korrigiert. 2026-02-30 verschiebt die API also nicht still auf den 2. März.

Zeitzonen

Ein Wert ohne UTC-Offset gilt als lokale Zeit des Servers. Weicht deine Zeitzone davon ab, verschiebt sich das Abfragefenster um die Differenz. An der Sync-Grenze fehlen dir dann Änderungen, oder du bekommst sie doppelt.

Schicke den Wert deshalb immer mit Offset, zum Beispiel 2026-08-01T00:00:00+02:00. Die API übernimmt diesen Offset unverändert, auch in den zurückgegebenen Zeitstempeln.

Sortierung im Filter-Modus

Ohne Zeitstempel-Filter behält jeder Endpoint seine eigene Standard-Sortierung, wie im jeweiligen Endpoint-Artikel beschrieben. Sobald du einen Zeitstempel-Filter setzt, wechselt die Sortierung auf interne ID aufsteigend. Diese Reihenfolge bleibt über die gesamte Paginierung stabil.

Ein Datensatz kann dir dadurch höchstens doppelt geliefert werden, aber nie fehlen. Pflege deine Daten deshalb per Upsert über die id ein – dann sind Doppelte unkritisch.

Cursor für den nächsten Durchlauf

Die API sortiert im Filter-Modus nach interner ID, nicht nach Zeitstempel. Das letzte Element einer Seite trägt deshalb nicht den jüngsten Zeitstempel. Bildest du deinen Cursor daraus, überspringst du Änderungen.

Nimm stattdessen den größten Zeitstempel über alle Seiten des gesamten Durchlaufs. Setze ihn erst, wenn der Durchlauf vollständig abgeschlossen ist.

Bricht der Durchlauf ab, lass den alten Cursor stehen und wiederhole den Durchlauf komplett. Zieh vom neuen Cursor außerdem eine kleine Sicherheitsmarge ab, etwa eine Minute.

Restrisiko der Paginierung

Ein Datensatz kann trotzdem übersprungen werden, wenn er die Ergebnismenge während der Paginierung verlässt. Die Menge schrumpft dann, und alles dahinter rutscht eine Position vor.

Der Datensatz an der Seitengrenze fällt so aus dem Durchlauf. Sein Zeitstempel bleibt unverändert und liegt unter dem Cursor, den du danach setzt – er wird also nicht nachgeholt.

Das passiert typischerweise, wenn ein Datensatz während des Durchlaufs über eine gesetzte updatedUntil-Grenze hinaus bearbeitet wird. Lass updatedUntil beim inkrementellen Abgleich deshalb weg.

meta.total bei eingeschränkten Rechten

total wird in der Datenbank gezählt, die Berechtigungsprüfung greift erst danach. Hat dein API-Zugang eingeschränkte Rechte, enthalten die Seiten weniger Datensätze als total erwarten lässt.

Eine Abbruchbedingung wie „paginieren, bis alle total Datensätze angekommen sind" terminiert deshalb nicht. Paginiere stattdessen, bis eine Seite weniger als limit Datensätze enthält oder leer ist.

Wann der Vollabgleich trotzdem nötig ist

Der inkrementelle Abgleich ersetzt den Vollabgleich nicht in jedem Fall. Drei Situationen bleiben:

• Endpoints ohne Löschzeitpunkt, etwa Rechnungen und Honorarnoten, melden Löschungen gar nicht. Nur ein periodischer Vollabgleich zeigt, welche Datensätze verschwunden sind.
• Ein wiederhergestellter Datensatz verschwindet aus dem Lösch-Abgleich. Er taucht stattdessen im Änderungs-Abgleich wieder auf, sofern dein Client das Feld deleted auswertet.
• Ist meta.total größer als die Menge, die deine Rechte dir liefern, bleiben dir Datensätze verborgen. Das erkennst du nur mit einem Vollabgleich ohne Zeitstempel-Filter.

Details zu Löschzeitpunkten und Wiederherstellung stehen im jeweiligen Endpoint-Artikel.