Reports V2: ein Endpunkt statt zwölf - `/v1/reports/generate`

12 Arten von PDF-Berichten - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - lebten bisher als 12 separate Routen. Jeder hat sein eigenes Schema, seinen chart-payload und seine Preisklasse. Das ist zwar REST-konform, aber es erzeugt ein DX-Problem auf zwei Ebenen:

1. SDK-Oberfläche. Der TypeScript-Client hat 12 Methoden client.reports.natal(), client.reports.synastry(), … Jeder neue Berichtstyp bedeutet eine brechende Änderung im öffentlichen API-SDK (eine Minor-Version mit neuer Methode).
2. MCP-Katalog. Der gehostete MCP-Server stellt 686 Tools bereit: Jeder der 12 Reports belegt einen eigenen Tool-Eintrag. Ein AI-Agent, der über MCP geht, muss 12 Tool-Beschreibungen scannen, um das richtige auszuwählen. Das erzeugt Rauschen bei der Tool-Auswahl.

Der neue Endpunkt POST /v1/reports/generate ist ein Dispatcher mit dem report_type-Enum.

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "natal",
    "chart": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52,
      "name": "Test"
    },
    "language": "uk",
    "whitelabel": {
      "themeColor": "#ff5500",
      "reportName": "My Cosmic Map"
    }
  }'

12 gültige Werte für report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Verschiedene Typen benötigen unterschiedliche Payload-Felder. Der Dispatcher führt die Validierung im Handler durch und gibt einen typisierten 400-Fehler zurück:

Also steuert report_type nicht nur den Render-Routen, sondern auch die Validierungsregeln für den Anfragekörper.

Die Rückwärtskompatibilität ist voll gewährleistet: Alle 12 typspezifischen Endpunkte bleiben erhalten. Der neue /v1/reports/generate ist eine additive Oberfläche, kein Ersatz. Das bedeutet, dass bestehender Code nicht bricht, aber neuer Code kompakter geschrieben werden kann:

// Стара модель - direct method per type
const pdf1 = await client.reports.natal.create({ chart, whitelabel });
const pdf2 = await client.reports.synastry.create({ chart1, chart2 });
const pdf3 = await client.reports.tarot.create({ seed: "abc" });

// V2 - generic dispatcher
const pdf1 = await client.reports.generate({ report_type: "natal", chart, whitelabel });
const pdf2 = await client.reports.generate({ report_type: "synastry", chart1, chart2 });
const pdf3 = await client.reports.generate({ report_type: "tarot", seed: "abc" });

Was besser ist, hängt vom Use‑Case ab. Die Direct-Methode bietet ein besseres Type Narrowing (der TS‑Compiler weiß, dass client.reports.synastry.create() chart1 und chart2 erfordert). Der Generic‑Dispatcher bietet eine kleinere Oberfläche für dynamische Use‑Cases – beispielsweise, wenn du den Berichtstyp über ein UI‑Dropdown auswählst und keinen 12‑fachen Switch im Client‑Code haben möchtest.

Auf dem gehosteten MCP‑Server (mcp.astroway.info) gab es 12 separate Tools, jeweils mit vollständiger Parameterbeschreibung. Nach Hinzufügen von generate entfernen wir die alten nicht (rückwärtskompatibel) – aber der neue Tool astroway_reports_generate besitzt eine Beschreibung mit dem report_type‑Enum:

Tool: astroway_reports_generate
Description: Generates a PDF/HTML astrology report. Pass report_type to select template.
Parameters:
  report_type (enum): "natal" | "transit-yearly" | "synastry" | "business" | ...
  chart (object, required for most types): birth chart data
  chart1, chart2 (objects, required for synastry)
  language (string): "uk" | "en" | ...
  whitelabel (boolean | object): branding override

Ein AI-Agent erhält bei der Aufgabe „Erstelle mir ein Natal‑Chart für das Datum X“ einen Kandidaten mit einer klaren Beschreibung, statt 12 Kandidaten mit überlappenden Beschreibungen. Dadurch wird die Tool‑Selektion‑Genauigkeit auf Agentenebene verbessert.

Der Dispatcher fügt keine zusätzlichen Kosten hinzu. Jeder report_type wird an seinen internen Renderer weitergeleitet, der seinen eigenen Preisstufe hat:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → entsprechende Stufen
• tarot → TIER_4

Die konkreten Credit‑Zahlen findest du auf der Seite Preisgestaltung. Der Aufruf POST /v1/reports/generate mit report_type: "natal" kostet genau genauso viel wie der direkte Aufruf POST /v1/reports/natal.

Der neue whitelabel: BrandingObject‑Inline‑Modus (eingeführt am 2026-05-19) funktioniert über den generischen Dispatcher ohne Änderungen:

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "synastry",
    "chart1": { ... },
    "chart2": { ... },
    "whitelabel": {
      "companyName": "Acme Astrology",
      "logoUrl": "https://cdn.example.com/logo.png",
      "themeColor": "#ff5500"
    }
  }'

Ein Dispatch + ein Inline‑Whitelabel = eine vollständige White‑Label‑Integration mit minimaler SDK‑Oberfläche.

GenerateReport ist eine eigenständige Komponente in /v1/openapi.json. Es verwendet oneOf anhand des report_type‑Discriminators, was zu korrektem Codegen in Python (Pydantic) und PHP (getypte Unions à la psalm/phpstan‑Hinweise) führt.

Der nächste Codegen‑Release des SDK wird die Methode client.reports.generate() in allen drei Paketen (TS / Python / PHP) hinzufügen. Bis dahin kannst du über den generischen HTTP‑Client deines SDK aufrufen – der Payload ist in der OpenAPI‑Spec dokumentiert.

Es besteht kein dringender Migrationsbedarf – die direkten Endpunkte sind nicht veraltet. Dies ist eine reine DX‑Verbesserung für alle, denen die 12‑Methoden‑Oberfläche im Weg steht.