Grundlagen

Basis-URL

Alle Endpunkte liegen unter https://api.sarora.de. Es gibt keine getrennte Sandbox — Testzugänge sind normale Schlüssel mit engerem Kontingent.

export API="https://api.sarora.de"
export KEY="ihr-schluessel"

Authentifizierung

Jeder Aufruf trägt den Schlüssel im Kopf X-API-Key. Ohne gültigen Schlüssel antwortet die API mit 401.

curl "$API/tickers/resolve/DE0007164600" \\
  -H "X-API-Key: $KEY"

Vier Bereiche brauchen keinen Schlüssel: /health, /status, die Swagger-Oberfläche unter /docs und POST /feedback. Alles andere ist geschlossen.

Identifier

Wo ein Endpunkt {identifier} erwartet, nimmt er jede der gängigen Kennungen entgegen — ohne dass Sie die Art mitgeben müssen: ISIN, WKN, Ticker, CIK und LEI. Erkannt wird nach Form.

• ISINDE0007164600 — zwei Buchstaben, zwölf Zeichen insgesamt
• WKN716460 — sechs Stellen
• TickerSAP, AAPL
• CIK1000184 oder cik:1000184
• LEI529900D6BF99LW9R2E68 — 20 Zeichen

Ist eine Form mehrdeutig, können Sie sie mit einem Präfix erzwingen: isin:, wkn:, ticker:, cik:, lei:.

Fehler

Fehler kommen als JSON mit einem detail-Feld. Bei 404 auf den Fundamentaldaten steht dort mehr als ein Text: welche Entität gemeint war und welche Quellen es für sie überhaupt gibt.

curl "$API/v1/fundamentals/XYZ/statements" -H "X-API-Key: $KEY"

{
  "detail": "Keine Rechenwerke für XYZ",
  "entity": { "name": null, "resolved": false },
  "suggestedSources": [],
  "suggestedImporter": "tickers/resolve"
}

• 401Kein oder ungültiger Schlüssel
• 404Identifier nicht auflösbar oder keine Daten vorhanden
• 409Ein Lauf dieser Lane läuft bereits
• 422Parameter unplausibel — oder, bei Sync-Endpunkten: nichts fällig
• 429Kontingent erschöpft

422 auf einem sync-Endpunkt ist kein Fehler: es heißt, dass nichts zu tun war. Automatisierte Aufrufer sollten das als Erfolg werten — genau darauf beruht unsere eigene Schleife.

Warnungen statt stiller Annahmen

Antworten mit Fundamentaldaten können ein warnings-Feld tragen. Die Codes sind stabil und maschinell auswertbar.

• esef.date_shift_appliedEuropäisches Periodenende um einen Tag korrigiert
• de.period_end_assumedKein Datum im Bericht, Geschäftsjahresende angenommen
• metric.shadowedMehrere Zeilen zeigten auf dieselbe Kennzahl, eine hat gewonnen
• currency.mixedDie Antwort enthält mehr als eine Währung
• cross_source.disputedEine zweite Quelle nennt einen abweichenden Wert

Wenn eine Kennzahl fehlt

Ein fehlender Wert ist bei uns eine Aussage, kein Ausfall. Die Regel lautet: ein fehlender Wert ist besser als ein falscher. Was nicht sicher zuzuordnen ist, bleibt null — es sieht dann aus wie eine Lücke und nicht wie eine Zahl, auf die man sich verlassen könnte.

Der häufigste Fall, der wie ein Fehler aussieht und keiner ist: revenue ist bei Banken, Versicherern und Fonds leer. Ein Kreditinstitut weist keinen Umsatz aus, sondern Zinsertrag und zinsunabhängigen Ertrag; ein Fonds weist ein Anlageergebnis aus. Die Zahlen sind da — sie heißen nur anders:

• Bankennet_interest_income, interest_income, noninterest_income
• Versichererpremiums_earned, investment_income
• Fonds, BDC, SPACinvestment_income — eine Umsatzzeile gibt es im Abschluss nicht

Von 6.480 US-Emittenten mit Fundamentaldaten tragen 915 keinen revenue. Davon sind rund 258 Banken und Versicherer und etwa 400 Fonds, BDC oder SPAC. Wir rechnen für sie keinen Umsatz aus anderen Zeilen zusammen: das wäre eine Zahl, die in keinem Abschluss steht.

Dasselbe gilt für gross_profit (knapp die Hälfte aller Emittenten weist keinen aus — Banken und viele Dienstleister kennen die Größe nicht) und für operating_income im Finanzsektor.

Was tatsächlich vorliegt, sagt Ihnen GET /v1/fundamentals/{identifier}/coverage vor der Abfrage — Töpfe, Zeitraum und Kennzahlendeckung.

Versionierung

Endpunkte unter /v1 haben eine Zusage: das Kennzahlen-Vokabular und die Antwortform ändern sich nur mit einer neuen Version. Die übrigen Endpunkte sind gewachsen und bleiben so, wie sie sind — wir nehmen nichts weg, aber sie tragen keine solche Zusage.

Erster Aufruf

Drei Schritte: Identifier auflösen, Abdeckung prüfen, Zahlen holen.

curl "$API/tickers/resolve/DE0007164600" -H "X-API-Key: $KEY"
curl "$API/v1/fundamentals/SAP/coverage"        -H "X-API-Key: $KEY"
curl "$API/v1/fundamentals/SAP/metrics?metrics=revenue&years=5" \\
  -H "X-API-Key: $KEY"

Der mittlere Schritt lohnt sich: er sagt Ihnen, welche Datentöpfe es für diesen Emittenten gibt und bis wann sie reichen — bevor Sie eine Abfrage bauen, die dann leer zurückkommt.