White-label PDF WordPress 없이: inline branding 단일 필드로

До сьогодні whitelabel: true у наших report-ендпоінтах вимагало WordPress-акаунту з налаштованими ключами в whitelabel_configs. Це історично - раніше білий лейбл був Pro-фічею WP-плагіна, і API просто читав ту саму DB-таблицю.

Для SDK-користувачів без WP це означало: brand-config неможливий без додаткового HTTP-стрибка (тримати окремий конфіг-сервіс, синхронізувати з нашим, та потім посилати whitelabel: true).

Тепер поле приймає inline-об’єкт з усіма 15 полями брендингу. Один запит = повний контекст бренду = персоналізована 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는 헤더에 로고, 커버에 커스텀 제목, 차트 SVG에 해당 theme-color 강조, 그리고 푸터에 연락처 블록을 포함해서 렌더링돼.

모든 옵션 - 누락된 필드는 DB 설정값을 사용해 (API 키가 WP 사용자와 연결된 경우) 혹은 시스템 기본값을 사용해 (WP 없는 SDK 클라이언트의 경우).

12개의 엔드포인트 /v1/reports/*는 이 필드를 동일하게 받아: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Boolean 모드가 살아있고 변하지 않았어:

• whitelabel: true: 연결된 WP 사용자에 대한 DB 설정을 읽어 (예전과 동일)
• whitelabel: false 또는 필드가 없을 경우: 기본 AstroWay 브랜딩
• whitelabel: {…}: inline 객체, 새로운 동작

필드에 대한 OpenAPI 스키마가 boolean | BrandingObject (union type)로 바뀌었어. 기존 요청이 깨지지는 않을 거야.

When the API key is linked to a WP user AND the client sends an inline object – inline overrides DB. Specifically:

1. 시스템 기본값 (AstroWay 브랜딩)
2. whitelabel_configs가 있는 DB 설정 (WP 사용자가 가지고 있다면)
3. 요청 body에 있는 Inline 객체

Merge는 얕게, 키별로 수행돼. 즉 inline.themeColor = "#ff5500"은 DB 값을 덮어쓰고, inline.logoUrl이 누락되면 DB 로고를 유지해. 이는 기본 브랜딩이 DB에 있고, per-tenant 미세 조정이 inline으로 들어오는 SaaS 시나리오에 편리해.

내부 매핑: themeColor는 applyBrandingPreferences 호출 후 primaryColor가 되고, fontPairing은 Handlebars 템플릿에서 CSS font-family 스택으로 매핑돼 (예: serif-sans = 헤더용 font-family: 'Playfair Display', serif + 본문용 'Inter', sans-serif).

BrandingObject가 이제 /v1/openapi.json에서 별도 컴포넌트가 되었어 – 이는 다음 SDK 릴리즈(TS / Python / PHP)에서 타입이 지정된 클래스를 얻게 된다는 뜻이야:

// 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 패키지 로드맵은 해당 스테이징 레포(astroway-typescript-staging/ROADMAP.md 등)에 있어. Cron이 5-8일마다 마이너 릴리즈를 배포하고, 타입이 지정된 BrandingObject가 곧 포함될 거야.

예전에는 AstroWay PDF 생성 기능을 자체 제품에 통합하는 SaaS 소비자에게는 다음과 같은 과정이 필요했어:

1. tenants 테이블에 branding_json 필드를 만들기
2. 각 report 요청 전에 사용자의 설정을 가져오기
3. WP 플러그인 없이 API에 전달하는 방법을 몰라서 (예전엔 방법이 없었고, 우리에게 whitelabel_configs에 SaaS 사용자를 위한 엔트리를 만들라고 요청해야 했어)
4. 혹은 자체 렌더러로 PDF 후처리하기: 추가 인프라가 필요했어

이제는 이렇게 하면 돼:

1. branding_json을 자체적으로 저장
2. 각 요청에 whitelabel에 inline으로 전달

HTTP 호출이 줄고, 서비스 간 DB 동기화가 없어지고, 요청당 브랜딩을 완전히 제어할 수 있어.

Inline 모드는 PDF 리포트가 제공되는 모든 요금제에서 사용할 수 있어 – Indie ($19/월)부터 Business까지. Free 티어는 PDF를 제공하지 않아 (이는 의도된 것으로, Free에서는 무료 JSON만 제공되고 렌더링은 안 해). 요청당 크레딧 비용은 변하지 않아 – inline 설정이 렌더링에 추가 크레딧 비용을 발생시키지 않아.

12개 엔드포인트 모두에 대한 문서가 inline 모드 예시와 함께 업데이트됐어. /docs/api/ → Reports 를 확인해.