White-label PDF không cần WordPress: branding inline qua một trường

Cho tới nay whitelabel: true trong các report-endpoint của chúng mình yêu cầu tài khoản WordPress có các key được cấu hình trong whitelabel_configs. Điều này mang tính lịch sử - trước đây white label là tính năng Pro của plugin WP, và API chỉ đọc cùng một bảng DB.

Đối với người dùng SDK không có WP, điều này có nghĩa là: brand-config không thể thực hiện được mà không có một bước HTTP bổ sung (giữ một service config riêng, đồng bộ với của chúng mình, rồi mới gửi whitelabel: true).

Bây giờ trường này nhận inline-đối tượng với tất cả 15 trường branding. Một request = ngữ cảnh thương hiệu đầy đủ = PDF cá nhân hoá.

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 được render với logo ở header, tiêu đề tùy chỉnh trên cover, các accent theme-color phù hợp trong chart-SVG, và khối liên hệ ở footer.

Tất cả tùy chọn - trường bị bỏ qua sẽ lấy giá trị từ DB-config (nếu API-key được gắn với người dùng WP) hoặc từ các default hệ thống (đối với khách hàng SDK không có WP).

12 endpoint trong họ /v1/reports/* nhận trường này giống nhau: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Chế độ Boolean vẫn hoạt động và không thay đổi:

• whitelabel: true: đọc DB-config cho người dùng WP được gắn (như trước)
• whitelabel: false hoặc trường không có: branding tiêu chuẩn của AstroWay
• whitelabel: {…}: inline-đối tượng, hành vi mới

Schema OpenAPI cho trường này đã trở thành boolean | BrandingObject (union type). Không có request nào hiện có sẽ bị phá vỡ.

Khi API-key được gắn với người dùng WP VÀ client gửi inline-đối tượng - inline sẽ ưu tiên hơn DB. Cụ thể:

1. Default hệ thống (branding AstroWay)
2. DB-config với whitelabel_configs (nếu người dùng WP có)
3. Inline-đối tượng từ body request

Merge - nông, key-by-key. Nghĩa là inline.themeColor = "#ff5500" sẽ ghi đè giá trị DB, nhưng nếu inline.logoUrl bị bỏ qua thì sẽ giữ logo DB. Điều này tiện cho các kịch bản SaaS nơi branding cơ bản nằm trong DB, và per-tenant fine‑tuning đến inline.

Mapping nội bộ: themeColor trở thành primaryColor sau khi gọi applyBrandingPreferences, fontPairing được map sang stack CSS font-family trong template Handlebars (ví dụ, serif-sans = font-family: 'Playfair Display', serif cho tiêu đề + 'Inter', sans-serif cho body).

BrandingObject bây giờ là một component riêng trong /v1/openapi.json - điều này có nghĩa là bản phát hành SDK tiếp theo (TS / Python / PHP) sẽ nhận được lớp được kiểu hoá:

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

Lộ trình SDK packages - trong các repo staging tương ứng (astroway-typescript-staging/ROADMAP.md, v.v.). Cron phát hành các bản minor mỗi 5‑8 ngày; BrandingObject đã được kiểu hoá sẽ có trong bản sắp tới.

Trước đây, đối với consumer SaaS muốn tích hợp việc tạo PDF của AstroWay vào sản phẩm của mình, quy trình là:

1. Tự quản lý bảng tenants với trường branding_json
2. Trước mỗi request report: lấy config của người dùng
3. Không biết cách truyền vào API mà không có plugin WP (trước đây: không thể, phải yêu cầu chúng mình tạo entry trong whitelabel_configs cho người dùng SaaS)
4. Hoặc tự làm post‑processing PDF bằng renderer của mình: đây là hạ tầng bổ sung

Bây giờ quy trình:

1. Lưu branding_json ở phía mình
2. Gửi inline trong whitelabel cho mỗi request

Ít bước HTTP hơn, không đồng bộ DB giữa các service, kiểm soát branding per‑request hoàn toàn.

Chế độ inline có sẵn trên mọi gói có PDF report - từ Indie ($19/tháng) tới Business. Gói Free không cung cấp PDF (đây là cố ý - Free chỉ có JSON miễn phí, không render). Chi phí credit cho request không thay đổi - config inline không tăng credit-cost trên render.

Tài liệu cho tất cả 12 endpoint đã được cập nhật với ví dụ chế độ inline. Xem /docs/api/ → Reports