White-label PDF χωρίς WordPress: inline branding μέσω ενός πεδίου

Μέχρι σήμερα, το whitelabel: true στα report-endpoints μας απαιτούσε έναν λογαριασμό WordPress με διαμορφωμένα κλειδιά στο whitelabel_configs. Αυτό είναι ιστορικό – παλαιότερα το white label ήταν μια Pro-λειτουργία του WP-plugin, και το API απλώς διάβαζε τον ίδιο πίνακα DB.

Για τους χρήστες του SDK χωρίς WP, αυτό σήμαινε: η διαμόρφωση επωνυμίας ήταν αδύνατη χωρίς ένα επιπλέον HTTP-hop (να διατηρείς μια ξεχωριστή υπηρεσία διαμόρφωσης, να τη συγχρονίζεις με τη δική μας και μετά να στέλνεις whitelabel: true).

Τώρα το πεδίο δέχεται ένα inline-αντικείμενο με όλα τα 15 πεδία branding. Ένα αίτημα = πλήρες πλαίσιο επωνυμίας = εξατομικευμένο 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 αποδίδεται με λογότυπο στην κεφαλίδα, προσαρμοσμένο τίτλο στο εξώφυλλο, αντίστοιχες theme-color πινελιές στα chart-SVG και ένα μπλοκ επαφών στο υποσέλιδο.

Όλα είναι προαιρετικά – ένα πεδίο που παραλείπεται λαμβάνει την τιμή από τη διαμόρφωση DB (εάν το API-key είναι συνδεδεμένο με χρήστη WP) ή από τις προεπιλογές συστήματος (για πελάτες SDK χωρίς WP).

12 endpoints της οικογένειας /v1/reports/* δέχονται αυτό το πεδίο με τον ίδιο τρόπο: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Η Boolean-λειτουργία είναι ζωντανή και δεν έχει αλλάξει:

• whitelabel: true: διαβάζει τη διαμόρφωση DB για τον συνδεδεμένο χρήστη WP (όπως πριν)
• whitelabel: false ή το πεδίο απουσιάζει: τυπικό branding AstroWay
• whitelabel: {…}: inline-αντικείμενο, νέα συμπεριφορά

Το σχήμα OpenAPI για το πεδίο έγινε boolean | BrandingObject (union type). Κανένα υπάρχον αίτημα δεν θα χαλάσει.

Όταν το API-key είναι συνδεδεμένο με χρήστη WP ΚΑΙ ο πελάτης στέλνει ένα inline-αντικείμενο – το inline υπερισχύει του DB. Συγκεκριμένα:

1. Προεπιλογές συστήματος (branding AstroWay)
2. Διαμόρφωση DB από το whitelabel_configs (εάν ο χρήστης WP έχει μία)
3. Inline-αντικείμενο από το body του αιτήματος

Η συγχώνευση είναι shallow, key-by-key. Δηλαδή, το inline.themeColor = "#ff5500" θα αντικαταστήσει την τιμή DB, αλλά το inline.logoUrl που παραλείπεται θα αφήσει το λογότυπο DB. Αυτό είναι βολικό για σενάρια SaaS όπου το βασικό branding βρίσκεται στο DB, ενώ ο per-tenant συντονισμός έρχεται inline.

Εσωτερική αντιστοίχιση: το themeColor γίνεται primaryColor μετά την κλήση του applyBrandingPreferences, το fontPairing αντιστοιχίζεται στο CSS font-family stack στο Handlebars-template (για παράδειγμα, serif-sans = font-family: 'Playfair Display', serif για επικεφαλίδες + 'Inter', sans-serif για το σώμα).

Το BrandingObject είναι τώρα ένα ξεχωριστό component στο /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 βρίσκονται στα αντίστοιχα staging-repos (astroway-typescript-staging/ROADMAP.md, κ.λπ.). Το Cron δημοσιεύει μικρές εκδόσεις κάθε 5-8 ημέρες· το τυποποιημένο BrandingObject θα είναι στην επόμενη.

Προηγουμένως, για έναν SaaS-καταναλωτή που ενσωματώνει τη δημιουργία PDF του AstroWay στο δικό του προϊόν, η διαδρομή ήταν:

1. Να δημιουργήσεις έναν πίνακα tenants με ένα πεδίο branding_json
2. Πριν από κάθε αίτημα αναφοράς: να ανακτήσεις τη διαμόρφωση του χρήστη σου
3. Να μην καταλάβεις πώς να το μεταβιβάσεις στο API χωρίς το WP-plugin (πριν: καθόλου, έπρεπε να μας ζητήσεις να δημιουργήσουμε μια καταχώριση στο whitelabel_configs για τον χρήστη SaaS)
4. Ή να κάνεις PDF-μετα-επεξεργασία με τον δικό σου renderer: αυτή είναι επιπλέον υποδομή

Τώρα η διαδρομή είναι:

1. Να αποθηκεύεις το branding_json σε εσένα
2. Να μεταβιβάζεις inline στο whitelabel για κάθε αίτημα

Λιγότερα HTTP-hops, μηδενικός συγχρονισμός DB μεταξύ υπηρεσιών, πλήρης έλεγχος του branding ανά αίτημα.

Η inline-λειτουργία είναι διαθέσιμη σε όλα τα πακέτα όπου υπάρχουν PDF-reports – από το Indie (19$/μήνα) έως το Business. Το Free tier δεν παρέχει PDF (αυτό είναι σκόπιμο – στο Free υπάρχει δωρεάν JSON, χωρίς rendering). Το κόστος πίστωσης του αιτήματος δεν αλλάζει – η inline-διαμόρφωση δεν προσθέτει credit-cost επιπλέον του rendering.

Η τεκμηρίωση για όλα τα 12 endpoints έχει ενημερωθεί με παραδείγματα inline-λειτουργίας. Δες /docs/api/ → Reports.