Anmelden

Das Belegschema

Als Markdown ansehen

GET /public/v1/files/{file_id}/document und GET /public/v1/documents/{document_id} liefern einen Beleg als ocost.document.v1, in den Begriffen der EN 16931 (der E-Rechnungsnorm hinter XRechnung, ZUGFeRD und Peppol UBL). Jeder Wert nennt seinen Business Term (BT-…) oder seine Gruppe (BG-…) und lässt sich so auf UBL oder CII abbilden.

Das Format ist stabil: Eine inkompatible Änderung kommt als ocost.document.v2 unter /public/v2, v1 bleibt noch 12 Monate erreichbar.

Konventionen

  • Beträge und Mengen: Dezimalzeichenketten wie gedruckt ("1270.92", "2.5"), nie Zahlen. Nutzen Sie einen Dezimaltyp.
  • Sätze: Prozent-Zeichenketten ("19", "7", "0", "5.5").
  • Daten nach ISO 8601 (2026-11-03), Währungen nach ISO 4217 (EUR), Länder nach ISO 3166-1 alpha-2 (DE).
  • Einheiten: UNECE-Empfehlung 20 (C62 eins, H87 Stück, HUR Stunde, KGM Kilogramm) und Verpackungen der Empfehlung 21 mit ihrem X (XCT Karton, XPF Palette). Unbekannt ist null, nie C62.
  • Fehlt etwas, ist es null: nicht gedruckt oder verworfen, weil Ocost nicht sicher war. Ocost rät nie.

Die Felder

FeldEN 16931Bedeutung
schemaImmer "ocost.document.v1".
id, file_idDer Beleg und seine Datei.
pagesSeine Seiten in der Datei, ab 1.
kindinvoice (jede zu zahlende Rechnung: Abschlags-, Schluss-, Anzahlungs-, Sammel-, Dauerrechnung; type_code sagt, welche), credit_note, invoice_correction, receipt, pro_forma, delivery_note, order, order_confirmation, quote, contract (Miet-, Versicherungs-, sonstige Verträge), statement (Abrechnung eines Factors), payment_reminder, other. kind_detail ist die genaue Art, zur Information.
directionincoming (die Rechnung eines Lieferanten), outgoing (Ihr Unternehmen hat ihn ausgestellt) oder unsure. Ermittelt aus USt-IdNr., Steuernummer und Namen unter Einstellungen › Unternehmen: Halten Sie sie aktuell.
type_codeBT-3UNCL 1001: 380 Rechnung, 381 Gutschrift, 384 korrigierte Rechnung, 326 Abschlagsrechnung, 386 Anzahlungsrechnung, 389 Gutschriftsverfahren, 325 Proforma.
number, issue_date, due_dateBT-1, BT-2, BT-9Nummer, Rechnungsdatum, Fälligkeit.
delivery_dateBT-72Lieferdatum.
invoicing_period_start, invoicing_period_endBT-73, BT-74Der abgerechnete Zeitraum.
valid_untilBei einem Angebot.
currencyBT-5Währung.
buyer_referenceBT-10Referenz des Käufers.
order_reference, order_referencesBT-13Die Bestellung und jede genannte Bestellung.
preceding_invoiceBT-25Worauf sich eine Gutschrift oder Korrektur bezieht.
seller, buyerBG-4, BG-7Je: name (BT-27, BT-44), vat_id (BT-31, BT-48), tax_registration_id (BT-32, die Steuernummer), legal_registration_id (BT-30, BT-47, der Registereintrag), address (street, postal_code, city, country), contact (email, phone), website.
payeeBG-10Wer bezahlt wird, wenn nicht der Verkäufer (ein Factor).
deliver_toBG-15Die Lieferanschrift.
other_parties[]Jede weitere genannte Partei, mit role (invoicee, service_recipient, payer, ship_to, carrier, debtor, landlord, tenant, contractor, …) und printed_role (wie gedruckt).
paymentBG-16means_code (BT-81, UNCL 4461: 58 SEPA-Überweisung, 59 SEPA-Lastschrift, 48 Karte), means (als Wort oder already_paid), iban (BT-84), bic (BT-86), terms (BT-20 wie gedruckt), net_days (Tage bis zur vollen Zahlung ab Rechnungsdatum), paid_on (der Tag, an dem er laut Beleg bezahlt wurde).
early_payment_discounts[]BT-20Skonto (#SKONTO# der XRechnung): days, percent, base_amount (null: vom fälligen Betrag), due_date (Rechnungsdatum plus days).
totalsBG-22net (BT-109), tax (BT-110), gross (BT-112), payable (BT-115, noch zu zahlen; null, wenn es der Bruttobetrag ist), prices_include_vat (wie auf einer Quittung).
vat_breakdown[]BG-23category (BT-118, UNCL 5305: S Regelsatz, Z Nullsatz, E steuerfrei, AE Reverse Charge, K innergemeinschaftlich, G Ausfuhr, O nicht steuerbar), rate (BT-119), taxable_amount (BT-116), tax_amount (BT-117), exemption_reason (BT-120).
lines[]BG-25id (BT-126, die Position), name (BT-153), seller_item_id (BT-155, Artikelnummer), standard_item_id (BT-157, GTIN), quantity (BT-129), unit (BT-130), price (BT-146, netto), base_quantity (BT-149, für wie viele Einheiten price gilt; null: eine), net_amount (BT-131), discount_percent, vat_category (BT-151), vat_rate (BT-152); wo gedruckt, ordered_quantity, backordered_quantity, batch, pzn, attributes (Farbe, Größe, Material, Marke, …).
deductions[]Die früheren Rechnungen, die eine Schlussrechnung abzieht: number, issue_date, net, tax, gross.
cardFür einen Beleg ohne eigene Felder (ein Prüfbericht, ein Brief): title, summary, facts (label, kind, date, amount, currency, number, text, page), Fristen zuerst.
worked_out[]Ein Betrag, den Ocost ausgerechnet hat, weil der gelesene nicht stimmen kann: field, printed, rule.
sourcesJe Wert, nach Pfad (number, totals.gross, seller.vat_id, …): page, quote (die gelesenen Worte), confidence und bei Zweifel why.
checks[]Jede Prüfung, die Ocost im Code ausgeführt hat: name, passed, sums (eine Summenprüfung), fields (Pfade), at (der Satz oder die Position).
tax_checkEine Eingangsrechnung nach § 14 UStG: case (standard, small, reverse_charge, intra_eu, exempt) und missing[] (item, law, at_stake: Fehlt es, kostet es den Vorsteuerabzug). Null für Arten, die nicht geprüft werden.
attention[]Worauf ein Mensch vor dem Buchen schauen sollte: sums (eine Summe stimmt nicht), outgoing, possible_duplicate, self_billed (Gutschriftsverfahren).
possible_duplicate_ofEin früherer Beleg derselben Art und Nummer vom selben Verkäufer, sonst null.
read_withe_invoice (genau aus dem XML) oder reader (aus den Seiten).

confidence in sources:

  • checked: Eine Prüfung hat den Wert bestätigt, oder er stammt aus einer E-Rechnung.
  • read: Nichts spricht dagegen.
  • doubt: Eine Prüfung schlug fehl (why nennt sie), oder seine Worte stehen nicht auf seiner Seite.

Die Summenprüfungen in checks sind total, vat, vat_net, vat_tax, gross, payable, signs, skonto, deduction, deductions und quantity. Füllen Sie eine Rechnung ohne Blick eines Menschen nur, wenn jede Prüfung mit sums: true bestanden ist.

Ein Beispiel

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

JSON
{
  "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"
}

Auslesen

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"]