White-label PDF bez WordPress: inline branding přes jedno pole

Až dosud whitelabel: true v našich report-endpointech vyžadovalo WordPress účet s nastavenými klíči v whitelabel_configs. To je historické – dříve byl white label Pro-funkcí WP-pluginu a API jednoduše četlo stejnou DB-tabulku.

Pro SDK-uživatele bez WP to znamenalo: brand-config není možný bez dodatečného HTTP-skoku (držet samostatný konfigurační servis, synchronizovat s naším a poté posílat whitelabel: true).

Nyní pole přijímá inline-objekt se všemi 15 poli brandingu. Jeden požadavek = kompletní kontext značky = personalizované 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 se renderuje s logem v záhlaví, vlastním nadpisem na obálce, odpovídajícími akcenty theme-color v SVG grafech a blokem kontaktů v zápatí.

Všechna jsou volitelná – vynechané pole přebírá hodnotu z DB-konfigurace (pokud je API-klíč vázán na WP-uživatele) nebo ze systémových výchozích hodnot (pro SDK-klienty bez WP).

12 endpointů rodiny /v1/reports/* přijímá toto pole stejně: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Boolean-režim je živý a nezměnil se:

• whitelabel: true: čte DB-konfiguraci pro vázaného WP-uživatele (jako dříve)
• whitelabel: false nebo pole chybí: standardní AstroWay-branding
• whitelabel: {…}: inline-objekt, nové chování

OpenAPI-schéma pro pole se stalo boolean | BrandingObject (union type). Žádný existující požadavek se nerozbije.

Když je API-klíč vázán na WP-uživatele A klient posílá inline-objekt – inline převažuje nad DB. Konkrétně:

1. Systémové výchozí hodnoty (AstroWay-branding)
2. DB-konfigurace z whitelabel_configs (pokud ji WP-uživatel má)
3. Inline-objekt z těla požadavku

Sloučení je mělké, klíč po klíči. To znamená, že inline.themeColor = "#ff5500" přepíše DB-hodnotu, ale vynechané inline.logoUrl ponechá DB-logo. To je vhodné pro SaaS-scénáře, kde základní branding sídlí v DB a per-tenant doladění přichází inline.

Interní mapování: themeColor se stává primaryColor po volání applyBrandingPreferences, fontPairing se mapuje na CSS font-family stack v Handlebars-šabloně (například serif-sans = font-family: 'Playfair Display', serif pro nadpisy + 'Inter', sans-serif pro tělo).

BrandingObject je nyní samostatná komponenta v /v1/openapi.json – to znamená, že další vydání SDK (TS / Python / PHP) obdrží typizovanou třídu:

// 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
  },
});

Roadmapy SDK-balíčků jsou v příslušných staging-repozitářích (astroway-typescript-staging/ROADMAP.md, atd.). Cron publikuje minoritní vydání každých 5-8 dní; typizovaný BrandingObject bude v nejbližším.

Dříve pro SaaS-spotřebitele, který integruje AstroWay-generování PDF do vlastního produktu, cesta byla:

1. U sebe vytvořit tabulku tenants s polem branding_json
2. Před každým report-požadavkem: načíst konfiguraci svého uživatele
3. Nerozumět, jak to předat do API bez WP-pluginu (dříve: nijak, museli jste nás požádat o vytvoření záznamu v whitelabel_configs pro SaaS-uživatele)
4. Nebo provádět PDF-postprocessing vlastním rendererem: to je dodatečná infrastruktura

Nyní cesta:

1. Ukládat branding_json u sebe
2. Předávat inline v whitelabel pro každý požadavek

Méně HTTP-skoků, nulová DB-synchronizace mezi službami, plná kontrola nad brandingem per-request.

Inline-režim je dostupný na všech tarifech, kde jsou PDF-reporty – od Indie (19 $/měsíc) po Business. Free tier PDF neposkytuje (to je záměrné – ve Free je zdarma JSON, bez renderování). Kreditní cena požadavku se nemění – inline-konfigurace nepřidává credit-cost nad rámec renderování.

Dokumentace pro všech 12 endpointů je aktualizována s příklady inline-režimu. Podívej se na /docs/api/ → Reports.