# Reporting API (https://docs.otark.com/de/developer/reporting-api)

<Callout type="warn" title="Freischaltung erforderlich">
  Diese API muss für Ihr Konto explizit freigeschaltet werden. Wenden Sie sich dazu an den [Support](https://docs.otark.com/de/support).
</Callout>

Die Reporting API ist der API-Kanal der drei Reportformate ([Formate & Zugriff](https://docs.otark.com/de/granular-certificates/formats-access)): automatisierter Zugriff ohne Download, für Berichtssysteme, Bilanzierungssoftware und eigene Auswertungen. Sie richtet sich an Teilnehmer in der Käuferrolle. Abrufbar sind der stundenscharfe [Verbrauchsabgleich](https://docs.otark.com/de/granular-certificates/coverage-matching) je Portfolio, das [Green-SPOT-Nachweispaket](https://docs.otark.com/de/green-spot/buyer-proof-package) je Liefermonat, der Jahresnachweis und der [Restsaldo](https://docs.otark.com/de/granular-certificates/fractional-account) zwischen GCR-Konto und HKNR-Konto. Jeder Report geht an den Teilnehmer, nie an den Inhaber eines benannten Bilanzkreises oder Registerkontos.

## Basis-URL

```
https://api.otark.energy/v1
```

Alle Anfragen müssen HTTPS verwenden. Antworten werden im JSON-Format zurückgegeben, auf Wunsch als CSV. Die Reporting API liegt auf `api.otark.energy`, dem Host der von OES betriebenen Abwicklungs-APIs (BRP Connect, GCR Connect), weil OES die Nachweise und Reports erstellt. Der API-Schlüssel stammt dagegen aus dem Otark-Konto.

## Authentifizierung

Alle Anfragen müssen den `X-Api-Key`-Header enthalten:

```bash
curl -X GET "https://api.otark.energy/v1/portfolios" \
-H "X-Api-Key: IHR_API_KEY"
```

Wie die Authentifizierung plattformweit funktioniert und wo die Schlüssel der übrigen APIs entstehen, steht unter [Authentifizierung](https://docs.otark.com/de/developer/authentication).

API-Schlüssel werden in den Kontoeinstellungen auf app.otark.com erstellt und tragen den Scope `proofs:read`. Bewahren Sie Ihren Schlüssel sicher auf.

## Konventionen

| Konvention      | Regel                                                                                                                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paginierung     | Listen nehmen `limit` (1–100, Vorgabe 10) und einen Cursor `after` entgegen; die Antwort führt `pagination` mit `has_more` und `next_cursor`; Stundenzeitreihen kommen vollständig je Monat oder Jahr |
| Zeitstempel     | ISO 8601 in UTC (`2026-06-10T09:30:00Z`); Liefertage als `YYYY-MM-DD`, Liefermonate als `YYYY-MM`                                                                                                     |
| Stunden         | gezählt 1–24 wie an der EPEX — Stunde 14 ist 13:00–14:00 Europe/Berlin ([Granularität](https://docs.otark.com/de/granular-certificates/hourly-granularity))                                                                 |
| Formate         | `format=json` (Standard) oder `format=csv`; die Nachweise zusätzlich als PDF über den Header `Accept: application/pdf`                                                                                |
| Fehler          | Problem Details nach RFC 9457 (`application/problem+json`)                                                                                                                                            |
| Ratenbegrenzung | **300 Anfragen je 60-Sekunden-Fenster**, plattformweit gleich; die Antwort führt `X-RateLimit-Limit`, `-Remaining` und `-Reset` mit, bei Überschreitung `429 Too Many Requests`                       |

## Ressourcen

| Ressource                | Zweck                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Portfolios               | Die Einheiten, in denen der Käufer seinen Bezug abbildet — je Portfolio mit hinterlegter Zielkurve                                                                                                                                                                                                                                                                                                                                                                                       |
| Verbrauchsabgleich       | HC und Ansprüche auf HC des Käufers gegen die Zielkurve, je Stunde: gedeckt, Unterdeckung, Überdeckung ([Verbrauchsabgleich](https://docs.otark.com/de/granular-certificates/coverage-matching))                                                                                                                                                                                                                                                                                                               |
| Green-SPOT-Nachweispaket | Die HC-Zeitreihe eines Liefermonats mit Ausweisung, Deckungsquelle und Zuteilung je Stunde und Anlage, ab D+1 mit vorläufigen Stundenwerten, final mit dem Monatsabschluss am 10. des übernächsten Monats ([Nachweispaket](https://docs.otark.com/de/green-spot/buyer-proof-package))                                                                                                                                                                                                                          |
| Jahresnachweis           | Die Jahreszeitreihe mit 8.760 Stundenwerten, im Schaltjahr 8.784, einmal jährlich zum 31. März des Folgejahres erstellt ([Formate & Zugriff](https://docs.otark.com/de/granular-certificates/formats-access))                                                                                                                                                                                                                                                            |
| Restsaldo                | Die Differenz zwischen dem GCR-Konto bei OES (drei Nachkommastellen) und dem HKNR-Konto (ganze HKN): der Rest, der im Kalenderjahr in den Folgemonat rollt (unter 1 MWh, solange in den Monatsabschlüssen keine ganzen HKN gefehlt haben). Im Dezember-Clearing erhält der Käufer dafür den Jahresreferenzpreis in bar, oder OES liefert stattdessen einen HKN desselben Erzeugungsmonats aus einer anderen Anlage ([Rundung & Restsaldo](https://docs.otark.com/de/granular-certificates/fractional-account)) |

## Nur die Stunde

Nach außen existiert ausschließlich die Stunde. Die API liefert keine Viertelstundenwerte: Das GCR führt darunter viertelstündlich, weist die Viertelstunde aber nicht aus ([Granularität](https://docs.otark.com/de/granular-certificates/hourly-granularity)). Wo eine Stunde nicht oder nur teilweise belegt ist, trägt die Menge ihre [Ausweisung](https://docs.otark.com/de/granular-certificates/honest-disclosure): *gedeckt*, *Anspruch, Zuteilung ausstehend*, *nicht grün gedeckt* (samt Ursache) oder *ungedeckt*. Eine Überdeckung überträgt der Report nie auf eine andere Stunde ([Verbrauchsabgleich](https://docs.otark.com/de/granular-certificates/coverage-matching)).

## Support

Bei Fragen oder für weitere Unterstützung erreichen Sie uns über den [Support](https://docs.otark.com/de/support).
