Dokumente-Guide

Ebene 2 — Details zum Fluss ③ des Agenten-Hubs. Urkunden = die Dokumente der öffentlichen Plattform Firmenbuch (via HVD): Jahresabschlüsse, Gründungsurkunden, Bestätigungsvermerke — als PDF oder XML.

1 Liste ziehen: hvd/suche-urkunde

curl "https://skale.dev/firmenindex/api?e=hvd%2Fsuche-urkunde&fnr=475207i"

Antwort: results[] — je Eintrag key (Download-Schlüssel), dokumentart_text (z. B. „Jahresabschluss“), stichtag, content_type (application/pdf | XML), dateiendung, groesse (Bytes), az (Aktenzeichen). Alternativ per Aktenzeichen: &az=….

Leere Liste (404 not_found) ist ein Prüfergebnis („keine Urkunden“) — e.U./junge Firmen haben oft keine, kein Fehler.

2 Dokument holen: hvd/urkunde-get?key=…

Zwei Fälle — die Liste verrät es über content_type, die Semantik entscheidet aber erst der Fetch:

• PDF (application/pdf) → rohes PDF, direkt verwendbar.
• XML → einer von zwei Unterfällen:
  1. FinanzOnline-Strukturdaten — die maschinenlesbare Bilanz: Zahlen stehen als POSTENZEILE/BETRAG, die Semantik in den Gliederungs-Tags (HGB_224_3 = §224 Abs 3 UGB u. a.). Direkt parsen — das ist der Fall, in dem XML mehr wert als PDF ist.
  2. XML mit eingebetteten PDF-Anhängen — Anhänge (ANHANG, LAGEBERICHT, BESTAETIGUNGSVERMERK, …) liegen als base64 im Tag (<TAG type="base64">JVBERi…, JVBERi = PDF-Magic). Base64 dekodieren, fertige PDFs.

Im Browser macht die Dokumente-Sektion exakt das: XML-Viewer (generisch, HGB-Codes veredelt) bzw. Extraktion der eingebetteten PDFs.

3 Fertig aufbereitet statt selbst parsen: bilanz

curl "https://skale.dev/firmenindex/api?e=bilanz&fn=475207i"

Ausgezählte Bilanz-Zahlen als Zeitreihe (JSON) — aus den Strukturdaten-XMLs extrahiert. Ehrlicher Status statt Fake: status/hinweis im Payload (z. B. pdf_aera = Urkunden vorhanden, aber nur als PDF — typisch vor ~2007 oder Kleinstgesellschaften; zeitreihe ist dann leer, nie geraten).

Firmenbuchauszug: auszug/{fn}

curl -O "https://skale.dev/firmenindex/api?e=auszug%2F475207i&fmt=pdf"   # application/pdf
curl "https://skale.dev/firmenindex/api?e=auszug%2F475207i&fmt=md"       # text/markdown

Auszug im Stil der amtlichen Druckdokumente aus HVD-Kurzinformation + evi-Ergänzungen. &stichtag=YYYY-MM-DD für den historischen Stand (Zeitreise). Kein amtliches Dokument — Ausdrucke kennzeichnen sich selbst mit der Datenquelle.

Höflichkeit bei Urkunden

• Urkunden-PDFs sind groß (bis mehrere MB) — gezielt per key ziehen, nicht probehalber batchen.
• Upstream-Rate-Limit ~30 req/min gilt auch hier: erst Liste, dann gezielt die benötigten keys.
• bilanz zuerst probieren — wenn die Zahlen schon ausgezählt sind, spart das den XML-Fetch komplett.