White-label PDF tanpa WordPress: inline branding melalui satu bidang

Hingga hari ini, whitelabel: true di endpoint laporan kami memerlukan akun WordPress dengan kunci yang dikonfigurasi di whitelabel_configs. Ini historis - sebelumnya, whitelabel adalah fitur Pro dari plugin WP, dan API hanya membaca tabel DB yang sama.

Bagi pengguna SDK tanpa WP, ini berarti: konfigurasi merek tidak mungkin tanpa lompatan HTTP tambahan (mempertahankan layanan konfigurasi terpisah, menyinkronkannya dengan layanan kami, lalu mengirim whitelabel: true).

Sekarang, bidang ini menerima objek inline dengan semua 15 bidang branding. Satu permintaan = konteks merek lengkap = PDF yang dipersonalisasi.

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 dirender dengan logo di header, judul kustom di halaman sampul, aksen theme-color yang sesuai di SVG bagan, dan blok kontak di footer.

Semua bidang bersifat opsional - bidang yang dihilangkan akan mengambil nilai dari konfigurasi DB (jika kunci API terikat ke pengguna WP) atau dari default sistem (untuk klien SDK tanpa WP).

12 endpoint dari keluarga /v1/reports/* menerima bidang ini dengan cara yang sama: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Mode boolean masih aktif dan tidak berubah:

• whitelabel: true: membaca konfigurasi DB untuk pengguna WP yang terikat (seperti sebelumnya)
• whitelabel: false atau bidang tidak ada: branding AstroWay standar
• whitelabel: {…}: objek inline, perilaku baru

Skema OpenAPI untuk bidang ini sekarang adalah boolean | BrandingObject (tipe union). Tidak ada permintaan yang ada yang akan rusak.

Ketika kunci API terikat ke pengguna WP DAN klien mengirimkan objek inline - inline akan mengesampingkan DB. Secara spesifik:

1. Default sistem (branding AstroWay)
2. Konfigurasi DB dari whitelabel_configs (jika pengguna WP memilikinya)
3. Objek inline dari body permintaan

Penggabungan bersifat dangkal, kunci-per-kunci. Artinya, inline.themeColor = "#ff5500" akan menimpa nilai DB, tetapi inline.logoUrl yang dihilangkan akan mempertahankan logo DB. Ini nyaman untuk skenario SaaS di mana branding dasar berada di DB, dan penyesuaian per-tenant datang secara inline.

Pemetaan internal: themeColor menjadi primaryColor setelah memanggil applyBrandingPreferences, fontPairing dipetakan ke tumpukan CSS font-family di template Handlebars (misalnya, serif-sans = font-family: 'Playfair Display', serif untuk judul + 'Inter', sans-serif untuk isi).

BrandingObject sekarang menjadi komponen terpisah di /v1/openapi.json - ini berarti rilis SDK berikutnya (TS / Python / PHP) akan mendapatkan kelas yang ditipisasi:

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

Peta jalan paket SDK ada di repositori staging yang sesuai (astroway-typescript-staging/ROADMAP.md, dll.). Cron menerbitkan rilis minor setiap 5-8 hari; BrandingObject yang ditipisasi akan ada di rilis terdekat.

Sebelumnya, untuk konsumen SaaS yang mengintegrasikan pembuatan PDF AstroWay ke dalam produk mereka sendiri, jalannya adalah:

1. Mengelola tabel tenants dengan bidang branding_json di sisi kamu
2. Sebelum setiap permintaan laporan: mengambil konfigurasi pengguna kamu
3. Tidak tahu cara meneruskan ke API tanpa plugin WP (sebelumnya: tidak mungkin, kamu harus meminta kami membuat entri di whitelabel_configs untuk pengguna SaaS)
4. Atau melakukan post-processing PDF dengan render kamu sendiri: ini adalah infrastruktur tambahan

Sekarang, jalannya adalah:

1. Menyimpan branding_json di sisi kamu
2. Meneruskan secara inline di whitelabel untuk setiap permintaan

Lebih sedikit lompatan HTTP, nol sinkronisasi DB antar layanan, kontrol penuh atas branding per permintaan.

Mode inline tersedia di semua paket yang menyertakan laporan PDF - dari Indie ($19/bulan) hingga Business. Tingkat gratis tidak menyediakan PDF (ini disengaja - tingkat gratis menyediakan JSON gratis, tanpa rendering). Biaya kredit permintaan tidak berubah - konfigurasi inline tidak menambah biaya kredit di atas rendering.

Dokumentasi untuk semua 12 endpoint telah diperbarui dengan contoh mode inline. Lihat /docs/api/ → Reports.