White-label PDF WordPress nélkül: inline branding egy mezőn keresztül

Eddig a whitelabel: true a jelentés‑endpointjainkban WordPress‑fiókot igényelt, amelynek be van állítva a kulcs a whitelabel_configs‑ben. Ez történelmileg így van – korábban a fehér címke a WP‑plugin Pro‑funkciója volt, és az API egyszerűen olvasta ugyanazt az adatbázistáblát.

SDK‑felhasználók számára WP nélkül ez azt jelentette, hogy a brand‑config nem lehetséges további HTTP‑ugrás nélkül (külön konfigurációs szolgáltatást kell tartani, szinkronizálni a miénkkel, majd elküldeni a whitelabel: true‑t).

Most a mező inline‑objektumot fogad el, amely tartalmazza a branding összes 15 mezőjét. Egy kérés = a teljes márka kontextus = személyre szabott 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"
    }
  }'

A PDF a logóval a fejlécben, egyedi címmel a borítón, a megfelelő theme‑color kiemelésekkel a chart‑SVG‑ben, valamint egy kapcsolati blokkot a láblécben rendereli.

Minden opcionális – a hiányzó mező az adatbázis‑konfigurációból veszi az értéket (ha az API‑kulcs WP‑felhasználóhoz van kötve), vagy a rendszer alapértelmezéseiből (SDK‑kliensek WP nélkül).

12 endpoint a /v1/reports/* családból ugyanúgy fogadja ezt a mezőt: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

A Boolean mód élő és nem változott:

• whitelabel: true: az adatbázis‑konfigurációt olvassa a kapcsolt WP‑felhasználóhoz (mint korábban)
• whitelabel: false vagy a mező hiányzik: az alapértelmezett AstroWay branding
• whitelabel: {…}: inline‑objektum, új viselkedés

Az OpenAPI‑séma a mezőhöz boolean | BrandingObject lett (unió típus). Egyetlen meglévő kérés sem fog elromlani.

Ha az API‑kulcs WP‑felhasználóhoz van kötve ÉS a kliens inline‑objektumot küld – az inline felülírja az adatbázist. Konkrétan:

1. Rendszer alapértelmezések (astroway branding)
2. DB‑konfiguráció a whitelabel_configs‑ből (ha a WP‑felhasználónak van ilyen)
3. Inline‑objektum a kérés body‑jában

Az összeolvasztás sekély, kulcsonként. Tehát inline.themeColor = "#ff5500" felülírja a DB‑értéket, de egy hiányzó inline.logoUrl megőrzi a DB‑logót. Ez kényelmes SaaS‑szcenáriókban, ahol az alap branding az adatbázisban van, a per‑tenant finomhangolás pedig inline érkezik.

Belső leképezés: a themeColor primaryColor‑ra változik az applyBrandingPreferences hívása után, a fontPairing a CSS font-family stack‑re map-olódik a Handlebars sablonban (például, serif-sans = font-family: 'Playfair Display', serif a címekhez + 'Inter', sans-serif a törzshöz).

A BrandingObject most egy külön komponens a /v1/openapi.json‑ben – ez azt jelenti, hogy a következő SDK (TS / Python / PHP) kiadás egy típusosztályt kap:

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

Az SDK‑csomagok roadmapjai a megfelelő staging repókban vannak (astroway-typescript-staging/ROADMAP.md, stb.). A Cron 5‑8 naponta publikál kisebb kiadásokat; a típusos BrandingObject a közeljövőben megjelenik.

Korábban egy SaaS‑fogyasztó számára, aki az AstroWay PDF‑generálást saját termékébe integrálja, az út a következő volt:

1. Létrehozni egy tenants táblát a branding_json mezővel
2. Minden jelentéskérés előtt lekérni a felhasználó konfigurációját
3. Nem tudni, hogyan kell átadni az API‑nak WP‑plugin nélkül (korábban: egyáltalán nem, kérni kellett tőlünk egy bejegyzést a whitelabel_configs‑ben a SaaS‑felhasználóhoz)
4. Vagy saját renderelővel PDF‑post‑processzálni: ez plusz infrastruktúra

Most az út:

1. Tárold a branding_json‑t nálad
2. Küldd inline‑ban a whitelabel‑ben minden kérésnél

Kevesebb HTTP‑ugrás, nulla DB‑szinkronizáció a szolgáltatások között, teljes kontroll a branding felett kérésenként.

Az inline mód minden csomagnál elérhető, ahol PDF‑jelentések vannak – az Indie ($19/hó) és a Business között. A Free szint nem ad PDF‑et (ez szándékos – a Free szinten csak ingyenes JSON, renderelés nélkül). A kérés kreditköltsége nem változik – az inline konfiguráció nem ad hozzá credit‑cost‑ot a renderhez.

A dokumentáció minden 12 endpointhoz frissítve lett inline‑móddal példákkal. Lásd a /docs/api/ → Reports oldalt.