API und MCP-Server

1. Zugang

Schlüssel erzeugen

Den persönlichen API-Schlüssel erzeugen Sie im Dashboard unter Einstellungen → API-Zugang. Er beginnt mit epr_live_ und ist genau einem Konto zugeordnet. Ein neu erzeugter Schlüssel ersetzt den bisherigen sofort — laufende Integrationen müssen dann umgestellt werden.

Der Schlüssel ist ein Geheimnis wie ein Passwort. Er gehört in die Konfiguration Ihres Systems, nicht in den Quelltext einer Anwendung, die im Browser läuft, und nicht in eine URL.

Basis-URL

https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/

Zwei gleichwertige Wege, den Schlüssel zu senden

Empfohlen ist der Header X-Api-Key. Er funktioniert in jeder Konfiguration:

X-Api-Key: epr_live_...

Alternativ nimmt jeder Endpunkt den Schlüssel auch im Authorization-Header entgegen:

Authorization: Bearer epr_live_...

Beide Wege führen zur selben Prüfung. Wenn Ihre Umgebung den Authorization-Header bereits anderweitig belegt, nehmen Sie X-Api-Key.

Erster Aufruf zur Probe

Dieser Aufruf schreibt nichts und ist der schnellste Weg zu prüfen, ob Schlüssel und Verbindung stimmen:

curl https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/materials-summary \
  -H "X-Api-Key: epr_live_..."

{
  "year": 2026,
  "used_kg": 607184.6,
  "rate_limit_per_minute": 120,
  "used_this_minute": 1
}

---

2. Grenzen und Fehler

Ratengrenze

Die Grenze gilt je Konto über alle Endpunkte zusammen, nicht je Endpunkt, und bezieht sich auf die letzten 60 Sekunden. MCP-Aufrufe zählen mit. Sie richtet sich nach dem gebuchten Tarif:

Jede erfolgreiche Antwort nennt Ihren Stand mit: rate_limit_per_minute und used_this_minute. Damit können Sie Ihre Aufruffolge selbst steuern, ohne auf einen Fehler zu warten. Wird die Grenze erreicht, antwortet der Endpunkt mit 429; ein Wiederholungsversuch nach einer Minute ist dann erfolgreich.

Fehlerformat

Jeder Fehler kommt als JSON-Objekt mit dem Feld error und einem stabilen Fehlerschlüssel. Dieser Schlüssel ist maschinenlesbar und ändert sich nicht — werten Sie ihn aus, nicht den HTTP-Status allein.

{ "error": "api-schluessel-ungueltig", "rate_limit_per_minute": null }

---

3. REST-Endpunkte

POST /submit-materials — Mengenmeldung

Überträgt in Verkehr gebrachte Verpackungsmengen. Der Endpunkt schreibt in eine eigene Quelle api; manuelle Eingaben im Dashboard und Mengen aus dem Packtisch bleiben davon unberührt. Die ausgewiesene Periodenmenge ist die Summe aller Quellen.

Mengenfelder, alle in Kilogramm, alle optional — mitschicken, was angefallen ist:

Rabattfähige Kunststoffmenge

Die drei Wahrheitswerte oben gelten pauschal für die ganze Periode. Wenn in Ihrem Sortiment nur ein Teil der Kunststoffverpackungen ein Rabattkriterium erfüllt, geben Sie stattdessen die rabattfähige Menge je Materialklasse und Kriterium an — dann wird auch nur diese Teilmenge verbilligt:

"discountable_plastic": {
  "plastic_flexible": { "pcr": 1.2, "mono": 3.0 },
  "plastic_rigid": {}
}

Ein leeres Objekt ("plastic_rigid": {}) ist eine Aussage: gerechnet, nichts rabattfähig. Ein fehlender Schlüssel bedeutet das Gegenteil — die volle Menge gilt als rabattfähig. Wer dieses Feld benutzt, muss es deshalb für jede gemeldete Kunststoffklasse mitschicken.

Beispiel

curl -X POST https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/submit-materials \
  -H "X-Api-Key: epr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "paper_cardboard": 12.5,
    "plastic_flexible": 3.2,
    "sup_pieces": 40,
    "discountable_plastic": { "plastic_flexible": { "pcr": 3.2 } }
  }'

{
  "ok": true,
  "period": "2026 H2",
  "amounts": { "paper": 12.5, "flexpl": 3.2 },
  "plastic_recycling": { "pcr": false, "mono": false, "color": false },
  "total_kg": 15.7,
  "sup_pieces": 40,
  "orders_synced_count": 1,
  "rate_limit_per_minute": 120,
  "used_this_minute": 3
}

Die Antwort zeigt den Stand nach dem Aufruf und über alle Quellen hinweg, nicht nur Ihre eigene Zeile. Die Gebühr wird ausschließlich in der Datenbank gerechnet; sie lässt sich nicht über die Schnittstelle setzen.

GET /materials-summary — Jahresmenge abfragen

Liefert die kumulierte Jahresmenge des Kontos über alle Meldewege hinweg. Rein lesend, schreibt nichts.

curl https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/materials-summary \
  -H "X-Api-Key: epr_live_..."

{ "year": 2026, "used_kg": 607184.6, "rate_limit_per_minute": 120, "used_this_minute": 1 }

POST /submit-product-passport — Produktdaten und Produktpass

Überträgt Produktstammdaten und die Vorbereitungsfelder für den digitalen Produktpass. Schlüssel ist die sku: existiert sie im Konto, werden nur die mitgeschickten Felder aktualisiert; existiert sie nicht, wird das Produkt angelegt — dafür ist name dann Pflicht.

Der digitale Produktpass ist eine kommende Pflicht aus der ESPR. Diese Felder dienen der Vorbereitung darauf; sie stellen keine Konformitätserklärung dar.

curl -X POST https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/submit-product-passport \
  -H "X-Api-Key: epr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ART-1234",
    "name": "Präzisionsdrehteil M8",
    "carbon_footprint_value": 2.4,
    "carbon_footprint_methodology": "GHG Protocol, eigene Berechnung"
  }'

{ "ok": true, "id": "…", "sku": "ART-1234", "created": false,
  "updated_fields": ["name", "carbon_footprint_value", "carbon_footprint_methodology"] }

---

4. MCP-Server

Das Model Context Protocol (MCP) ist der offene Standard, über den KI-Assistenten auf Fachsysteme zugreifen. PPWR-Ready betreibt dafür einen eigenen Server: Sie verbinden ihn einmal mit Ihrem Assistenten, und danach lassen sich Ihre Verpackungs- und Meldedaten in natürlicher Sprache befragen — „Welche Verpackungen haben keine Konformitätserklärung?“, „Wie viel Kunststoff haben wir 2026 gemeldet?“.

Eckdaten

Einrichtung in Claude Desktop oder Claude Code

{
  "mcpServers": {
    "ppwr-ready": {
      "type": "http",
      "url": "https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/mcp",
      "headers": { "X-Api-Key": "epr_live_..." }
    }
  }
}

Die sechs Werkzeuge

Ein leerer Wert in einem Ergebnis bedeutet nicht erfasst — nicht null und nicht „nein“. Der Server macht diesen Unterschied ausdrücklich, damit ein Assistent eine Datenlücke nicht als Sachaussage ausgibt.

Aufruf ohne Assistent

Der Server ist gewöhnliches JSON-RPC und lässt sich direkt ansprechen:

curl -X POST https://cuugzslijbqurmeuvshh.supabase.co/functions/v1/mcp \
  -H "X-Api-Key: epr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

5. Massenimport und Export

Nicht jede Anbindung braucht eine Programmierung. Für den einmaligen oder regelmäßigen Datenaustausch gibt es im Dashboard drei Wege ohne eine Zeile Code.

Import

Produkte, Verpackungen und Lieferanten lassen sich als CSV einlesen. Der Import erkennt Semikolon wie Komma als Trennzeichen und kommt mit den Zeichensätzen zurecht, die Excel erzeugt. Vor dem Schreiben sehen Sie eine Vorschau mit Spaltenzuordnung; jeder Durchlauf wird protokolliert und lässt sich als Ganzes wieder zurücknehmen, wenn eine Datei falsch war.

Export und Berichte

In der Berichtszentrale stellen Sie sich Berichte selbst zusammen: Datenquelle wählen, Felder wählen, filtern, gruppieren — und als XLSX oder als prüfsicheres PDF ausgeben. Eine einmal gebaute Zusammenstellung lässt sich als Vorlage sichern und jederzeit erneut ausgeben, etwa halbjährlich für dieselbe Behördenabfrage.

Dieselben Datenquellen und Felder, die dort zur Auswahl stehen, erreichen Sie über query_data am MCP-Server. Es ist derselbe Katalog — was im Bericht erscheinen darf, darf auch abgefragt werden, und umgekehrt.

Vollständiger Datenexport

Unabhängig davon können Sie unter Einstellungen → Datenschutz einen vollständigen Export aller Daten Ihres Kontos anfordern. Er wird serverseitig erzeugt und als Archiv bereitgestellt.

---

6. Sicherheit

Mandantentrennung

Jede Abfrage über API und MCP läuft in der Datenbank mit den Rechten Ihres Kontos, abgesichert über Row Level Security. Die Trennung entsteht nicht durch einen Filter, den die Schnittstelle setzt, sondern durch dieselbe Regel, die auch im Dashboard gilt. Eine Abfrage, die ausdrücklich nach fremden Daten fragt, liefert kein Ergebnis — nicht weil sie abgefangen würde, sondern weil die Zeilen für dieses Konto nicht existieren.

Zugriffsprotokoll

Jeder Zugriff wird mit Zeitpunkt, Endpunkt, Ergebnis, IP-Adresse und Kennung des aufrufenden Programms protokolliert — auch abgewiesene. Ungültige Schlüssel und gesperrte Konten erzeugen zusätzlich einen Eintrag im Sicherheitsprotokoll. Diese Einträge sind die Grundlage der Ratengrenze und zugleich der Nachweis, wer wann was abgerufen hat.

Schlüssel verloren

Erzeugen Sie im Dashboard einen neuen Schlüssel. Der alte verliert damit sofort seine Gültigkeit; Aufrufe damit werden ab diesem Moment mit 401 abgewiesen und im Sicherheitsprotokoll vermerkt.