GCR Connect API

GCR Connect API

API für den programmatischen Zugriff auf das GCR Portal: Teilnehmer, Bestand, Entwertung und die drei Reports des Nachweises

Als Markdown anzeigen

Freischaltung erforderlich

Diese API muss für Ihr Konto explizit freigeschaltet werden. Wenden Sie sich dazu an den Support.

Die GCR Connect API ist das programmatische Gegenstück zum GCR Portal, dem Portal des GCR (Granular Certificate Register, Register für granulare Zertifikate), das die Zertifikatstelle von OES unter gcr.otark.energy betreibt. Sie richtet sich an alle, die zugeteilte GC verwalten: den Käufer mit seinem eigenen GCR-Konto oder den Dienstleister, etwa den Stromlieferanten, mit dessen GCR-Konto der Käufer sein Konto verknüpft hat. Was das Portal zeigt und kann, kann auch die API: den Bestand einsehen, die Entwertung beantragen und die drei Reports des Nachweises abrufen. Wie das Portal ist die API der Zugang zu einem Bestandsregister, kein Handelsplatz. Gehandelt wird auf der Otark-Plattform.

Basis-URL

https://api.otark.energy/v1

Alle Anfragen müssen HTTPS verwenden. Antworten werden im JSON-Format zurückgegeben.

Authentifizierung

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

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

Wie die Authentifizierung plattformweit funktioniert und wo die Schlüssel der übrigen APIs entstehen, steht unter Authentifizierung.

API-Schlüssel entstehen in der Nutzerverwaltung des GCR Portals unter gcr.otark.energy, nicht im Otark-Konto: Das Portal hat eine eigene Nutzerverwaltung, getrennt vom Zugang zur Otark-Plattform (Konten & Zugang). Jeder Schlüssel trägt Scopes (certificates:read, cancellations:write, reports:read); jede Operation nennt die benötigten.

Konventionen

KonventionRegel
PaginierungListen nehmen limit (1–100, Vorgabe 10) und einen Cursor after entgegen; die Antwort führt pagination mit has_more und next_cursor
ZeitstempelISO 8601 in UTC (2026-03-18T12:00:00Z); Liefertage als YYYY-MM-DD, Stunden 1–24 wie an der EPEX — Stunde 14 ist 13:00–14:00 lokaler Zeit
MengenMWh mit bis zu drei Nachkommastellen (kWh-Genauigkeit, der kleinste Nennwert eines GC ist 1 kWh)
Fehlerapplication/problem+json nach RFC 9457, mit feldgenauen Validierungsfehlern
Ratenbegrenzung300 Anfragen je 60-Sekunden-Fenster, plattformweit gleich; die Antwort führt X-RateLimit-Limit, -Remaining und -Reset mit, bei Überschreitung 429 Too Many Requests

Ein Konto, mehrere Kunden

Jeder Teilnehmer erhält mit der Zulassung automatisch ein GCR-Konto. Er kann es mit dem GCR-Konto eines Dienstleisters verknüpfen; die Verknüpfung braucht die Zustimmung des Dienstleisters und wirkt ab dem nächsten Monatsabschluss. Ein Dienstleister-GCR-Konto kann mit den Konten mehrerer Teilnehmer verknüpft sein, und die Sicht ist getrennt je Kunde: Eine Sicht, die die Bestände zweier Kunden zusammenfasst, gibt es nicht (Konten & Zugang). Jede Integration beginnt deshalb mit GET /v1/customers; alle weiteren Aufrufe tragen den Kundenbezug. Inhaber der GC bleibt der Teilnehmer, auch auf dem GCR-Konto eines Dienstleisters. Die Reports tragen deshalb immer den Teilnehmer, nie den Kontoinhaber.

Ressourcen

RessourceZweckScope
Kundendie Teilnehmer, deren GC das GCR-Konto führt, als Einstieg jeder Integrationcertificates:read
Bestanddie HC je Liefertag und Stunde, mit einer Detailansicht je HC mit den Registerangaben (Was das Register führt)certificates:read
Entwertungder Antrag, GC zu entwerten: erst der HKN im HKNR, dann das GC im GCR (Entwertung)cancellations:write
ReportsStundenzeitreihe, HKN-Monatsmenge mit Stand der Übertragung und Entwertungsnachweis (Auszüge & Reports)reports:read

Die Entwertung ist ein Antrag, keine unmittelbare Registerbuchung: Die Zertifikatstelle entwertet das GC erst, wenn die Entwertung des HKN im HKNR festgestellt ist (Entwerten). Was zugeteilt ist, wird nicht mehr gehandelt und nicht zurückübertragen.

Was die API nicht liefert

Wie die Detailansicht im Portal lässt die API bewusst dreierlei weg (Einsicht & Auszüge):

  • Keine Identitäten früherer Inhaber. Der Handel ist anonym, im Orderbuch wie auf dem Aftermarket, und daran ändert das Register nichts. Die vollständige Kette kennt allein OES.
  • Keine Preise und keine Geschäfte. Zertifikatpreis, Sanktionen und Abrechnung gehören zum Markt, nicht zum Register.
  • Keine Bestandsbestätigung zu einem frei gewählten Tag. Über die drei Reports des Nachweises hinaus liefert das Register nichts.

Support

Bei Fragen oder für weitere Unterstützung erreichen Sie uns über den Support.

Zuletzt aktualisiert am