White-label PDF senza WordPress: branding inline tramite un unico campo

Fino ad oggi, whitelabel: true nei nostri endpoint di report richiedeva un account WordPress con chiavi configurate in whitelabel_configs. Questo è storico: in precedenza, il white label era una funzionalità Pro del plugin WP, e l’API semplicemente leggeva la stessa tabella DB.

Per gli utenti SDK senza WP, questo significava: la configurazione del brand non era possibile senza un ulteriore salto HTTP (mantenere un servizio di configurazione separato, sincronizzarlo con il nostro e poi inviare whitelabel: true).

Ora il campo accetta un oggetto inline con tutti i 15 campi di branding. Una singola richiesta = contesto completo del brand = PDF personalizzato.

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"
    }
  }'

Il PDF viene renderizzato con il logo nell’intestazione, un titolo personalizzato sulla copertina, accenti di theme-color corrispondenti nei grafici SVG e un blocco di contatti nel piè di pagina.

Sono tutti opzionali: un campo omesso prende il valore dalla configurazione DB (se la chiave API è collegata a un utente WP) o dai valori predefiniti di sistema (per i client SDK senza WP).

12 endpoint della famiglia /v1/reports/* accettano questo campo allo stesso modo: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

La modalità booleana è attiva e non è cambiata:

• whitelabel: true: legge la configurazione DB per l’utente WP collegato (come prima)
• whitelabel: false o campo assente: branding AstroWay standard
• whitelabel: {…}: oggetto inline, nuovo comportamento

Lo schema OpenAPI per il campo è diventato boolean | BrandingObject (tipo unione). Nessuna richiesta esistente si romperà.

Quando la chiave API è collegata a un utente WP E il client invia un oggetto inline, l’inline prevale sul DB. Nello specifico:

1. Valori predefiniti di sistema (branding AstroWay)
2. Configurazione DB da whitelabel_configs (se l’utente WP ne ha una)
3. Oggetto inline dal corpo della richiesta

La fusione è superficiale, chiave per chiave. Ciò significa che inline.themeColor = "#ff5500" sovrascriverà il valore DB, ma inline.logoUrl omesso lascerà il logo DB. Questo è comodo per scenari SaaS in cui il branding di base risiede nel DB, e la personalizzazione per tenant arriva inline.

Mappatura interna: themeColor diventa primaryColor dopo la chiamata a applyBrandingPreferences, fontPairing viene mappato allo stack CSS font-family nel template Handlebars (ad esempio, serif-sans = font-family: 'Playfair Display', serif per i titoli + 'Inter', sans-serif per il corpo).

BrandingObject è ora un componente separato in /v1/openapi.json - ciò significa che la prossima release dell’SDK (TS / Python / PHP) riceverà una classe tipizzata:

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

Le roadmap dei pacchetti SDK si trovano nei rispettivi repository di staging (astroway-typescript-staging/ROADMAP.md, ecc.). Cron pubblica release minori ogni 5-8 giorni; il BrandingObject tipizzato sarà nella prossima.

In precedenza, per un consumatore SaaS che integrava la generazione di PDF di AstroWay nel proprio prodotto, il percorso era:

1. Dover gestire una tabella tenants con un campo branding_json
2. Prima di ogni richiesta di report: recuperare la configurazione del proprio utente
3. Non capire come passarlo all’API senza il plugin WP (prima: in nessun modo, dovevi chiederci di creare una voce in whitelabel_configs per l’utente SaaS)
4. Oppure eseguire la post-elaborazione del PDF con il proprio renderer: questa è un’infrastruttura aggiuntiva

Ora il percorso è:

1. Salvare branding_json localmente
2. Passare inline in whitelabel per ogni richiesta

Meno salti HTTP, zero sincronizzazione DB tra i servizi, controllo completo sul branding per richiesta.

La modalità inline è disponibile su tutti i piani tariffari che includono report PDF - da Indie ($19/mese) a Business. Il livello Free non fornisce PDF (questo è intenzionale - il Free offre JSON gratuito, senza rendering). Il costo in crediti della richiesta non cambia - la configurazione inline non aggiunge costi in crediti oltre al rendering.

La documentazione per tutti i 12 endpoint è stata aggiornata con esempi della modalità inline. Consulta /docs/api/ → Reports.