# Synchron bleiben

Sammeln Sie jede Datei ein, die sich seit Ihrer letzten Abfrage geändert hat, statt jede Datei einzeln abzufragen. `GET /public/v1/files` listet Dateien nach ihrer letzten Änderung, älteste zuerst. Ein Cursor merkt sich, wo Sie aufgehört haben. Der Schlüssel braucht die Berechtigung `documents:read`.

## Die erste Seite abfragen

Geben Sie `updated_since` an, um bei einem Zeitpunkt zu beginnen. Ohne beginnen Sie bei der ersten Datei.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "updated_since=2026-11-09T08:00:00Z" \
  --data-urlencode "limit=100"
```

Die Antwort enthält die Dateien, den Cursor und ob weitere folgen:

```json
{
  "files": [
    {
      "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
      "name": "invoice.pdf",
      "status": "read",
      "external_ref": "account.move,42",
      "documents": [
        { "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11", "kind": "invoice", "number": "RE-2026-1187", "pages": [1] }
      ],
      "updated_at": "2026-11-09T08:02:41Z"
    }
  ],
  "next_cursor": "MjAyNi0xMS0wOVQwODowMjo0MVo",
  "more": false
}
```

Eine Seite enthält bis zu `limit` Dateien, 1 bis 100, standardmäßig 50. Eine Datei kommt einmal je Änderung.

## Dem Cursor folgen

Solange `more` `true` ist, fragen Sie sofort erneut, mit `cursor` gleich `next_cursor`. Ist `more` `false`, merken Sie sich den letzten `next_cursor`. Fragen Sie bei der nächsten Abfrage damit, und Sie bekommen nur, was sich seitdem geändert hat.

```python
def changed_since(session, cursor=None):
    """Jede seit dem gemerkten Cursor geänderte Datei (None: alle)."""
    files = []
    while True:
        params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
        page = session.get(f"{API}/files", params=params, timeout=15).json()
        files += page["files"]
        cursor = page["next_cursor"] or cursor
        if not page["more"]:
            return files, cursor  # den Cursor für die nächste Abfrage merken
```

```javascript
async function changedSince(cursor) {
  const files = [];
  for (;;) {
    const params = new URLSearchParams({ limit: '100', ...(cursor ? { cursor } : {}) });
    const page = await fetch(`${API}/files?${params}`, { headers: auth }).then((r) => r.json());
    files.push(...page.files);
    cursor = page.next_cursor ?? cursor;
    if (!page.more) return { files, cursor }; // den Cursor für die nächste Abfrage merken
  }
}
```

## Nur fertige Dateien

Fragen Sie mit `status`, um nur Dateien in diesen Status zu listen. Wiederholen Sie es für mehrere.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "cursor=$CURSOR" \
  --data-urlencode "status=read" --data-urlencode "status=not_read" \
  --data-urlencode "status=failed"
```

`status` filtert erst nach dem Blättern. Eine Seite kann daher weniger Dateien als `limit` enthalten, oder keine. Folgen Sie `more`, nicht der Anzahl.

Behandeln Sie dann jede Datei nach ihrem Status. [Status und Gründe](https://docs.ocost.io/de/statuses.md) sagt, was jeder bedeutet.