POST /v1/cancellation-requests
Den Antrag stellen, die ausgewählten GC zu entwerten — den Antrag, nicht den Vollzug. Die Reihenfolge steht fest und wird durch die API nicht verändert: zuerst der HKN im HKNR, dann das GC im GCR; OES entwertet kein GC, bevor die Entwertung der zugehörigen HKN festgestellt ist. Wie es weitergeht, hängt davon ab, ob OES Zugriff auf das benannte HKNR-Konto hat, über die Dienstleisterrolle oder einen eigenen Benutzer mit Lesezugriff. Mit Zugriff bleibt evidence weg: OES stellt die HKN-Entwertung im Registerabgleich selbst fest, automatisch und ohne Entgelt. Ohne Zugriff ist evidence Pflicht, die Entwertungsbestätigung des HKNR (Kontoauszug oder Entwertungsbeleg) mit Anlage, Liefermonat und Menge; OES prüft sie manuell, und es kann ein Entgelt nach dem Preis- und Leistungsverzeichnis anfallen. Einen Beleg, der sich nicht zuordnen lässt, lehnt OES mit Begründung ab; die GC bleiben ausgestellt. Eine Pflicht zur Entwertung besteht nicht, und deshalb auch keine Frist. Den Fortgang verfolgen Sie über GET /v1/cancellation-requests/{request_id}; der Entwertungsnachweis steht erst nach dem Abschluss bereit. Erforderlicher Scope: cancellations:write
Freischaltung erforderlich
In: header
Der Teilnehmer, dessen GC entwertet werden sollen
Kennungen der zu entwertenden GC
1 <= itemsDer Entwertungsbeleg des HKNR. Bleibt weg, wenn OES Zugriff auf das benannte HKNR-Konto hat (Dienstleisterrolle oder eigener Benutzer mit Lesezugriff); OES stellt die HKN-Entwertung dann im Registerabgleich selbst fest. Andernfalls Pflicht.
Response Body
curl -X POST "https://api.otark.energy/v1/cancellation-requests" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "cust_b7e4a2c9", "certificate_ids": [ "gc_5d8f3a1c", "gc_8a2c7e4b" ] }'{
"id": "creq_2e9b4f7a",
"customer_id": "cust_b7e4a2c9",
"certificate_ids": [
"gc_5d8f3a1c",
"gc_8a2c7e4b"
],
"status": "submitted",
"evidence_route": "service_provider_role",
"rejected_reason": null,
"requested_at": "2026-06-02T09:15:00Z",
"completed_at": null
}{
"type": "https://gcr.otark.energy/errors/validation",
"title": "Validierung fehlgeschlagen",
"status": 400,
"instance": "/v1/cancellation-requests",
"errors": [
{
"field": "evidence",
"code": "required",
"message": "Evidence is required because OES has no access to the named register account"
}
]
}{
"type": "https://gcr.otark.energy/errors/invalid_api_key",
"title": "Ungültiger API-Schlüssel",
"status": 401
}{
"type": "https://gcr.otark.energy/errors/insufficient_scopes",
"title": "Unzureichende Scopes des API-Schlüssels",
"status": 403,
"detail": "Missing scope: cancellations:write. Please create a new API key with the required scopes."
}{
"type": "https://gcr.otark.energy/errors/certificate_not_found",
"title": "GC nicht gefunden",
"status": 404,
"instance": "/v1/certificates/gc_5d8f3a1c"
}{
"type": "https://gcr.otark.energy/errors/certificate_already_cancelled",
"title": "GC bereits entwertet",
"status": 409,
"detail": "Cancellation is final — a cancelled certificate cannot be cancelled again."
}{
"type": "https://gcr.otark.energy/errors/rate_limited",
"title": "Ratenbegrenzung erreicht",
"status": 429
}/certificates/{certificate_id} GET
Ein einzelnes HC samt der Registerangaben abrufen, die das GCR dazu führt: Tupel, Anlage, Menge, Merkmale, Status, Ort des HKN, Deckungsquelle, HKN-Übertragung und Entwertung. Die Detailansicht nennt nie die Identitäten früherer Inhaber — der Handel ist anonym, und das Register hebt das nicht auf; die vollständige Kette kennt allein OES. Preise und Transaktionen enthält sie ebenfalls nicht. Erforderlicher Scope: certificates:read
/cancellation-requests/{request_id} GET
Einen Entwertungsantrag abrufen, um seinen Status zu verfolgen. Mit Zugriff von OES auf das HKNR-Konto geht der Antrag von submitted auf completed über, sobald OES die HKN-Entwertung im Registerabgleich feststellt. Mit hochgeladenem Beleg durchläuft er under_review und endet auf completed oder rejected — abgelehnt, wenn der Beleg Anlage, Liefermonat und Menge nicht ausweist. Nach dem Abschluss tragen die GC im GCR den Status cancelled, einen der beiden Endzustände. Erst mit beiden Entwertungen ist der Nachweis vollständig, und erst dann steht der Entwertungsnachweis bereit. Erforderlicher Scope: cancellations:write