# API und KI-Agenten

Quelle: <https://mvg-frankfurt.de/entwickler>

> Offene REST-API für Blechzuschnitte, Kantteile und Halbzeuge: Katalog, Sofortpreis, Versandquote und Bestellung. Mit OpenAPI-Spec und llms.txt für KI-Agenten.

Diese Website ist nur eine von zwei Oberflächen unseres Systems. Die zweite ist die Schnittstelle darunter. Katalog, Preisberechnung, Versandquote und Bestellung laufen über dieselben REST-Endpunkte, die auch der Konfigurator im Browser benutzt. Sie sind offen, brauchen kein Konto, keinen Schlüssel und kein Cookie.

**Auf einen Blick**

- Basis-URL: `https://mvg-frankfurt.de`
- Preis ohne Schnittstelle, nur per Link: Preis per Link
- Für Programme und Agenten: `/v1`: kuratiert, MVG-API-Key oder OAuth (Lesen und Datei-Preisprüfung frei), Spec unter [/v1/openapi.json](https://mvg-frankfurt.de/v1/openapi.json)
- Für den Browser-Bestellpfad: [/openapi.json](https://mvg-frankfurt.de/openapi.json) und [/llms.txt](https://mvg-frankfurt.de/llms.txt)
- JSON über HTTPS, Preise netto in EUR zzgl. 19 % USt
- Bestellung als Gast, ohne Konto und ohne Anmeldung

## Für ChatGPT und andere KI-Assistenten: Preis per Link

Für eine einzelne Preisfrage braucht ein Assistent keine Schnittstelle. Ein einfacher GET-Aufruf liefert eine HTML-Seite ohne JavaScript, Anmeldung oder Cookie – mit Endpreis, Lieferzeit und strukturierten Daten (schema.org `Offer`).

```
GET https://mvg-frankfurt.de/preis/blech/<werkstoff>/<dicke_mm>/<laenge>x<breite>?menge=n
GET https://mvg-frankfurt.de/preis/halbzeug/<slug>/<laenge_mm>?menge=n
```

1. Maße immer in Millimetern: 100 × 100 cm ist `1000x1000`.
2. Werkstoff als Kürzel, z. B. `almg3`, `1-4301`, `s235jr`, oder der `code` aus [/api/materials](https://mvg-frankfurt.de/api/materials). Den Halbzeug-`slug` liefert [/halbzeuge-index.json](https://mvg-frankfurt.de/halbzeuge-index.json).
3. Nur den Preis übernehmen, den die Seite liefert. Nicht schätzen, nicht hochrechnen.
4. Der Stückpreis enthält Material, Schnitt und Rüsten; der Endpreis zusätzlich die Auftragspauschale je Bestellung (die Seite weist beides getrennt aus). Versand kommt im Warenkorb dazu, Abholung in Frankfurt ist kostenlos. Verbindlich ist der Preis im Warenkorb.
5. Für Kantteile, Laserteile, Dateien und Angebote den MCP-Server oder `/v1` verwenden.

Beispiele zum Öffnen (Referenzfall „Blech 200 × 200 × 2 mm“):

- [Aluminium AlMg3, 2 mm, 200 × 200 mm, 1 Stück](https://mvg-frankfurt.de/preis/blech/almg3/2/200x200)
- [Stahl S235JR, 2 mm, 200 × 200 mm](https://mvg-frankfurt.de/preis/blech/s235jr/2/200x200)
- [Edelstahl 1.4301, 2 mm, 200 × 200 mm](https://mvg-frankfurt.de/preis/blech/1-4301/2/200x200)
- [Aluminium AlMg3, 2 mm, 1000 × 1000 mm, 10 Stück](https://mvg-frankfurt.de/preis/blech/almg3/2/1000x1000?menge=10)
- [Aluminium-Flachstange 10 × 2 mm, 1000 mm](https://mvg-frankfurt.de/preis/halbzeug/flachstange-10-x-2-4200/1000)
- [Preisbeispiele Blechzuschnitt](https://mvg-frankfurt.de/blechzuschnitt/preisbeispiele): Tabelle mit aktuellen Endpreisen gefragter Zuschnitte

Werkstoff-Kürzel sind tolerant: `1.4301`, `14301`, `v2a` und `edelstahl` führen zu Edelstahl 1.4301, `aluminium` zu AlMg3, `stahl` zu S235JR. Ein unbekanntes Kürzel liefert eine Seite mit allen gültigen Kürzeln. Markdown statt HTML: `Accept: text/markdown` oder Endung `.md`.

Aufbau der Antwort (die Beträge stehen immer aktuell auf der Seite):

```
Aluminium AlMg3 2 mm, 200 × 200 mm, 1 Stück
<Endpreis> € netto · <Endpreis> € brutto inkl. 19 % MwSt.
Stückpreis      <Stückpreis> € netto (Material, Schnitt, Rüsten)
Zusammensetzung Stückpreis × Menge + Auftragspauschale je Bestellung = Endpreis
Lieferzeit      <n> Werktage, abholbereit ab Datum
Link            Im Konfigurator öffnen und in den Warenkorb legen →
```

## Die Agenten-Schnittstelle `/v1`

Die Endpunkte unter `/api/…` sind die des Browsers: viele, fein geschnitten, und sie erwarten, dass der Aufrufer den Warenkorb im Kopf behält. Für Programme, Beschaffungssysteme und KI-Agenten gibt es daneben `/v1`: eine kleine Oberfläche entlang des Prozesses statt entlang der Tabellen. Auf ihr sitzt unser MCP-Server.

|  |  |
|---|---|
| `GET /v1` | Selbstbeschreibung: Einheiten, Berechtigungen, Regeln |
| `GET /v1/materials` | Blech-Werkstoffe: Name, Varianten-Code, Stärken (Anzeige „2,0/3,5“), Formate mit Tafelgewicht, REACH-Hinweis |
| `GET /v1/profiles` | Halbzeuge suchen (`q`, `kategorie`, `werkstoff`, Maße wie `breite_mm`): Art.-Nr., Abmessungen, kg/m, Stangenlänge, REACH-Hinweis. Die `art_nr` geht als `article_nr` ins Angebot |
| `GET /v1/dfm/rules` | Konstruktionsgrenzen (Format, Loch, Steg, Rand, Kanten) |
| `GET /v1/part-templates` | Formen des Teile-Editors mit Parametern (ohne Anmeldung) |
| `POST /v1/parts/configure`, `/v1/parts/configure-plate` | Teil ohne Datei: Vorlage bzw. Lochplatte → Prüfung, Shop-Preis, Vorschau `/v1/parts/drafts/…/preview.svg`, Editor-Link, Entwurf 7 Tage (ohne Anmeldung, Ratenbremse) |
| `POST /v1/uploads` | signierter Upload-Link für eine CAD-Datei |
| `POST /v1/designs` | Datei prüfen, dauerhafte `design_id` und Richtpreis für 1 Stück erhalten |
| `GET /v1/designs/{id}/price` | Richtpreis für eine Menge (`?quantity=`), unverbindlich |
| `POST /v1/quotes` | verbindliches Angebot rechnen (24 Stunden gültig) |
| `POST /v1/orders` | gegen die `quote_id` bestellen; Antwort enthält die `checkout_url` |
| `GET /v1/orders/…` | Status der Bestellung; `POST /v1/orders/…/reorder` bietet die Teile neu an (bestellt nichts) |
| `POST /v1/webhooks` | Adresse für signierte Statusmeldungen hinterlegen |

### Feste Zusagen

- **Der Server nennt den Preis.** Es gibt kein Feld, in das ein Aufrufer einen Betrag schreiben könnte. Bestellt wird gegen eine `quote_id`; beim Anlegen der Bestellung wird noch einmal nachgerechnet.
- **Bezahlt wird im Browser.** Diese API hat kein Bezahlwerkzeug und keine Berechtigung dafür. `POST /v1/orders` liefert eine `checkout_url`, die ein Mensch öffnet.
- **Kein stilles Annehmen von Risiken.** Jedes Angebot trägt `requirements` aus der Fertigbarkeitsprüfung. `block` ist nicht bestellbar; `warn` muss beim Bestellen in `accepted_requirements` genannt werden. Das ist eine Entscheidung des Kunden, nicht des Agenten.
- **Einheiten sind festgelegt:** Längen in Millimeter, Winkel in Grad, Geld in ganzen Cent (netto, USt und brutto getrennt), Zeit als ISO 8601 in UTC.
- **Dauerhafte Kennungen statt Warteschleifen:** eine geprüfte Datei bekommt sofort eine `design_id` und wird nie ein zweites Mal übertragen.

### Zugang und Berechtigungen

Lesende Endpunkte (`GET /v1`, `/v1/materials`, `/v1/profiles`, `/v1/dfm/rules`, [`/v1/guide.txt`](https://mvg-frankfurt.de/v1/guide.txt)) sind frei. Die Preisprüfung einer Datei (`POST /v1/uploads`, `POST /v1/designs`) geht ohne Anmeldung, bis 20 Dateien je Tag und 5 je Minute und IP. Angebote, Bestellungen und alles Weitere brauchen `Authorization: Bearer …`, also ein OAuth-Token oder ein **MVG-API-Key** (`mvg_live_…`, unter [Konto → API-Zugang](https://mvg-frankfurt.de/konto) selbst erstellen; ältere `bw_live_…` gelten weiter). Berechtigungen sind einzeln vergebbar: `catalog:read`, `designs:write`, `quotes:read`, `quotes:write`, `orders:write`, `orders:read`, `webhooks:write`. Eine Berechtigung fürs Bezahlen gibt es bewusst nicht.

**Für Agenten im Namen eines Kunden** gibt es dafür einen eigenen Autorisierungsserver nach OAuth 2.1. Die Anwendung meldet sich selbst an (`POST /oauth/register`, RFC 7591), schickt den Kunden auf `/oauth/authorize` (PKCE mit `S256` ist Pflicht), und dort meldet er sich mit seinem Kundenkonto an, sieht Anwendung und Rechte im Klartext und legt eine Betragsgrenze je Bestellung und je Monat fest. Danach holt die Anwendung unter `POST /oauth/token` ein Zugriffstoken (zehn Minuten) und ein Refresh-Token (dreißig Tage, rotierend). Die Selbstbeschreibung steht nach RFC 8414 unter [`/.well-known/oauth-authorization-server`](https://mvg-frankfurt.de/.well-known/oauth-authorization-server), die Beschreibung der Ressource nach RFC 9728 unter [`/.well-known/oauth-protected-resource`](https://mvg-frankfurt.de/.well-known/oauth-protected-resource), der Einstieg nach RFC 9727 unter [`/.well-known/api-catalog`](https://mvg-frankfurt.de/.well-known/api-catalog).

Trägt ein Token ein Kundenkonto (`GET /v1/me` sagt es), dann genügt zum Bestellen `{"quote_id": "…", "payment_method": "…"}`: Anschrift und USt-IdNr. kommen aus dem Konto, AGB und Widerrufsbelehrung stecken in der Zustimmung. Der Kunde sieht alle verbundenen Anwendungen unter [/oauth/apps](https://mvg-frankfurt.de/oauth/apps) und kann jede sofort widerrufen. Für feste Anbindungen ohne Browser (ERP, Einkaufssystem) vergeben wir auf Anfrage an [info@mvg-frankfurt.de](mailto:info@mvg-frankfurt.de) einen Zugang für `client_credentials`.

### Datei übergeben, ohne sie durchzureichen

Ein gehosteter Agent sieht weder lokale Pfade noch Chat-Anhänge, und Base64 in Werkzeugargumenten sprengt jedes Kontextfenster. Deshalb liefert `POST /v1/uploads` einen signierten Link: `upload_url` für das Programm (ein PUT, 15 Minuten, einmalig, STEP bis 50 MiB, DXF bis 20 MiB) und `browser_upload_url` für den Menschen, wenn das Programm die Datei gar nicht lesen kann. Danach genügt `POST /v1/designs` mit der `upload_id`.

### Doppelte Aufrufe

Schreibende Aufrufe sind idempotent: Der Kopf `Idempotency-Key` (oder das Feld `operation_key` im Rumpf für Clients ohne eigene Kopfzeilen) macht aus einer Wiederholung eine Wiedergabe (`Idempotency-Replayed: true`). Derselbe Schlüssel mit anderen Daten wird mit `409 idempotency_reuse` abgewiesen: gleicher Wiederholversuch, gleicher Schlüssel; geänderte Eingabe, neuer Schlüssel.

### Statusmeldungen statt Dauerabfrage

Wer unter `POST /v1/webhooks` eine `https`-Adresse hinterlegt, bekommt `order.status_changed` zugestellt, sobald sich etwas ändert. Jede Meldung trägt `webhook-id`, `webhook-timestamp` und `webhook-signature: v1,<Base64>`. Signiert wird `<id>.<timestamp>.<Rumpf>` mit dem Geheimnis aus der Antwort beim Anlegen. Fehlversuche werden acht Mal mit wachsendem Abstand wiederholt.

### Als MCP-Server einbinden

Wer mit Claude, ChatGPT, Codex oder einer anderen Agenten-Oberfläche arbeitet, bindet uns als Verbindung ein: `https://mvg-frankfurt.de/mcp` (Streamable HTTP, Spezifikation 2026-07-28, zustandslos; ältere Clients mit `initialize` gehen weiter). Die Werkzeuge rechnen mit derselben Engine wie der Shop. Preise kommen netto und brutto, Kanal online.

```
# Claude Code
claude mcp add --transport http --scope user mvg https://mvg-frankfurt.de/mcp

# Codex
codex mcp add mvg --url https://mvg-frankfurt.de/mcp

# VS Code
code --add-mcp '{"name":"mvg","type":"http","url":"https://mvg-frankfurt.de/mcp"}'

# Cursor (~/.cursor/mcp.json)
{"mcpServers": {"mvg": {"url": "https://mvg-frankfurt.de/mcp"}}}

# Mit MVG-API-Key statt Zustimmung im Browser
claude mcp add --transport http mvg https://mvg-frankfurt.de/mcp \
  --header "Authorization: Bearer mvg_live_…"
```

In Claude Desktop und claude.ai: Einstellungen → Konnektoren → eigenen Konnektor mit derselben Adresse hinzufügen. In ChatGPT (Entwicklermodus) genauso als eigenen Konnektor. Die Server-Beschreibung mit Fähigkeiten, Anmeldewegen, empfohlenen Werkzeugen und Ratenbremse steht unter [/.well-known/mcp.json](https://mvg-frankfurt.de/.well-known/mcp.json).

| Werkzeug | Zugang | Scope | Ändert Daten | Zweck |
|---|---|---|---|---|
| `find_materials` | öffentlich | – | nein | Blech-Werkstoffe mit lesbarem Code, Stärken, Tafelformaten, REACH-Hinweis; Halbzeug-Suche mit Maßen (z. B. „Alu-Winkel 15 × 15 × 2“ = Halbzeug, kein Kantteil) |
| `get_price` | öffentlich | – | nein | Richtpreis für Blech-Zuschnitt, Kantteil, Halbzeug-Zuschnitt und Zubehör, netto und brutto |
| `list_part_templates` | öffentlich | – | nein | Formen des Teile-Editors (Rechteck, Ronde, Ring, Flansch, Lochbild, Langloch, Laschen …) mit Parametern, Grenzen, Beispiel |
| `configure_part` | öffentlich | – | nein (temporärer Entwurf, 7 Tage) | Laserteil aus Vorlage + Maßen (+ Zusatzlöcher): Prüfung, Shop-Preis, bemaßte Vorschau (SVG), Link in den Teile-Editor |
| `configure_plate` | öffentlich | – | nein (temporärer Entwurf, 7 Tage) | Lochplatte L × B mit Löchern (x, y, Ø ab linker unterer Ecke): wie configure_part |
| `check_manufacturability` | öffentlich (mit Datei: Anmeldung, designs:write) | – | nein | Konstruktionsgrenzen und Prüfung eines Kantteils |
| `get_lead_time` | öffentlich | – | nein | Termine je Stufe, Schnellversand-Regel |
| `get_shipping_estimate` | öffentlich | – | nein | Packstücke und Versandkosten (Richtwert) |
| `search_docs` | öffentlich | – | nein | Magazin, Konstruktionsrichtlinien, FAQ, Preise, Versand |
| `get_agent_guidance` | öffentlich | – | nein | Leitfaden: Reihenfolge, Einheiten, Verbote |
| `normalize_material` | öffentlich | – | nein | Freier Werkstoff-Text („V2A 2mm“, „AlMg3“) → Werkstoff-Code mit Dicken |
| `get_delivery_options` | öffentlich | – | nein | Alle Lieferstufen mit Termin und die Versandkosten zur Postleitzahl in einem Aufruf |
| `find_hole_operations` | öffentlich | – | nein | Gewinde und Senkungen je Werkstoff und Dicke: Größen, Preis je Stück, ob es geht |
| `whoami` | angemeldet | `catalog:read` | nein | Für wen spricht der Zugang, welche Rechte gelten |
| `create_upload` | angemeldet | `designs:write` | ja (Upload-Link) | signierter Link für eine STEP-, DXF-, AI- oder EPS-Datei (AI/EPS wird zu DXF in mm) |
| `create_quote` | angemeldet | `quotes:write` | ja (Angebot) | Angebot (24 Stunden) mit `checkout_url` in den Warenkorb; auch aus einem Entwurf (`part_draft`) |
| `update_quote_parts` | angemeldet | `quotes:write` | ja (neue Fassung) | Mengen/Positionen ändern ergibt eine neue Fassung, die alte bleibt unverändert |
| `get_quote` | angemeldet | `quotes:read` | nein | Angebot erneut lesen |
| `upload_status` | angemeldet | `designs:write` | nein | Ist die Datei angekommen? (waiting, received, expired) |
| `add_quote_parts` | angemeldet | `quotes:write` | ja (neue Fassung) | Stückliste schrittweise: weitere Positionen anhängen |
| `list_quotes`, `get_link` | angemeldet | `quotes:read` | nein | Eigene Angebote; Link in den Warenkorb (zum Weitergeben) oder auf die Bilder einer Position |
| `list_orders`, `check_order_status` | angemeldet (OAuth mit Kundenkonto) | `orders:read` | nein | Bestellungen und Status des Kundenkontos |
| `reorder_from_order` | angemeldet (OAuth mit Kundenkonto) | `orders:read` | ja (Angebot) | Teile einer Bestellung zu heutigen Preisen neu anbieten; bestellt nichts |

Die Werkzeugliste (`tools/list`) nennt dasselbe maschinenlesbar in `_meta` (`requires_login`, `scope`, `changes_data`) und in jeder Beschreibung. `quotes:write` schließt `quotes:read` ein.

**Bestellen und Bezahlen gibt es per MCP nicht.** Das Angebot liefert einen Link in den Warenkorb der Website; dort bestellt und bezahlt ein Mensch. Die Anmeldung passiert von selbst: Ein Konto-Werkzeug ohne Token antwortet mit 401 und verweist auf `/.well-known/oauth-protected-resource/mcp`; der Client registriert sich und schickt den Kunden auf die Zustimmungsseite (in Claude Code: `/mcp` → Server → Authenticate). Token für den MCP-Server gelten nur dort (`resource` = `https://mvg-frankfurt.de/mcp`) und tragen kein Bestellrecht. Fachfehler kommen als Werkzeug-Ergebnis mit `isError` und einem Problem-Dokument nach RFC 9457. Das Prozesswissen liefert der Server als `instructions` mit.

### Fertigungsfeedback mit Bild

Jede Prüfung und jedes Angebot liefert einen festen Block `dfm` bzw. `feedback`: Zähler für Sperren und Hinweise, je Befund den Ort (Kantung), den Grenzwert und eine direkt anwendbare Korrektur mit ihrer Preiswirkung. Dazu kommen zwei Bilder: der Querschnitt mit Maßen (betroffene Schenkel rot) und die Biegeschritte an unserer Kantbank mit Werkzeug (Kollision rot).

```
"feedback": {
  "status": "blocked", "counts": {"block": 1, "warn": 0},
  "issues": [{
    "code": "bend_collision", "where": {"bend": 1},
    "limit": {"max_mm": 33, "segment": 3},
    "fix": [{"field": "segments_mm[2]", "value": 33, "price_effect_net": -370}]
  }],
  "visual": {"part_svg_url": "…", "bending_svg_url": "…"}
}
```

Beispiel U-Profil 60/20/60, 2 mm: Biegeschritte mit Werkzeug (Richtwert).

### Agenten-Prompt zum Kopieren

```
Verbinde dich mit dem MCP-Server von MVG Frankfurt: https://mvg-frankfurt.de/mcp (Streamable HTTP).
Lies zuerst get_agent_guidance. Werkstoff aus freiem Text mit normalize_material zuordnen.
Preise nennt nur der Server (get_price, netto und brutto). Kantteile mit check_manufacturability prüfen,
Befunde wörtlich nennen und die Bilder (visual) zeigen; nur bei 0 Sperren und 0 Hinweisen "fehlerfrei" sagen.
Für ein Angebot create_quote, dann checkout_url an mich. Nichts selbst bestellen oder bezahlen.
```

### Beispiel-Prompts

- „Was kostet ein Zuschnitt 500 × 300 mm aus 2 mm AlMg3, 4 Stück, netto und brutto?“
- „Prüfe ein U-Profil 60/20/60 aus 2 mm Stahl, 500 mm lang, und zeig mir die Biegeschritte.“
- „Mach daraus ein fertigbares Teil und sag mir, was die Änderung kostet.“
- „Flansch Ø 200 mit 4 Löchern Ø 9 auf Lochkreis 140, 3 mm Stahl, 10 Stück: Preis und Vorschau.“
- „4 Stück Alu-Flachstange 20 × 5, je 1200 mm: Preis und Termin.“
- „Welche Gewinde gehen in 2 mm Edelstahl, und was kostet M5?“
- „Lieferoptionen und Versandkosten nach 60314 für diese Teile.“
- „Hier sind 6 STEP-Dateien: ein Angebot über alle, 10 Stück je Teil, AlMg3 3 mm.“
- „Nochmal wie meine letzte Bestellung, aber 20 statt 10 Stück.“

### Fehler

Jede Fehlerantwort unter `/v1` ist ein Problem-Dokument nach RFC 9457 (`application/problem+json`) mit stabilem `code`, dem betroffenen Feld als `param`, der Angabe `retryable`, einer `doc_url` auf diesen Abschnitt und einer `request_id` für Rückfragen.

|  |  |
|---|---|
| `invalid_request` | Anfrage ist unvollstaendig oder widerspruechlich: HTTP 422, nicht wiederholbar |
| `unauthorized` | OAuth-Token oder MVG-API-Key fehlt: HTTP 401, nicht wiederholbar |
| `invalid_token` | OAuth-Token oder MVG-API-Key ist ungültig oder widerrufen: HTTP 401, nicht wiederholbar |
| `insufficient_scope` | Der Schluessel hat diese Berechtigung nicht: HTTP 403, nicht wiederholbar |
| `upload_not_found` | Upload nicht gefunden oder abgelaufen: HTTP 404, nicht wiederholbar |
| `upload_expired` | Der Upload-Link ist abgelaufen: HTTP 410, nicht wiederholbar |
| `not_found` | Objekt nicht gefunden: HTTP 404, nicht wiederholbar |
| `design_not_found` | Design nicht gefunden: HTTP 404, nicht wiederholbar |
| `quote_not_found` | Angebot nicht gefunden: HTTP 404, nicht wiederholbar |
| `quote_expired` | Angebot ist abgelaufen: HTTP 409, nicht wiederholbar |
| `price_changed` | Der Preis hat sich geaendert: HTTP 409, nicht wiederholbar |
| `not_manufacturable` | Teil braucht eine Anpassung: HTTP 422, nicht wiederholbar |
| `requirements_open` | Offene Hinweise wurden nicht bestaetigt: HTTP 409, nicht wiederholbar |
| `file_too_large` | Datei ist zu gross: HTTP 413, nicht wiederholbar |
| `unsupported_file` | Dateiformat wird nicht unterstuetzt: HTTP 422, nicht wiederholbar |
| `idempotency_reuse` | Idempotenz-Schluessel mit anderen Daten benutzt: HTTP 409, nicht wiederholbar |
| `idempotency_pending` | Gleicher Idempotenz-Schluessel wird gerade verarbeitet: HTTP 409, wiederholbar |
| `shipping_unavailable` | Versand an diese Adresse ist nicht buchbar: HTTP 409, nicht wiederholbar |
| `payment_unavailable` | Zahlungsseite konnte nicht geoeffnet werden: HTTP 502, wiederholbar |
| `pricing_unavailable` | Preis derzeit nicht ermittelbar: HTTP 503, wiederholbar |
| `account_binding_required` | Nur für ein Kundenkonto (OAuth-Zustimmung, bei `/v1` auch an ein Konto gebundener MVG-API-Key): HTTP 403, nicht wiederholbar |
| `limit_exceeded` | Betragsgrenze der OAuth-Zustimmung überschritten: HTTP 409, nicht wiederholbar |
| `login_required` | Tageskontingent ohne Anmeldung erreicht. Bitte anmelden bzw. MVG-API-Key verwenden; HTTP 401, nicht wiederholbar |
| `order_limit_exceeded` | Bestellung liegt über dem Bestell-Limit des MVG-API-Key (€ brutto je Bestellung): HTTP 403, nicht wiederholbar |
| `rate_limited` | Zu viele Anfragen: HTTP 429, wiederholbar |
| `capacity` | Kalkulation gerade ausgelastet: HTTP 503 mit `Retry-After`, wiederholbar |
| `internal_error` | Bitte erneut versuchen: HTTP 500, wiederholbar |

## Der Bestellpfad des Browsers

|  |  |
|---|---|
| `GET /api/materials` | Werkstoffe, Blechstärken und die je Stärke bestellbaren Tafelformate |
| `GET /api/profiles/catalog` | Halbzeug-Katalog: Rohre, Profile, Flach- und Rundmaterial |
| `POST /api/pricing/calculate` | Preis für Zuschnitte, Kantteile und Halbzeug-Abschnitte inklusive Mengenstaffel |
| `POST /api/pricing/step-quickcalc` | Preis zu einer hochgeladenen STEP-Datei |
| `POST /api/feasibility/check` | Fertigbarkeitsprüfung gegen die Maschinengrenzen, vor dem Bestellen |
| `POST /api/online/shipping-quote` | Versandkosten zu Postleitzahl und Warenkorb |
| `POST /api/online/orders` | Bestellung anlegen; die Antwort enthält den Status-Token |
| `GET /api/online/orders/{token}` | Zahlungs- und Auftragsstatus |

Die vollständige Beschreibung aller öffentlichen Endpunkte mit Feldern und Beispielen steht als OpenAPI-Dokument unter [/openapi.json](https://mvg-frankfurt.de/openapi.json). Sie lässt sich direkt in einen Client-Generator oder in ein Agenten-Werkzeug laden.

## Deep-Links in die Konfiguratoren

Jeder Konfigurator lässt sich mit Vorbelegung aufrufen, etwa für Links aus Katalogen, E-Mails, ERP-Systemen oder Agenten. Alle Parameter sind optional, Maße in Millimetern, Dezimaltrenner Punkt oder Komma; unbekannte Werte werden ignoriert, Werkstoff-Codes kommen aus `GET /api/materials` (Feld `code`, z. B. `stahl-s235jr`, `edelstahl-1.4301`, `aluminium-almg3`).

- **Kantteil** `/teile-designer/kantteil`: `form=L|U|Z|C` mit `a` (Mittelschenkel), `b`, `c`, `winkel` (Vorgabe 90) oder generisch `a`, `rechts=50,30`, `wr=90,45`, `sr=-1,-1`, `links=40`, `wl=90`, `sl=1`; dazu `t` (Stärke), `mat`, `tiefe` (Kantlänge), `qty`, `mass=innen|aussen`, `phase=material|output`.   Beispiel: [`/teile-designer/kantteil?form=L&a=100&b=50&t=2&mat=stahl-s235jr&tiefe=500&qty=3`](https://mvg-frankfurt.de/teile-designer/kantteil?form=L&a=100&b=50&t=2&mat=stahl-s235jr&tiefe=500&qty=3)
- **Blechzuschnitt** `/online/cutting`: `l`, `b`, `t`, `mat`, `qty`, `phase=material`.   Beispiel: [`/online/cutting?l=300&b=200&t=2&mat=stahl-s235jr&qty=10`](https://mvg-frankfurt.de/online/cutting?l=300&b=200&t=2&mat=stahl-s235jr&qty=10)
- **Rohre, Stangen & Halbzeuge** `/online/profiles`: `art=<Artikelnummer>` öffnet den Artikel direkt im Zuschnitt. Beispiel: [`/online/profiles?art=37000`](https://mvg-frankfurt.de/online/profiles?art=37000)
- **Teile-Designer** `/teile-designer`: `tpl=rechteck|ronde|ring|flansch|montage|langlasche|lasche|dogear|rahmen|vent|polygon|gusset|eckrund|trapez|zprofil|wanne`, Maße wie in der Maße-Karte (`L`, `B`, `D`, `d`, …), `t`, `mat`, `qty`, `phase=ausschnitte|fertig`.   Beispiel: [`/teile-designer?tpl=rechteck&L=400&B=250&t=3&mat=stahl-s235jr&qty=2`](https://mvg-frankfurt.de/teile-designer?tpl=rechteck&L=400&B=250&t=3&mat=stahl-s235jr&qty=2)
- **Werkstoff** (`mat=`): lesbarer Code aus `GET /api/materials` (Feld `code`), z. B. `stahl-s235jr`, `edelstahl-1.4301`, `aluminium-almg3`, Lochbleche `edelstahl-1.4301-lochblech-rv5-8` (Rv = Rundloch versetzt, Qg = Quadratloch gerade, Zahlen = Lochweite-Teilung in mm). Ältere interne Kennungen bleiben als Alias gültig; alle API-Felder `material_id` akzeptieren den Code. Lochbleche gibt es als Rechteckzuschnitt und als Kantteil (seit 11.10.2026; größere Winkel- und Maßtoleranzen), der Materialpreis gilt immer je ganze Tafel.
- **Gespeicherter Stand**: `?s=<token>` auf `/teile-designer/kantteil|cutting|profiles` und `/teile-designer`. Der Token kommt aus dem Knopf „Teilen" oder `POST /api/online/share` (`{"kind","state"}`); `?s=` hat Vorrang vor den lesbaren Parametern.

## Preis abfragen

Eine ebene Platte 200 × 150 mm aus 2 mm Aluminium AlMg3, fünf Stück. Die `material_id` nimmt den lesbaren Code aus `/api/materials`:

```
curl -s https://mvg-frankfurt.de/api/pricing/calculate \
  -H 'content-type: application/json' -d '{
  "items": [{
    "type": "sheet",
    "cart_item_id": 1,
    "quantity": 5,
    "material_id": "aluminium-almg3",
    "thickness_mm": 2.0,
    "depth_mm": 150,
    "profile": { "thickness_mm": 2.0, "center": { "length_mm": 200 } }
  }]
}'
```

Zurück kommt der Netto- und Bruttopreis je Position und für den gesamten Warenkorb: derselbe Preis, den ein Kunde im Browser sieht. Es gibt keinen zweiten Preis für Maschinen. Zusätzlich liefert jede Position unter `scale_prices` die gesamte Mengenstaffel von 1 bis 100 Stück mit, sodass ein Agent die wirtschaftliche Losgröße in einem einzigen Aufruf bestimmen kann.

Ein Kantteil entsteht aus demselben Aufruf, indem das `profile` um Segmente und Biegungen ergänzt wird: `right_segments`/`right_joints` und `left_segments`/`left_joints` beschreiben den Querschnitt, `depth_mm` die Länge der Biegelinie.

## Was der Preis enthält

Material, Zuschnitt, Kantungen und Entgraten sind im Positionspreis enthalten; der Preis gilt netto in Euro zuzüglich 19 % Umsatzsteuer. Die Preisantwort liefert je Position den Aufriss (`breakdown`) und die Mengenstaffel (`scale_prices`). Alle Kosten bis auf die Auftragspauschale sind im Positionspreis enthalten, auch das Einrichten der Maschinen. Die Auftragspauschale steht einmal je Auftrag im Feld `auftragspauschale` (ab 250 € Warenwert `null`); `ruest_zeilen` und `kleinmengen_zuschlag` bleiben `null`. Rechnen Sie den Auftrag deshalb immer als Ganzes. Jede Position geht auf: Menge × Einzelpreis = Positionsbetrag. Versandkosten stammen aus der Versandquote, die Abholung in Frankfurt ist kostenfrei. Maßgefertigte Teile sind vom Widerrufsrecht ausgenommen. Die Grenzen, innerhalb derer ein Teil überhaupt fertigbar ist, stehen in den [Konstruktionsrichtlinien](https://mvg-frankfurt.de/konstruktionsregeln#richtlinien).

## Faire Nutzung

Rechenintensive Endpunkte sind mengenbegrenzt, je aufrufender Adresse und Minute: 20 Anfragen für die Kalkulation hochgeladener Dateien (STEP, DXF), 120 für Preis, Optimierung, Schachtelung und Versandquote. Darüber antworten wir mit HTTP 429 und einem `Retry-After`-Kopf. Lesende Abrufe wie Katalog und Werkstoffe sind nicht begrenzt. Ein Preisaufruf trägt höchstens 200 Positionen. Wer regelmäßig größere Volumina braucht (etwa für eine CAD-Integration, ein Beschaffungssystem oder einen Einkaufsagenten), schreibt uns unter [info@mvg-frankfurt.de](mailto:info@mvg-frankfurt.de); dann heben wir das Kontingent an.

## Für KI-Agenten

Unter [/llms.txt](https://mvg-frankfurt.de/llms.txt) steht eine kurze, maschinenlesbare Übersicht mit allen Einstiegen; [/llms-full.txt](https://mvg-frankfurt.de/llms-full.txt) enthält denselben Stoff vollständig: Leistungen, Werkstoffe, Fertigungsgrenzen, Preisregeln und Versandbedingungen in einer Datei. Beides ist bewusst öffentlich: Ein Agent soll ohne Umweg über gerendertes HTML herausfinden können, was wir fertigen und was es kostet.

### Kurz für Agenten

- **Preise** holen Sie am besten über Preis per Link, den MCP-Server oder `/v1`. Die Konfiguratoren rechnen erst im Browser und eignen sich nicht zum Auslesen.
- **Bei HTTP 429 oder 503** warten Sie die Sekunden aus `Retry-After` ab. Die Antwort ist JSON nach RFC 9457 mit `error` (`rate_limited` bzw. `capacity`) und `retry_after`. Für viele Abfragen eignet sich `/v1` mit MVG-API-Key.
- **Markdown**: Jede Inhaltsseite gibt es als Markdown, mit `Accept: text/markdown` auf derselben Adresse oder unter `<pfad>.md` (z. B. [/preise.md](https://mvg-frankfurt.de/preise.md), Startseite [/index.md](https://mvg-frankfurt.de/index.md)). Der Text entsteht automatisch aus der Seite.
- **Alle Adressen** stehen im [Sitemap-Index](https://mvg-frankfurt.de/sitemap.xml), aufgeteilt nach Seiten, Werkstoffen, Halbzeugen, Maschinenbauprofilen, Anwendungen und Magazin.

[OpenAPI-Spec öffnen →](https://mvg-frankfurt.de/openapi.json)
