White-label PDF sin WordPress: branding inline a través de un solo campo

Hasta hoy whitelabel: true en nuestros endpoints de report requería una cuenta de WordPress con claves configuradas en whitelabel_configs. Esto es histórico: anteriormente el white label era una función Pro del plugin de WP, y la API simplemente leía esa misma tabla de la base de datos.

Para los usuarios del SDK sin WP esto significaba: la configuración de marca era imposible sin un salto HTTP adicional (tener un servicio de configuración separado, sincronizarlo con el nuestro y luego enviar whitelabel: true).

Ahora el campo acepta un objeto inline con los 15 campos de branding. Un request = contexto completo de marca = PDF personalizada.

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

El PDF se renderiza con el logo en el encabezado, un título personalizado en la portada, acentos de theme-color correspondientes en el SVG del gráfico y un bloque de contactos en el pie de página.

Todos opcionales - el campo omitido toma el valor de la configuración de la DB (si la clave de API está vinculada a un usuario de WP) o de los valores predeterminados del sistema (para clientes del SDK sin WP).

12 endpoints de la familia /v1/reports/* aceptan este campo de la misma manera: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

El modo booleano sigue vigente y no ha cambiado:

• whitelabel: true: lee la configuración de la DB para el usuario de WP vinculado (como antes)
• whitelabel: false o el campo ausente: branding estándar de AstroWay
• whitelabel: {…}: objeto inline, nuevo comportamiento

El esquema OpenAPI para el campo se convirtió en boolean | BrandingObject (tipo unión). Ninguna solicitud existente se romperá.

Cuando la clave de API está vinculada a un usuario de WP y el cliente envía un objeto inline, el inline tiene prioridad sobre la DB. Específicamente:

1. Valores predeterminados del sistema (branding de AstroWay)
2. Configuración de la DB desde whitelabel_configs (si el usuario de WP tiene uno)
3. Objeto inline del cuerpo de la solicitud

La fusión es superficial, clave por clave. Es decir, inline.themeColor = "#ff5500" sobrescribirá el valor de la DB, pero si inline.logoUrl está ausente, se mantendrá el logo de la DB. Esto es útil para escenarios SaaS donde el branding básico reside en la DB y el ajuste fino por tenant llega inline.

El mapeo interno: themeColor se convierte en primaryColor después de llamar a applyBrandingPreferences, fontPairing se mapea a la pila CSS font-family en la plantilla Handlebars (por ejemplo, serif-sans = font-family: 'Playfair Display', serif para encabezados + 'Inter', sans-serif para el cuerpo).

BrandingObject ahora es un componente separado en /v1/openapi.json - esto significa que la próxima versión del SDK (TS / Python / PHP) recibirá una clase tipada:

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

Los roadmaps de los paquetes SDK están en los repositorios de staging correspondientes (astroway-typescript-staging/ROADMAP.md, etc.). Cron publica lanzamientos menores cada 5-8 días; el BrandingObject tipado estará en la próxima versión.

Antes, para un consumidor SaaS que integra la generación de PDF de AstroWay en su propio producto, el flujo era:

1. Molestarse manteniendo una tabla tenants con el campo branding_json
2. Antes de cada solicitud de report: obtener la configuración de su usuario
3. No entender cómo enviarlo a la API sin el plugin de WP (antes: imposible, había que pedírnosnos que creáramos una entrada en whitelabel_configs para el usuario SaaS)
4. O bien hacer postprocesamiento de PDF con su propio renderizado: eso es infra adicional

Ahora el flujo es:

1. Guardar branding_json en su lado
2. Enviar inline en whitelabel para cada solicitud

Menos saltos HTTP, cero sincronización de DB entre servicios, control total sobre el branding por solicitud.

El modo inline está disponible en todos los planes que incluyen reportes PDF, desde Indie ($19/міс) hasta Business. El nivel gratuito no incluye PDF (intencionalmente: en el plan gratuito hay JSON gratuito, sin renderizado). El costo en créditos de la solicitud no cambia: la configuración inline no agrega costo de crédito adicional sobre el renderizado.

La documentación de todos los 12 endpoints se ha actualizado con ejemplos del modo inline. Mira /docs/api/ → Reports.