White-label PDF sem WordPress: branding inline através de um único campo

Até hoje whitelabel: true nos nossos report-endpoints exigia uma conta WordPress com chaves configuradas em whitelabel_configs. Isto é histórico – antes o white label era uma funcionalidade Pro do plugin WP, e a API simplesmente lia a mesma tabela DB.

Para utilizadores do SDK sem WP isso significava: brand-config impossível sem um salto HTTP adicional (manter um serviço de configuração separado, sincronizar com o nosso, e depois enviar whitelabel: true).

Agora o campo aceita um inline-objeto com todos os 15 campos de branding. Um pedido = contexto completo da marca = PDF personalizado.

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

O PDF é renderizado com logótipo no cabeçalho, título personalizado na capa, acentos theme-color correspondentes no chart-SVG, e bloco de contactos no rodapé.

Todos os opcionais – um campo omitido assume o valor da configuração DB (se a chave API estiver ligada a um utilizador WP) ou dos defaults do sistema (para clientes SDK sem WP).

12 endpoints da família /v1/reports/* aceitam este campo da mesma forma: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Modo booleano continua ativo e não mudou:

• whitelabel: true: lê a configuração DB para o utilizador WP associado (como antes)
• whitelabel: false ou campo ausente: branding padrão AstroWay
• whitelabel: {…}: inline-objeto, novo comportamento

O esquema OpenAPI para o campo passou a ser boolean | BrandingObject (tipo união). Nenhum pedido existente irá quebrar.

Quando uma chave API está ligada a um utilizador WP E o cliente envia um inline‑objeto – o inline prevalece sobre a DB. Concretamente:

1. Defaults do sistema (branding AstroWay)
2. Configuração DB com whitelabel_configs (se o utilizador WP tiver uma)
3. Inline‑objeto no corpo do pedido

Merge – shallow, key‑by‑key. Ou seja, inline.themeColor = "#ff5500" sobrescreve o valor DB, mas inline.logoUrl omitido mantém o logótipo DB. Isto é útil para cenários SaaS onde o branding base está na DB, e o ajuste per‑tenant vem inline.

Mapeamento interno: themeColor torna‑se primaryColor após a chamada applyBrandingPreferences, fontPairing mapeia para a pilha CSS font-family no template Handlebars (por exemplo, serif-sans = font-family: 'Playfair Display', serif para cabeçalhos + 'Inter', sans-serif para o corpo).

BrandingObject agora é um componente separado em /v1/openapi.json – isso significa que a próxima versão do SDK (TS / Python / PHP) receberá uma classe 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
  },
});

Roadmaps dos pacotes SDK – nos repositórios de staging correspondentes (astroway-typescript-staging/ROADMAP.md, etc.). O Cron publica releases menores a cada 5‑8 dias; o BrandingObject tipado chegará em breve.

Antes, para um consumidor SaaS que integrava a geração de PDF AstroWay no seu próprio produto, o caminho era:

1. Manter a tua própria tabela tenants com o campo branding_json
2. Antes de cada pedido de report: buscar a configuração do teu utilizador
3. Não perceber como passar para a API sem o plugin WP (antes: impossível, era preciso pedir‑nos para criar uma entrada em whitelabel_configs para o utilizador SaaS)
4. Ou então fazer pós‑processamento do PDF com o teu próprio renderizador: infra adicional

Agora o caminho:

1. Guardar branding_json localmente
2. Passar inline em whitelabel em cada pedido

Menos saltos HTTP, zero sincronização DB entre serviços, controlo total do branding por request.

O modo inline está disponível em todos os planos que incluem relatórios PDF – desde Indie ($19/mês) até Business. O tier Free não oferece PDF (intencional – no Free há JSON gratuito, sem renderização). O custo de crédito do pedido não muda – a configuração inline não acrescenta credit-cost ao render.

A documentação para todos os 12 endpoints foi atualizada com exemplos do modo inline. Vê /docs/api/ → Reports.