BRP Connect API

Konventionen

Paginierung, Fehlerbehandlung, Zeitstempel, Lieferzeiträume und Ratenbegrenzung

Als Markdown anzeigen

Paginierung

Alle Listen-Endpunkte unterstützen Cursor-basierte Paginierung mit zwei Parametern:

ParameterTypBeschreibung
limitintegerMax. Einträge pro Seite (Standard: 10, Max: 100)
afterstringCursor für die nächste Seite — den next_cursor-Wert der vorherigen Antwort übergeben

Paginierte Antworten enthalten ein pagination-Objekt mit einem next_cursor-Feld:

{
  "contracts": [ ... ],
  "pagination": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "con_a1b2c3d4"
  }
}

Wenn has_more den Wert true hat, übergeben Sie den next_cursor-Wert als after-Parameter, um die nächste Seite abzurufen. Wenn keine weiteren Seiten vorhanden sind, ist next_cursor null.

Beispielablauf:

  1. GET /v1/transactions?limit=10 — gibt Einträge 1–10 zurück, "next_cursor": "txn_abc123"
  2. GET /v1/transactions?limit=10&after=txn_abc123 — gibt Einträge 11–20 zurück, "next_cursor": "txn_xyz789"
  3. GET /v1/transactions?limit=10&after=txn_xyz789 — gibt Einträge 21–25 zurück, "has_more": false, "next_cursor": null

Der Sammlungsschlüssel in der Antwort entspricht dem Ressourcennamen (z.B. "contracts", "transactions", "nominations", "customers").

Zeitstempel

Alle Zeitstempel sind ISO 8601 in UTC:

2026-07-15T11:00:00Z

Lieferzeiträume

Die Energielieferung verwendet die standardmäßige PTU (Programme Time Unit)-Konvention mit 15-Minuten-Intervallen. delivery_date bezeichnet den Liefertag in der Zeitzone Europe/Berlin; die Zeitscheiben 1–96 zählen ab 00:00 Uhr dieses lokalen Tages. Die Zeitstempel period_from und period_to stehen wie alle Zeitstempel der API in UTC:

{
  "delivery_date": "2026-07-15",
  "period_from": "2026-07-15T11:00:00Z",
  "period_to": "2026-07-15T11:15:00Z"
}

Jeder Liefertag hat 96 Zeitscheiben von je 15 Minuten (nummeriert 1–96). Am Tag der Umstellung auf Sommerzeit sind es 92 — die Nummern 9–12 entfallen —, am Tag der Umstellung auf Winterzeit 100: Der erste Durchlauf der wiederholten Stunde behält die Nummern 9–12, der zweite trägt die Nummern 97–100 (sie entsprechen 9b bis 12b in den Nominierungsdateien). Nach Zeitscheiben filtern die Transaktions- und Nominierungs-Endpunkte über die Parameter slot_number_from und slot_number_to.

Fehlerantworten

Alle Fehler folgen RFC 9457 — Problem Details for HTTP APIs und werden mit Content-Type: application/problem+json zurückgegeben:

{
  "type": "https://brp.otark.energy/errors/balance_group_tso_not_enabled",
  "title": "Balance Group TSO Not Enabled",
  "status": 400,
  "detail": "The requested TSO is not enabled for this balance group.",
  "instance": "/v1/customers/cust_r8s9t0u1"
}

Validierungsfehler enthalten ein errors-Array mit feldspezifischen Details:

{
  "type": "https://brp.otark.energy/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "instance": "/v1/customers/cust_r8s9t0u1",
  "errors": [
    {
      "field": "balance_group.tso",
      "code": "invalid_enum_value",
      "message": "Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ'"
    }
  ]
}

Feldspezifische Fehlercodes: unknown_field, read_only_field, required, invalid_type, invalid_enum_value, invalid_format, invalid_literal, value_too_small, value_too_large, validation_failed.

Die API verwendet die Standard-HTTP-Statuscodes:

CodeBeschreibung
400Ungültige Anfrage — Validierungsfehler oder Verstoß gegen Geschäftsregeln
401Nicht autorisiert — fehlender oder ungültiger API-Schlüssel
403Zugriff verweigert — API-Schlüssel hat nicht die erforderlichen Berechtigungen
404Nicht gefunden — Ressource existiert nicht oder kein Zugriff
409Konflikt — Operation kann im aktuellen Zustand nicht ausgeführt werden
429Zu viele Anfragen — Ratenlimit überschritten
500Interner Serverfehler

Ratenbegrenzung

Für alle APIs der Plattform gilt dieselbe Grenze: 300 Anfragen je 60-Sekunden-Fenster. Jede Antwort enthält folgende Header:

HeaderBeispielBeschreibung
x-ratelimit-limit300Maximale Anfragen pro Fenster
x-ratelimit-remaining299Verbleibende Anfragen im aktuellen Fenster
x-ratelimit-reset60Sekunden, bis das Fenster zurückgesetzt wird

Bei Überschreitung des Limits gibt die API 429 Too Many Requests zurück.

Zuletzt aktualisiert am