Sieben Wege für eigene Systeme — Konten, Buchungen, offene Posten, Planwerte, Kategorien, die Arbeitsfläche als Daten und die Kennzahlen.

Wofür diese Seite da ist

Damit Yupana nicht die letzte Station ist. Die Schnittstelle liefert eure Zahlen an eigene Systeme — an ein Auswertungswerkzeug, an ein Warenwirtschafts- system, an eine Tabelle, die jemand jeden Montag zieht.

⚠️ Sie ist Teil der Stufe „Gruppe“. In den Stufen darunter gibt es sie nicht.

Was du siehst

Die Einstellungen von Yupana, in denen auch die Schlüssel der Schnittstelle verwaltet werden. — Schlüssel werden in den Einstellungen angelegt und widerrufen. Der Widerruf wirkt sofort — es gibt keinen Zwischenspeicher, der ihn überlebt.

Die Liste eurer Schlüssel mit Namen, den ersten acht Zeichen, den vergebenen Rechten, dem Ablaufdatum und wann er zuletzt benutzt wurde.

Ein Knopf je Schlüssel zum Widerrufen. Er wirkt sofort.

Das Zugriffsprotokoll: welcher Schlüssel wann welchen Weg gerufen hat und welche Antwort kam. Ohne Inhalte — ein Protokoll, das Nutzdaten mitschreibt, wäre ein zweiter Datenbestand mit denselben Schutzanforderungen.

Woher die Zahlen kommen

Aus derselben Quelle wie die Anwendung. /v1/vorschau liefert exakt das, was auf /liquiditaet steht — dieselbe Rechnung, dieselbe Regel, dieselbe Zahl. Es gibt keinen zweiten Rechenweg für die Schnittstelle.

Was du damit machst

Anmelden

Jede Anfrage trägt den Schlüssel im Kopf:

curl https://api.yupana.de/v1/konten \
  -H "Authorization: Bearer yup_DEIN_SCHLUESSEL"

Die sieben Wege

Konten und Salden. Ein Konto ohne Saldo liefert saldo: null — das heißt „nicht bekannt“, nicht „null Euro“.

curl https://api.yupana.de/v1/konten -H "Authorization: Bearer $KEY"

Buchungen lesen. Seitenweise über cursor, höchstens 200 je Seite.

curl "https://api.yupana.de/v1/buchungen?von=2026-01-01&bis=2026-12-31" \
  -H "Authorization: Bearer $KEY"

Eine fremde Zahlung einspielen — aus Stripe, PayPal oder der Kasse. Die fremdId macht das wiederholbar: Dieselbe ID wird nicht zweimal angelegt.

curl -X POST https://api.yupana.de/v1/buchungen \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"kontoId":"…","datum":"2026-09-04","betragMinor":499900,
       "waehrung":"EUR","richtung":"einzahlung","partner":"Stripe",
       "fremdId":"pi_3Abc123"}'

Offene Posten lesen.

curl https://api.yupana.de/v1/posten -H "Authorization: Bearer $KEY"

Das erwartete Zahldatum setzen — die Erwartung, nicht die Fälligkeit.

curl -X PATCH "https://api.yupana.de/v1/posten/forderung:centron:RE-2026-0847" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"erwartetAm":"2026-10-15","notiz":"Ratenzahlung vereinbart"}'

Planwerte lesen und setzen. Die Notiz ist Pflicht.

curl https://api.yupana.de/v1/planwerte -H "Authorization: Bearer $KEY"

curl -X POST https://api.yupana.de/v1/planwerte \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"kategorieId":"…","periode":"2026-10","betragMinor":-4025004,
       "notiz":"Mietvertrag vom 01.03.2024"}'

Den Kategorienbaum lesen — flach mit elternId, damit ihr ihn bauen könnt, ohne ihn zu erraten.

curl https://api.yupana.de/v1/kategorien -H "Authorization: Bearer $KEY"

Die Arbeitsfläche als Daten. Je Kategorie und Periode vier Größen.

curl "https://api.yupana.de/v1/vorschau?von=2026-01-01&bis=2026-12-31" \
  -H "Authorization: Bearer $KEY"

Die Kennzahlen des Monatsblicks.

curl "https://api.yupana.de/v1/kennzahlen?periode=2026-06" \
  -H "Authorization: Bearer $KEY"

Die Beschreibung maschinenlesbar

curl https://api.yupana.de/v1/openapi.json

Fallen

⚠️ Beträge sind immer Cent, immer Ganzzahlen. betragMinor: 499900 sind 4.999,00 €. Wer sie als Euro-Fließkommazahl weiterverarbeitet, baut sich einen Rundungsfehler ein, der in einer Buchhaltung kein Rundungsfehler bleibt.

⚠️ Der Betrag einer Buchung ist immer positiv. Die Richtung steht in richtung, nie im Vorzeichen. Ein Minus im Betrag wird abgelehnt, statt still umgedeutet zu werden.

⚠️ Blättert über cursor, nie über offset. Ein Offset verschiebt sich, wenn während des Blätterns eine Zeile dazukommt — ihr überspringt dann still einen Datensatz.

⚠️ Der Schlüssel ist genau einmal sichtbar. Bei der Erstellung. Danach gibt es keinen Weg, ihn anzuzeigen — auch nicht für uns. Wer ihn verliert, legt einen neuen an und widerruft den alten.

⚠️ null heißt „nicht bekannt“, nicht „null“. Ein Konto ohne Saldo, eine Kennzahl ohne Wert, eine Zelle ohne Plan — überall dasselbe. Wer null als Null verrechnet, bekommt eine Bilanz, die aufgeht und falsch ist.

⚠️ 600 Anfragen je Minute und Schlüssel. Darüber kommt 429 mit Retry-After. Die Bremse zählt je Schlüssel, nicht je IP-Adresse — ein Kunde hinter einem Firmenanschluss teilt sich die Adresse mit allen Kollegen.

Verwandt

Die Arbeitsfläche — dieselben Zahlen zum Ansehen
Sicherheit — wie Yupana eure Daten schützt

Die Schnittstelle