White-label PDF ohne WordPress: inline branding über ein Feld

Bis heute erforderte whitelabel: true in unseren Report-Endpunkten ein WordPress‑Konto mit konfigurierten Schlüsseln in whitelabel_configs. Das ist historisch – früher war das White‑Label eine Pro‑Funktion des WP‑Plugins, und die API las einfach dieselbe DB‑Tabelle.

Für SDK‑Nutzer ohne WP bedeutete das: brand‑config war ohne einen zusätzlichen HTTP‑Sprung nicht möglich (einen separaten Config‑Service betreiben, mit unserem synchronisieren und dann whitelabel: true senden).

Jetzt akzeptiert das Feld ein inline‑Objekt mit allen 15 Branding‑Feldern. Eine Anfrage = voller Marken‑Kontext = personalisiertes PDF.

curl -X POST https://api.astroway.info/v1/reports/natal \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chart": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52,
      "name": "Maria"
    },
    "whitelabel": {
      "companyName": "Acme Astrology",
      "companyUrl": "https://acme-astro.example.com",
      "companyEmail": "hello@acme-astro.example.com",
      "logoUrl": "https://cdn.example.com/logo.png",
      "themeColor": "#ff5500",
      "headingColor": "#1a1a2e",
      "reportName": "My Personal Cosmic Map",
      "footerText": "© 2026 Acme Astrology",
      "fontPairing": "serif-sans"
    }
  }'

Das PDF wird mit einem Logo im Header, einem benutzerdefinierten Titel auf dem Cover, passenden theme‑color Akzenten im Chart‑SVG und einem Kontakt‑Block im Footer gerendert.

Alle optional – ein fehlendes Feld übernimmt den Wert aus der DB‑Konfiguration (wenn der API‑Schlüssel an einen WP‑Nutzer gebunden ist) oder aus den systemeigenen Defaults (für SDK‑Kunden ohne WP).

12 Endpunkte der Familie /v1/reports/* akzeptieren dieses Feld einheitlich: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Der Boolean‑Modus ist weiterhin aktiv und hat sich nicht geändert:

• whitelabel: true: liest die DB‑Konfiguration für den gebundenen WP‑Nutzer (wie zuvor)
• whitelabel: false oder das Feld fehlt: Standard‑AstroWay‑Branding
• whitelabel: {…}: Inline‑Objekt, neues Verhalten

Das OpenAPI‑Schema für das Feld ist jetzt boolean | BrandingObject (Union‑Typ). Keine bestehende Anfrage wird brechen.

Wenn der API‑Schlüssel an einen WP‑Nutzer gebunden ist und der Client ein Inline‑Objekt sendet – das Inline‑Objekt hat Vorrang vor der DB. Konkret:

1. System‑Defaults (AstroWay‑Branding)
2. DB‑Konfiguration aus whitelabel_configs (falls der WP‑Nutzer eine hat)
3. Inline‑Objekt aus dem Request‑Body

Merge – shallow, Schlüssel‑für‑Schlüssel. Das heißt, inline.themeColor = "#ff5500" überschreibt den DB‑Wert, aber ein fehlendes inline.logoUrl lässt das DB‑Logo erhalten. Das ist praktisch für SaaS‑Szenarien, bei denen das Basis‑Branding in der DB liegt und per‑Tenant‑Feintuning inline kommt.

Interne Zuordnung: themeColor wird nach Aufruf von applyBrandingPreferences zu primaryColor, fontPairing wird auf den CSS‑font-family‑Stack im Handlebars‑Template gemappt (z. B. serif-sans = font-family: 'Playfair Display', serif für Überschriften + 'Inter', sans-serif für den Body).

BrandingObject ist jetzt ein separates Component in /v1/openapi.json – das bedeutet, dass das nächste SDK‑Release (TS / Python / PHP) eine typisierte Klasse erhalten wird:

// TS SDK - після наступного codegen-релізу
import { Astroway } from "@astroway/sdk";

const client = new Astroway({ apiKey: process.env.ASTROWAY_KEY });

const pdf = await client.reports.natal.create({
  chart: { date: "1990-05-15", time: "14:30", /* ... */ },
  whitelabel: {
    companyName: "Acme Astrology",
    themeColor: "#ff5500",
    reportName: "My Personal Cosmic Map",
    fontPairing: "serif-sans",  // typed enum, autocomplete у IDE
  },
});

Roadmaps der SDK‑Pakete – in den jeweiligen Staging‑Repos (astroway-typescript-staging/ROADMAP.md usw.). Der Cron veröffentlicht alle 5‑8 Tage Minor‑Releases; das typisierte BrandingObject kommt bald.

Früher war der Weg für einen SaaS‑Konsumenten, der die AstroWay‑PDF‑Generierung in sein Produkt integriert, folgender:

1. Eine eigene Tabelle tenants mit dem Feld branding_json pflegen
2. Vor jedem Report‑Request die Konfiguration des eigenen Users abrufen
3. Nicht wissen, wie man das an die API ohne WP‑Plugin übergibt (früher: gar nicht, man musste uns bitten, einen Eintrag in whitelabel_configs für den SaaS‑User anzulegen)
4. Oder das PDF‑Post‑Processing mit eigenem Renderer durchführen: das ist zusätzliche Infrastruktur

Jetzt der Weg:

1. branding_json intern speichern
2. Inline in whitelabel für jede Anfrage übergeben

Weniger HTTP‑Sprünge, null DB‑Synchronisation zwischen den Services, volle Kontrolle über das Branding per Request.

Der Inline‑Modus ist auf allen Tarifen verfügbar, die PDF‑Reports bieten – von Indie ($19/Monat) bis Business. Der Free‑Tier liefert kein PDF (absichtlich – im Free‑Tier gibt es nur kostenloses JSON, kein Rendering). Die Kreditkosten pro Anfrage ändern sich nicht – die Inline‑Konfiguration fügt keinen zusätzlichen credit‑cost zum Rendering hinzu.

Die Dokumentation für alle 12 Endpunkte wurde mit Beispielen für den Inline‑Modus aktualisiert. Siehe /docs/api/ → Reports.