White-label PDF fără WordPress: inline branding printr-un singur câmp

Până acum whitelabel: true la endpoint-urile noastre de rapoarte cerea un cont WordPress cu cheile configurate în whitelabel_configs. Este istoric - anterior, eticheta albă era o funcție Pro a pluginului WP, iar API citea simplu aceeași tabelă DB.

Pentru utilizatorii SDK fără WP, acest lucru însemna: configurarea brand-ului nu era posibilă fără un suplimentar HTTP jump (țineţi un serviciu de configurare separat, sincronizaţi-l cu nostrul, apoi trimiteţi whitelabel: true).

Acum câmpul primește un obiect inline cu toate cele 15 câmpuri de branding. Un singur request = context complet de brand = PDF personalizată.

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-ul este renderat cu logo în antet, un titlu personalizat pe copertă, accentele corespunzătoare de theme-color în SVG-ul graficului și un bloc de contacte în subsol.

Toate sunt opționale - câmpul lipsă preia valoarea din configurarea DB (dacă cheia API este legată de un utilizator WP) sau din valorile implicite ale sistemului (pentru clienții SDK fără WP).

12 endpoint-uri din familia /v1/reports/* acceptă acest field la fel: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Modul boolean rămâne activ și neschimbat:

• whitelabel: true: citește configurarea DB pentru utilizatorul WP legat (ca și anterior)
• whitelabel: false sau lipsa câmpului: branding implicit AstroWay
• whitelabel: {…}: obiect inline, noul comportament

OpenAPI-schema pentru câmp a devenit boolean | BrandingObject (tip uniune). Niciun request existent nu se va rupta.

Când cheia API este legată de un utilizator WP și clientul trimite un obiect inline - inline are prioritate față de DB. Concret:

1. Valorile implicite ale sistemului (branding AstroWay)
2. Configurarea DB din whitelabel_configs (dacă utilizatorul WP are una)
3. Obiectul inline din corpul cererii

Fuzionare - superficială, cheie-cheie. Astfel inline.themeColor = "#ff5500" va suprascrie valoarea DB, dar inline.logoUrl lăsat gol va lăsa logo-ul DB. Este util pentru scenarii SaaS unde branding-ul de bază se află în DB, iar ajustările per-tenant vin inline.

Mapeare internă: themeColor devine primaryColor după apelul applyBrandingPreferences, fontPairing se mapează pe stac CSS font-family în șablonul Handlebars (de exemplu, serif-sans = font-family: 'Playfair Display', serif pentru anteturi + 'Inter', sans-serif pentru corp).

BrandingObject este acum un component separat în /v1/openapi.json - ceea ce înseamnă că următorul release al SDK-ului (TS / Python / PHP) va primi o clasă tipizată:

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

Hărțile de drum pentru pachetele SDK se găsesc în repo-urile de staging corespunzătoare (astroway-typescript-staging/ROADMAP.md, etc.). Cron publică release-uri minore la fiecare 5-8 zile; BrandingObject tipizat va fi în cea mai apropiată versiune.

Anterior, pentru un consultant SaaS care integrează generarea PDF-ului AstroWay în propriul său produs, calea era:

1. Țineţi la voi o tabelă tenants cu câmpul branding_json
2. Înainte de fiecare cerere de raport: preluţi configurarea utilizatorului tău
3. Nu înţelegeţi cum să trimiteţi în API fără pluginul WP (în trecut: niciodată, trebuia să ne solicitaţi să facem o intrare în whitelabel_configs pentru utilizatorul SaaS)
4. Sau să faceţi postprocesare PDF cu propriul vostru render: aceasta este o infrastructură suplimentară

Acum calea:

1. Stochează branding_json la tine
2. Trimită inline în whitelabel pentru fiecare cerere

Mai puţi sari HTTP, nulă sincronizare DB între servicii, control total asupra branding-ului per-cerere.

Modul inline este disponibil pe toate planurile care includ rapoarte PDF – de la Indie ($19/міс) până la Business. Nivelul gratuit nu oferă PDF (intenționat – în planul gratuit ai JSON gratuit, fără render). Costul în credite al cererii nu se schimbă – configurarea inline nu adaugă cost suplimentar în credite peste render.

Documentația pentru toate cele 12 endpoint-uri a fost actualizată cu exemple de modul inline. Vezi /docs/api/ → Reports.