Synchron bleiben

Als Markdown ansehen

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.

Shell

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.

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

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.

Shell

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 sagt, was jeder bedeutet.