Dateien und Status

Eine Datei ist ein PDF, ein Bild oder eine E-Rechnung, die Sie schicken. Sie enthält einen oder mehrere Belege: Ein Scan von drei Rechnungen ist eine Datei mit drei Belegen.

Eine Datei schicken

POST /public/v1/files, multipart/form-data, Berechtigung documents:write:

Jede Antwort trägt X-Ocost-Documents-Left, die Belege, die Ihr Tarif in diesem Monat noch hat.

curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@scan.pdf" -F "name=scan.pdf" -F "external_ref=account.move,42"

Status

GET /public/v1/files/{file_id} (Berechtigung documents:read) liefert die Datei mit ihrem status:

Auf eine Datei warten

Fragen Sie eine halbe Minute lang alle 2 bis 3 Sekunden ab, danach alle 10 bis 30. Die meisten PDFs brauchen unter einer Minute, lange einige.

Für viele Dateien listen Sie die Änderungen: zuerst mit updated_since (oder ohne, für alle), dann dem Cursor nach.

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 "status=read" --data-urlencode "status=not_read" \
  --data-urlencode "status=failed"

• Älteste Änderung zuerst, bis zu limit (1 bis 100, Standard 50), eine Datei einmal je Änderung.
• Solange more wahr ist, holen Sie mit cursor=<next_cursor> die nächste Seite; danach merken Sie sich den Cursor für die nächste Abfrage.
• status filtert erst nach dem Blättern, eine Seite kann also weniger als limit enthalten: Folgen Sie more, nicht der Anzahl.

Auf eine Datei warten und alles einsammeln, was sich seit der letzten Abfrage geändert hat:

def wait_for(session, file_id, timeout=300):
    started = time.monotonic()
    while time.monotonic() - started < timeout:
        file = session.get(f"{API}/files/{file_id}", timeout=15).json()
        if file["status"] not in ("received", "reading"):
            return file
        time.sleep(3 if time.monotonic() - started < 30 else 15)
    return file

// Jede seit dem gemerkten Cursor geänderte Datei (null: alle).
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 }; // `cursor` fürs nächste Abfragen merken
  }
}

Das Original

GET /public/v1/files/{file_id}/content liefert die Bytes, wie sie geschickt wurden.

Eine Datei löschen

DELETE /public/v1/files/{file_id} (Berechtigung documents:write) löscht die Datei mit ihren Belegen, allem Gelesenen, ihrem Suchindex und dem Original, sofort und endgültig.