White-label PDF WordPress olmadan: tek bir alan üzerinden inline branding

Şu ana kadar whitelabel: true rapor endpointlerimizde, whitelabel_configs içinde yapılandırılmış anahtarlarla bir WordPress hesabı gerektiriyordu. Bu tarihi - daha önce beyaz etiket WP eklentisinin Pro özelliğiydi ve API sadece aynı DB tablosunu okuyordu.

WP olmayan SDK kullanıcıları için bu, brand-config’in ek bir HTTP atlaması olmadan mümkün olmadığı anlamına geliyordu (ayrı bir yapılandırma servisi tutmak, bizimle senkronize etmek ve ardından whitelabel: true göndermek).

Şimdi alan, tüm 15 branding alanını içeren inline-nesne kabul ediyor. Tek bir istek = tam branding bağlamı = kişiselleştirilmiş 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, başlıkta logo, kapakta özel başlık, chart-SVG’de tema rengi aksanları ve alt bilgi kısmında iletişim bloğu ile render edilir.

Tüm alanlar opsiyonel - boş bırakılan alan, API anahtarı WP kullanıcısına bağlıysa DB yapılandırmasından değeri alır, aksi takdirde SDK istemcileri için sistem varsayılanlarından alır.

12 /v1/reports/* endpoint ailesi bu alanı aynı şekilde kabul eder: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Boolean modu hâlâ aktif ve değişmemiş:

• whitelabel: true: WP kullanıcısına bağlı olan DB yapılandırmasını okur (eski gibi)
• whitelabel: false veya alan eksikse: standart AstroWay branding
• whitelabel: {…}: inline nesne, yeni davranış

OpenAPI şeması için alan boolean | BrandingObject (birleşim tipi) oldu. Mevcut hiçbir istek bozulmaz.

API anahtarı WP kullanıcısına bağlıysa ve istemci inline nesne gönderirse - inline DB’ye öncelik verir. Özellikle:

1. Sistem varsayılanları (AstroWay branding)
2. whitelabel_configs içindeki DB yapılandırması (WP kullanıcısı bir tane sahipse)
3. İstek gövdesindeki inline nesne

Birleştirme - yüzeyel, anahtar-anahtar. Yani inline.themeColor = "#ff5500" DB değerini ezer, ancak inline.logoUrl boş bırakılırsa DB logosu korunur. Bu, temel branding DB’de tutulurken per-tenant ayarların inline ile gelmesi gereken SaaS senaryoları için kullanışlı.

İç eşleme: themeColor, applyBrandingPreferences çağrısından sonra primaryColor olur; fontPairing, Handlebars şablonunda CSS font-family yığına eşlenir (örneğin, serif-sans = font-family: 'Playfair Display', serif başlıklar için + 'Inter', sans-serif gövde için).

BrandingObject artık /v1/openapi.json içinde ayrı bir bileşen - bu, sonraki SDK sürümü (TS / Python / PHP) tipize edilmiş bir sınıf alacağı anlamına gelir:

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

SDK paketleri için yol haritaları ilgili staging depolarda (astroway-typescript-staging/ROADMAP.md vb.). Cron her 5-8 günde bir mikro sürüm yayınlar; tipize edilmiş BrandingObject en yakın sürümde olacak.

AstroWay PDF üretimini kendi ürününe entegre eden bir SaaS danışmanı için önceki yol şöyleydi:

1. Kendi tenants tablosunda branding_json alanıyla uğraşmak
2. Her rapor isteğinden önce: kullanıcının yapılandırmasını çekmek
3. WP eklentisi olmadan API’ya nasıl gönderileceğini anlamamak (önceden: hiçbir yol yoktu, SaaS kullanıcısı için whitelabel_configs girişi yapmamız gerekiyordu)
4. Ya da PDF post‑işlemeyi kendi renderimizle yapmak: bu ekstra altyapı

Şimdi yol:

1. Kendi branding_json’i saklamak
2. Her istek için whitelabel alanına inline göndermek

Daha az HTTP atlaması, hizmetler arasında DB senkronizasyonu yok, per‑request branding üzerinde tam kontrol.

Inline modu, PDF raporu bulunan tüm planlarda kullanılabilir - Indie ($19/ay) ile Business arasında. Free tier PDF sağlamaz (bu amaçlı - Free’te ücretsiz JSON, render yok). İstek kredi maliyeti değişmez - inline yapılandırma render üzerine ek credit maliyeti getirmez.

Tüm 12 endpoint için dokümantasyon inline modu örnekleriyle güncellendi. Bak: /docs/api/ → Reports.