GCR Connect API

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

Als Markdown anzeigen

Freischaltung erforderlich

Diese API muss für Ihr Konto explizit freigeschaltet werden. Wenden Sie sich dazu an den Support.
POST
/v1/cancellation-requests
X-Api-Key<token>

In: header

customer_idstring

Der Teilnehmer, dessen GC entwertet werden sollen

certificate_idsarray<string>

Kennungen der zu entwertenden GC

Items1 <= items
evidence?EvidenceDocument

Der 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
}