# Offene Posten zum Stichtag (https://developer.bimetrics.de/recipes/open-items)

Die Offene-Posten-Liste der Kunden oder Lieferanten zu einem Stichtag lesen und als CSV oder PDF für die Kanzlei laden.

Die Offene-Posten-Liste (OPOS) zeigt zu einem Stichtag, was jeder Kunde noch schuldet und was die Firma jedem Lieferanten noch schuldet. Die Summe je Personenkonto ist sein Saldo, wie ihn der DATEV-Export bis zu diesem Tag ergibt. So lässt sie sich mit den Personenkonten in DATEV abgleichen.

## Ablauf

1. **Liste lesen:** [`GET /api/open-items`](https://developer.bimetrics.de/reference/open-items/get-open-items.md) mit `side=customers` für die Kunden oder `side=suppliers` für die Lieferanten und dem Stichtag in `asOf`, etwa `2026-12-31`. Ohne `asOf` gilt heute. Den Stichtag schreibst du als `JJJJ-MM-TT` (siehe [Datentypen](/data-types#kalenderdaten)).
2. **Auswerten:** Jeder Eintrag in `groups` ist ein Personenkonto mit seiner Summe in `totalMinor`, den Summen je Altersstufe in `buckets` und den Posten in `items`, die früheste Fälligkeit zuerst. `totalMinor` und `buckets` auf oberster Ebene gelten für die ganze Liste.
3. **Dateien für die Kanzlei:** [`GET /api/open-items/csv`](https://developer.bimetrics.de/reference/open-items/download-open-items-csv.md) liefert dieselbe Liste als CSV für Excel, eine Zeile je Posten, [`GET /api/open-items/pdf`](https://developer.bimetrics.de/reference/open-items/download-open-items-pdf.md) als PDF zum Weitergeben. Mit `download=1` nennt der Header `Content-Disposition` den Dateinamen, etwa `Offene-Posten-Kunden-2026-12-31.pdf`.

## Code

Du brauchst einen Schlüssel mit der Berechtigung `read` in der Umgebungsvariable `BIMETRICS_API_KEY`. Das Beispiel liest die offenen Posten der Kunden zum 31.12.2026, gibt je Konto die Summe und den Teil aus, der über 90 Tage überfällig ist, und speichert CSV und PDF. Das JavaScript-Beispiel braucht Node.js ab Version 20 und läuft nur als ES-Modul, weil es `import` und `await` außerhalb von Funktionen nutzt: Speichere es als `offene-posten.mjs` oder setze in deiner `package.json` `"type": "module"`.

```bash tab="cURL"
#!/usr/bin/env bash
set -euo pipefail

API="https://app.bimetrics.de/api"
AUTH="Authorization: Bearer $BIMETRICS_API_KEY"
QUERY="side=customers&asOf=2026-12-31"

# 1. Liste der Kunden zum Stichtag
curl --fail --silent --show-error --retry 5 -H "$AUTH" "$API/open-items?$QUERY" >offene-posten.json

# 2. Je Konto: offen gesamt und davon über 90 Tage überfällig, in Euro
jq -r '(.groups // [])[]
  | [.account, (if .collective then "Ohne Kundennummer" else .name end),
     (.totalMinor / 100), ((.buckets.over_90 // 0) / 100)]
  | @tsv' offene-posten.json

# 3. CSV und PDF für die Kanzlei
for ext in csv pdf; do
  curl --fail --silent --show-error --retry 5 -H "$AUTH" \
    -o "Offene-Posten-Kunden-2026-12-31.$ext" "$API/open-items/$ext?$QUERY"
done
```

```js tab="JavaScript"
import { writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const api = "https://app.bimetrics.de/api";
const auth = { Authorization: `Bearer ${process.env.BIMETRICS_API_KEY}` };
const query = "side=customers&asOf=2026-12-31";

// Liest eine Route und wiederholt bei 429 (nach Retry-After) und 5xx.
async function get(path, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`${api}${path}?${query}`, { headers: auth });
    if ((response.status === 429 || response.status >= 500) && attempt < attempts) {
      await sleep((Number(response.headers.get("Retry-After")) || 2 ** attempt) * 1000);
      continue;
    }
    if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
    return response;
  }
}

// 1. Liste der Kunden zum Stichtag
const list = await (await get("/open-items")).json();

// 2. Je Konto: offen gesamt und davon über 90 Tage überfällig
const euro = (cents) => (cents / 100).toFixed(2);
for (const group of list.groups ?? []) {
  const name = group.collective ? "Ohne Kundennummer" : group.name;
  console.log(group.account, name, euro(group.totalMinor), "davon über 90 Tage:", euro(group.buckets.over_90 ?? 0));
}

// 3. CSV und PDF für die Kanzlei
for (const ext of ["csv", "pdf"]) {
  const file = await get(`/open-items/${ext}`);
  await writeFile(`Offene-Posten-Kunden-2026-12-31.${ext}`, Buffer.from(await file.arrayBuffer()));
}
```

```python tab="Python"
import os
import time

import requests

API = "https://app.bimetrics.de/api"
PARAMS = {"side": "customers", "asOf": "2026-12-31"}
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BIMETRICS_API_KEY']}"

def get(path, attempts=5):
    """Liest eine Route und wiederholt bei 429 (nach Retry-After) und 5xx."""
    for attempt in range(1, attempts + 1):
        response = session.get(API + path, params=PARAMS, timeout=60)
        if (response.status_code == 429 or response.status_code >= 500) and attempt < attempts:
            time.sleep(int(response.headers.get("Retry-After", 2**attempt)))
            continue
        response.raise_for_status()
        return response

# 1. Liste der Kunden zum Stichtag
open_items = get("/open-items").json()

# 2. Je Konto: offen gesamt und davon über 90 Tage überfällig
for group in open_items["groups"] or []:
    name = "Ohne Kundennummer" if group["collective"] else group["name"]
    over_90 = group["buckets"].get("over_90", 0)
    print(group["account"], name, f"{group['totalMinor'] / 100:.2f}", "davon über 90 Tage:", f"{over_90 / 100:.2f}")

# 3. CSV und PDF für die Kanzlei
for ext in ("csv", "pdf"):
    with open(f"Offene-Posten-Kunden-2026-12-31.{ext}", "wb") as file:
        file.write(get(f"/open-items/{ext}").content)
```

## Was die Liste zählt

- **Buchungen bis zum Stichtag:** Es zählt jede Buchung auf einem Personenkonto bis einschließlich `asOf`: der Beleg mit seinem Belegdatum, eine Bankzahlung mit ihrer Wertstellung, eine erfasste Zahlung mit ihrem Zahltag. Die Zuordnungen gelten so, wie sie heute sind. Eine Zahlung, die vor dem Stichtag einging, aber erst danach zugeordnet wurde, gleicht ihren Beleg deshalb schon zum Stichtag aus.
- **Teilzahlung und Sammelposten:** Nach einer Teilzahlung bleibt ein Beleg mit seinem Rest offen. Ist eine Zahlung mehreren Belegen zugeordnet und bleibt ein Rest, steht er als ein Posten mit `kind` `collection` da. `documents` nennt die Belege; fällig ist der Posten mit dem frühesten.
- **Guthaben:** Eine Überzahlung ist ein Posten mit negativem `amountMinor`. Sie mindert die Summe des Kontos, wie in DATEV.
- **Sammelkonto:** Belege von Kontakten ohne Kunden- oder Lieferantennummer stehen wie im DATEV-Export auf dem Konto 10000 bzw. 70000, mit `collective` gleich `true`. Jeder Posten nennt dort in `name` seinen Kunden oder Lieferanten.
- **Was fehlt:** Abschlagsrechnungen bucht bimetrics bei Soll-Versteuerung und als Kleinunternehmer erst mit der Zahlung, ihr unbezahlter Rest fehlt deshalb. Belege mit einem Buchungsfehler sind noch gar nicht gebucht. Belege in fremder Währung ohne Euro-Betrag hält der DATEV-Export samt ihrer Zuordnung zurück, bis der Euro-Betrag feststeht. Alle drei fehlen deshalb in der Liste und im DATEV-Export. `downPayments` und `bookingErrors` nennen Zahl und Summe, `waitingForEuro` die Zahl der Belege und den Saldo ihrer weggelassenen Buchungen.

## Beträge und Daten

- Alle Beträge sind Euro-Cent als Ganzzahl. Bei den Kunden ist positiv, was der Kunde schuldet, bei den Lieferanten, was die Firma schuldet. Bei einem Beleg in Fremdwährung nennt der Posten zusätzlich `currency` und den Belegbetrag in dieser Währung in `originalAmountMinor`.
- `buckets` nennt nur Altersstufen mit Posten: `not_due`, `1_30`, `31_60`, `61_90` und `over_90`. Eine fehlende Stufe zählt als 0, deshalb setzen die Beispiele 0 ein.
- `date` und `dueDate` kommen als Objekt `{ "year", "month", "day" }` wie jedes Kalenderdatum in den Antworten. `daysOverdue` zählt von `dueDate` bis zum Stichtag; 0 oder weniger heißt nicht überfällig.
- Gibt es keine offenen Posten, ist `groups` leer.
