# GCR Connect API (https://docs.otark.com/de/developer/gcr-connect-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 GCR Connect API ist das programmatische Gegenstück zum [GCR Portal](https://docs.otark.com/de/settlement/gcr-portal), dem Portal des GCR (Granular Certificate Register, Register für granulare Zertifikate), das die Zertifikatstelle von OES unter [gcr.otark.energy](https://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:

```bash
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](https://docs.otark.com/de/developer/authentication).

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

## 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`                                    |
| **Zeitstempel**     | ISO 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                                    |
| **Mengen**          | MWh mit bis zu drei Nachkommastellen (kWh-Genauigkeit, der kleinste Nennwert eines GC ist 1 kWh)                                                                                |
| **Fehler**          | `application/problem+json` nach RFC 9457, mit feldgenauen Validierungsfehlern                                                                                                   |
| **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` |

## 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](https://docs.otark.com/de/settlement/gcr-portal/accounts)). 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

| Ressource      | Zweck                                                                                                                                                         | Scope                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Kunden**     | die Teilnehmer, deren GC das GCR-Konto führt, als Einstieg jeder Integration                                                                                  | `certificates:read`   |
| **Bestand**    | die HC je Liefertag und Stunde, mit einer Detailansicht je HC mit den Registerangaben ([Was das Register führt](https://docs.otark.com/de/granular-certificates/register-contents)) | `certificates:read`   |
| **Entwertung** | der Antrag, GC zu entwerten: erst der HKN im HKNR, dann das GC im GCR ([Entwertung](https://docs.otark.com/de/granular-certificates/cancellation))                                  | `cancellations:write` |
| **Reports**    | Stundenzeitreihe, HKN-Monatsmenge mit Stand der Übertragung und Entwertungsnachweis ([Auszüge & Reports](https://docs.otark.com/de/settlement/gcr-portal/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](https://docs.otark.com/de/settlement/gcr-portal/actions)). 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](https://docs.otark.com/de/granular-certificates/register-access)):

* **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](https://docs.otark.com/de/support).
