Der Beleg

Ocost liefert jeden gelesenen Beleg als ocost.document.v1. Fragen Sie ihn mit GET /public/v1/files/{file_id}/document oder GET /public/v1/documents/{document_id} ab. Die Felder folgen der EN 16931, der Norm hinter XRechnung, ZUGFeRD und Peppol UBL. Jedes Feld nennt seinen Business Term (BT-…) oder seine Gruppe (BG-…), und lässt sich so auf UBL oder CII abbilden.

Prüfen Sie gegen das JSON Schema oder erzeugen Sie Typen daraus. Felder und Werte unten listen alles, was es enthält.

Ein Beispiel

Eine Eingangsrechnung mit zwei Positionen zu 19 % und 2 % Skonto innerhalb von 14 Tagen:

{
  "schema": "ocost.document.v1",
  "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
  "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "pages": [1],
  "kind": "invoice",
  "kind_detail": "invoice",
  "direction": "incoming",
  "type_code": "380",
  "number": "RE-2026-1187",
  "issue_date": "2026-11-03",
  "due_date": "2026-12-03",
  "delivery_date": "2026-10-30",
  "invoicing_period_start": null,
  "invoicing_period_end": null,
  "valid_until": null,
  "currency": "EUR",
  "buyer_reference": null,
  "order_reference": "PO-2316",
  "order_references": ["PO-2316"],
  "preceding_invoice": null,
  "seller": {
    "name": "Musterbüro Lieferant GmbH",
    "vat_id": "DE123456789",
    "tax_registration_id": null,
    "legal_registration_id": "HRB 12345",
    "address": { "street": "Beispielweg 4", "postal_code": "50667", "city": "Köln", "country": "DE" },
    "contact": { "email": "rechnung@lieferant.example", "phone": null },
    "website": null
  },
  "buyer": {
    "name": "Beispiel Handel GmbH",
    "vat_id": "DE987654321",
    "tax_registration_id": null,
    "legal_registration_id": null,
    "address": { "street": "Hauptstraße 1", "postal_code": "40213", "city": "Düsseldorf", "country": "DE" },
    "contact": null,
    "website": null
  },
  "payee": null,
  "deliver_to": null,
  "other_parties": [],
  "payment": {
    "means_code": "58",
    "means": "transfer",
    "iban": "DE02120300000000202051",
    "bic": null,
    "terms": "14 Tage 2 % Skonto, 30 Tage netto",
    "net_days": 30,
    "paid_on": null
  },
  "early_payment_discounts": [
    { "days": 14, "percent": "2", "base_amount": null, "due_date": "2026-11-17" }
  ],
  "totals": { "net": "1068.00", "tax": "202.92", "gross": "1270.92", "payable": null, "prices_include_vat": false },
  "vat_breakdown": [
    { "category": "S", "rate": "19", "taxable_amount": "1068.00", "tax_amount": "202.92", "exemption_reason": null }
  ],
  "lines": [
    {
      "id": "1", "name": "Bürostuhl ErgoPlus schwarz", "seller_item_id": "ES-200", "standard_item_id": null,
      "quantity": "4", "unit": "H87", "price": "189.00", "base_quantity": null, "net_amount": "756.00",
      "discount_percent": null, "vat_category": "S", "vat_rate": "19",
      "ordered_quantity": null, "backordered_quantity": null, "batch": null, "pzn": null,
      "attributes": { "colour": "schwarz" }
    },
    {
      "id": "2", "name": "Montage", "seller_item_id": null, "standard_item_id": null,
      "quantity": "4", "unit": "HUR", "price": "78.00", "base_quantity": null, "net_amount": "312.00",
      "discount_percent": null, "vat_category": "S", "vat_rate": "19",
      "ordered_quantity": null, "backordered_quantity": null, "batch": null, "pzn": null,
      "attributes": {}
    }
  ],
  "deductions": [],
  "card": null,
  "worked_out": [],
  "sources": {
    "number": { "page": 1, "quote": "RE-2026-1187", "confidence": "read", "why": null },
    "totals.gross": { "page": 1, "quote": "1.270,92 €", "confidence": "checked", "why": null },
    "seller.vat_id": { "page": 1, "quote": "DE123456789", "confidence": "checked", "why": null }
  },
  "checks": [
    { "name": "vat", "passed": true, "sums": true, "fields": ["totals.net", "totals.tax"], "at": "19" },
    { "name": "gross", "passed": true, "sums": true, "fields": ["totals.net", "totals.tax", "totals.gross"], "at": null }
  ],
  "tax_check": { "case": "standard", "missing": [] },
  "attention": [],
  "possible_duplicate_of": null,
  "read_with": "reader"
}

Art und Richtung

Verzweigen Sie nach kind. Es fasst Ocosts viele Belegarten zu wenigen zusammen, etwa invoice, credit_note, delivery_note und contract. kind_detail nennt die genaue Art, zur Information. type_code gibt den UNCL-1001-Code der Rechnung, etwa 380 für eine Rechnung oder 381 für eine Gutschrift.

direction sagt, ob der Beleg incoming von einem Lieferanten kommt, outgoing von Ihrem Unternehmen, oder unsure ist. Ocost ermittelt es aus USt-IdNr., Steuernummer und Namen unter Einstellungen › Unternehmen. Halten Sie diese also aktuell.

Wie Werte geschrieben sind

Wie sicher Ocost ist

sources sagt für jeden Wert, nach seinem Pfad, wo er gelesen wurde: seine page und sein quote. Seine confidence ist eine von dreien:

checks listet jede Prüfung, die Ocost im Code ausführte, mit passed. Die Prüfungen mit sums: true rechnen die Beträge nach. Füllen Sie eine Rechnung ohne Blick einer Person nur, wenn jede davon bestanden hat.

attention listet, was sich eine Person vor dem Buchen ansehen sollte, etwa ein mögliches Duplikat. tax_check enthält die Prüfung einer Eingangsrechnung nach § 14 UStG.

from decimal import Decimal

document = session.get(f"{API}/files/{file_id}/document", timeout=15).json()
sums_hold = all(c["passed"] for c in document["checks"] if c["sums"])
gross = Decimal(document["totals"]["gross"]) if document["totals"]["gross"] else None
doubts = [path for path, s in document["sources"].items() if s["confidence"] == "doubt"]

const document = await fetch(`${API}/documents/${documentId}`, { headers: auth }).then((r) => r.json());
const sumsHold = document.checks.filter((c) => c.sums).every((c) => c.passed);
// Beträge sind Zeichenketten: als solche behalten oder mit einer Dezimal-Bibliothek rechnen.
console.log(document.number, document.totals.gross, sumsHold);

Versionen

Die Form ist stabil. Innerhalb von v1 kann Ocost einer Liste Werte hinzufügen, benennt aber nie ein Feld oder einen Wert um und entfernt keines. Behandeln Sie ein unbekanntes kind als other, und scheitern Sie nie an einem unbekannten Wert. Eine inkompatible Änderung kommt als ocost.document.v2 unter /public/v2, und v1 bleibt 12 weitere Monate.

Felder

Jedes Feld, aus Ocosts Code geschrieben. Das JSON Schema enthält dasselbe. Die Beschreibungen stehen dort wie hier auf Englisch.

Document

Party

Address

OtherParty

Payment

EarlyPaymentDiscount

Totals

VatGroup

Line

Deduction

Card

WorkedOut

Source

Check

TaxCheck

Contact

Fact

TaxItem

Werte

Jede Werteliste, aus Ocosts Code geschrieben. Das JSON Schema und die API-Referenz enthalten dasselbe, die Bedeutungen auf Englisch. Eine spätere Ocost-Version kann in v1 Werte ergänzen. Behandeln Sie ein unbekanntes kind als other und lassen Sie jeden anderen unbekannten Wert beiseite. In v1 wird kein Wert umbenannt oder entfernt.

kind

What a document is, grouped so an integrator branches on few; the exact kind is kind_detail.

kind_detail

The exact kind, one of Ocost's document types, for information: branch on kind, which groups them (the guide's reference lists which).

Jedes kind_detail, nach dem kind, das es ist:

direction

Whether the business received or issued it.

other_parties[].role

What another party is to the document; printed_role is its words.

payment.means_code

BT-81: how it is paid, UNCL 4461.

payment.means

How it is paid, as a word.

vat_breakdown[].category, lines[].vat_category

BT-118, BT-151: the VAT category, UNCL 5305 as EN 16931 uses it.

card.facts[].kind

What a fact on a document's card is.

worked_out[].field

The amount worked out, by its path.

worked_out[].rule

How Ocost worked an amount out.

sources.*.confidence

How sure Ocost is of a value, from its checks: never a model's grade.

checks[].name

A check Ocost ran in code on what it read.

tax_check.case

Which German rules an incoming invoice is held to.

tax_check.missing[].item

What an invoice lacks, or has wrong, for its case.

attention[]

What a person should look at before booking it.

read_with

How Ocost read it: never a model's or provider's name.

type_code

UNCL 1001, ein bis drei Ziffern. Eine E-Rechnung kann einen Code tragen, der hier fehlt. Wo der Beleg keinen druckt, schreibt Ocost den seiner Art:

sources

Die Pfade, die sources, checks[].fields und worked_out[].field nennen, n ab 0. Eine spätere Ocost-Version kann Pfade ergänzen:

number, issue_date, due_date, delivery_date, valid_until, currency, order_reference, seller.name, buyer.name, seller.vat_id, buyer.vat_id, seller.contact.email, buyer.contact.email, seller.contact.phone, buyer.contact.phone, seller.website, buyer.website, seller.legal_registration_id, buyer.legal_registration_id, totals.net, totals.tax, totals.gross, totals.payable, payment.iban, payment.means_code, payment.paid_on, lines, other_parties[n].name, deductions[n].gross