White-label PDF zonder WordPress: inline branding via één veld

Tot nu toe vereiste whitelabel: true in onze report‑endpoints een WordPress‑account met geconfigureerde sleutels in whitelabel_configs. Historisch gezien was het witte label een Pro‑feature van de WP‑plugin, en de API las gewoon dezelfde DB‑tabel.

Voor SDK‑gebruikers zonder WP betekende dit: brand‑config is niet mogelijk zonder een extra HTTP‑sprong (een aparte config‑service onderhouden, synchroniseren met de onze, en dan whitelabel: true sturen).

Nu accepteert het veld een inline‑object met alle 15 branding‑velden. Eén request = volledige merkcontext = gepersonaliseerde 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"
    }
  }'

PDF wordt gerenderd met een logo in de header, een aangepast titel op de cover, bijpassende theme‑color accenten in de chart‑SVG, en een contactblok in de footer.

Alle optionele velden - een weggelaten veld neemt de waarde uit de DB‑config (als de API‑sleutel gekoppeld is aan een WP‑gebruiker) of uit de systeem‑defaults (voor SDK‑klanten zonder WP).

12 endpoints van de familie /v1/reports/* accepteren dit veld op dezelfde manier: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

De boolean‑modus blijft actief en is niet veranderd:

• whitelabel: true: leest de DB‑config voor de gekoppelde WP‑gebruiker (zoals eerder)
• whitelabel: false of het veld ontbreekt: standaard AstroWay‑branding
• whitelabel: {…}: inline‑object, nieuw gedrag

Het OpenAPI‑schema voor het veld is nu boolean | BrandingObject (union type). Geen enkel bestaand request zal breken.

Als de API‑sleutel gekoppeld is aan een WP‑gebruiker EN de client een inline‑object stuurt, heeft het inline‑object voorrang boven de DB. Concreet:

1. Systeem‑defaults (astro‑way‑branding)
2. DB‑config met whitelabel_configs (als de WP‑gebruiker er één heeft)
3. Inline‑object uit de request‑body

Merge – shallow, key‑by‑key. Dus inline.themeColor = "#ff5500" overschrijft de DB‑waarde, maar een weggelaten inline.logoUrl laat het DB‑logo behouden. Handig voor SaaS‑scenario’s waar de basis‑branding in de DB zit en per‑tenant fine‑tuning inline komt.

Interne mapping: themeColor wordt primaryColor na aanroep van applyBrandingPreferences, fontPairing wordt gemapt naar de CSS font-family stack in het Handlebars‑template (bijv. serif-sans = font-family: 'Playfair Display', serif voor koppen + 'Inter', sans-serif voor de body).

BrandingObject is nu een apart component in /v1/openapi.json – dit betekent dat de volgende SDK‑release (TS / Python / PHP) een getypeerde klasse krijgt:

// 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 van de SDK‑pakketten – in de respectieve staging‑repo’s (astroway-typescript-staging/ROADMAP.md, enz.). Cron publiceert elke 5‑8 dagen een minor‑release; de getypeerde BrandingObject komt er binnenkort aan.

Eerder was de route voor een SaaS‑consument die AstroWay‑PDF‑generatie in zijn eigen product integreert:

1. Een eigen tabel tenants met het veld branding_json onderhouden
2. Voor elk rapport‑request: de config van de gebruiker ophalen
3. Niet weten hoe je dit naar de API stuurt zonder WP‑plugin (voorheen: nergens, je moest ons vragen een entry in whitelabel_configs voor de SaaS‑gebruiker te maken)
4. Of PDF‑post‑processing zelf doen met je eigen renderer: extra infra

Nu de route:

1. branding_json bij jou opslaan
2. Inline doorgeven in whitelabel voor elk request

Minder HTTP‑sprongen, nul DB‑synchronisatie tussen services, volledige controle over branding per request.

De inline‑modus is beschikbaar op alle abonnementen waar PDF‑rapporten deel van uitmaken – van Indie ($19/maand) tot Business. De Free‑tier biedt geen PDF (dit is opzettelijk – Free geeft alleen gratis JSON, geen rendering). De credit‑kosten per request blijven gelijk – een inline‑config voegt geen extra credit‑cost toe bovenop de rendering.

De documentatie voor alle 12 endpoints is bijgewerkt met voorbeelden van de inline‑modus. Zie Documentatie → Reports.