Schnellstart

Als Markdown ansehen

Fünf Schritte von null zur ersten Rechnung als JSON. Sie brauchen ein Ocost-Konto, in dem Sie Inhaber oder Buchhaltung sind.

1. Registrieren

Registrieren Sie sich unter https://app.ocost.io/auth/sign-up, oder melden Sie sich an. Dateien, die Sie über die API schicken, stehen wie jeder Upload unter Dateien.

2. Einen Schlüssel erstellen

Öffnen Sie Einstellungen › API und wählen Sie Schlüssel erstellen.
Benennen Sie den Schlüssel nach seinem Nutzer, etwa „Odoo Produktion“.
Lassen Sie die vorgegebenen Berechtigungen angehakt und wählen Sie Schlüssel erstellen.
Wählen Sie Schlüssel kopieren. Der Schlüssel beginnt mit ocost_sk_, und Ocost zeigt ihn nur einmal.

Legen Sie ihn für die nächsten Schritte in Ihrer Shell ab:

Shell

export OCOST_KEY="ocost_sk_…"

3. Ein PDF schicken

Schicken Sie die Datei als multipart/form-data im Feld file. external_ref ist Ihre eigene Kennung, und Ocost gibt sie zurück.

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

import os

import requests

API = "https://api.ocost.io/public/v1"
auth = {"Authorization": f"Bearer {os.environ['OCOST_KEY']}"}

with open("invoice.pdf", "rb") as f:
    sent = requests.post(
        f"{API}/files",
        headers=auth,
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={"external_ref": "account.move,42"},
        timeout=30,
    )
sent.raise_for_status()
file = sent.json()

import { readFile } from 'node:fs/promises';

const API = 'https://api.ocost.io/public/v1';
const auth = { Authorization: `Bearer ${process.env.OCOST_KEY}` };

const form = new FormData();
form.append(
  'file',
  new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }),
  'invoice.pdf',
);
form.append('external_ref', 'account.move,42');
const sent = await fetch(`${API}/files`, { method: 'POST', headers: auth, body: form });
let file = await sent.json();

Ocost antwortet 202 Accepted und beginnt zu lesen:

JSON

{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "name": "invoice.pdf",
  "status": "received",
  "reason": null,
  "external_ref": "account.move,42",
  "documents": [],
  "sha256": "0edd5593…"
}

4. Warten, bis sie gelesen ist

Fragen Sie die Datei alle paar Sekunden ab, solange ihr status received oder reading ist. Die meisten PDFs brauchen unter einer Minute.

curl -sS https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"

import time

for wait in [2, 2, 3, 5, 5, 10, 10, 15, 30, 30]:
    file = requests.get(f"{API}/files/{file['id']}", headers=auth, timeout=15).json()
    if file["status"] not in ("received", "reading"):
        break
    time.sleep(wait)

while (file.status === 'received' || file.status === 'reading') {
  await new Promise((done) => setTimeout(done, 3000));
  file = await (await fetch(`${API}/files/${file.id}`, { headers: auth })).json();
}

Eine gelesene Datei listet ihre Belege:

JSON

{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "status": "read",
  "documents": [
    {
      "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
      "kind": "invoice",
      "number": "RE-2026-1187",
      "pages": [1]
    }
  ]
}

Endet eine Datei mit not_read oder failed, nennt reason den Grund. Status und Gründe listet sie auf.

5. Den Beleg lesen

Fragen Sie den ersten Beleg der Datei ab.

curl -sS https://api.ocost.io/public/v1/files/$FILE_ID/document \
  -H "Authorization: Bearer $OCOST_KEY"

document = requests.get(
    f"{API}/files/{file['id']}/document", headers=auth, timeout=15
).json()
print(document["number"], document["totals"]["gross"], document["currency"])

const document = await (
  await fetch(`${API}/files/${file.id}/document`, { headers: auth })
).json();
console.log(document.number, document.totals.gross, document.currency);

Die Antwort ist die Rechnung als ocost.document.v1, hier gekürzt:

JSON

{
  "schema": "ocost.document.v1",
  "kind": "invoice",
  "number": "RE-2026-1187",
  "issue_date": "2026-11-03",
  "due_date": "2026-12-03",
  "currency": "EUR",
  "seller": { "name": "Musterbüro Lieferant GmbH", "vat_id": "DE123456789" },
  "totals": { "net": "1068.00", "tax": "202.92", "gross": "1270.92" }
}

Weiter

Eine Datei schicken und lesen erklärt erneutes Schicken und Löschen.
Synchron bleiben sammelt jede Änderung mit einem Aufruf ein.
Der Beleg erklärt jedes Feld.
Suche findet Belege nach Wörtern und nach Bedeutung.
Odoo anbinden füllt Rechnungsentwürfe.