White-label PDF sans WordPress : inline branding via un seul champ

Jusqu’à présent whitelabel: true dans nos endpoints de report nécessitait un compte WordPress avec les clés configurées dans whitelabel_configs. C’est historique – auparavant le white label était une fonctionnalité Pro du plugin WP, et l’API lisait simplement la même table DB.

Pour les utilisateurs SDK sans WP, cela signifiait : la configuration de marque était impossible sans un saut HTTP supplémentaire (garder un service de config séparé, le synchroniser avec le nôtre, puis envoyer whitelabel: true).

Désormais le champ accepte un inline-objet avec les 15 champs de branding. Une requête = contexte complet de la marque = PDF personnalisé.

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

Le PDF est rendu avec le logo dans l’en-tête, un titre personnalisé sur la couverture, des accents theme-color appropriés dans le chart‑SVG, et un bloc de contacts dans le pied de page.

Tous les optionnels – un champ omis prend la valeur du config DB (si la clé API est liée à un utilisateur WP) ou des défauts système (pour les clients SDK sans WP).

12 endpoints de la famille /v1/reports/* acceptent ce champ de la même façon : natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Le mode booléen est toujours actif et n’a pas changé :

• whitelabel: true : lit la config DB pour l’utilisateur WP lié (comme avant)
• whitelabel: false ou champ absent : branding standard AstroWay
• whitelabel: {…} : inline‑objet, nouveau comportement

Le schéma OpenAPI pour le champ est devenu boolean | BrandingObject (type union). Aucune requête existante ne sera cassée.

Lorsque la clé API est liée à un utilisateur WP ET le client envoie un inline‑objet, l’inline l’emporte sur la DB. Concrètement :

1. Défauts système (branding AstroWay)
2. Config DB avec whitelabel_configs (si l’utilisateur WP en possède un)
3. Inline‑objet du corps de la requête

Fusion – superficielle, clé par clé. Ainsi inline.themeColor = "#ff5500" écrasera la valeur DB, mais inline.logoUrl omis laissera le logo DB. C’est pratique pour les scénarios SaaS où le branding de base réside dans la DB, et le fine‑tuning per‑tenant arrive inline.

Mappage interne : themeColor devient primaryColor après l’appel à applyBrandingPreferences, fontPairing est mappé sur la pile CSS font-family dans le template Handlebars (par ex., serif-sans = font-family: 'Playfair Display', serif pour les titres + 'Inter', sans-serif pour le corps).

BrandingObject est maintenant un composant séparé dans /v1/openapi.json – cela signifie que la prochaine version du SDK (TS / Python / PHP) recevra une classe typée :

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

Les feuilles de route des paquets SDK – dans les repos de staging correspondants (astroway-typescript-staging/ROADMAP.md, etc.). Cron publie des releases mineures tous les 5‑8 jours ; le BrandingObject typé sera dans la prochaine.

Auparavant, pour un consommateur SaaS qui intègre la génération PDF d’AstroWay dans son propre produit, le flux était :

1. Gérer chez toi une table tenants avec le champ branding_json
2. Avant chaque requête de rapport : récupérer la config de ton utilisateur
3. Ne pas savoir comment transmettre à l’API sans le plugin WP (avant : impossible, il fallait nous demander de créer une entrée dans whitelabel_configs pour l’utilisateur SaaS)
4. Ou bien faire le post‑processing PDF avec ton propre rendu : c’est une infra supplémentaire

Désormais le flux :

1. Stocker branding_json chez toi
2. Le transmettre inline dans whitelabel pour chaque requête

Moins de sauts HTTP, zéro synchronisation DB entre les services, contrôle total du branding par requête.

Le mode inline est disponible sur tous les plans où les rapports PDF sont proposés – de Indie ($19/mois) à Business. Le niveau gratuit ne fournit pas de PDF (c’est intentionnel – le Free donne uniquement du JSON gratuit, sans rendu). Le coût en crédits de la requête ne change pas – la config inline n’ajoute pas de credit‑cost au rendu.

La documentation pour les 12 endpoints a été mise à jour avec des exemples du mode inline. Voir /docs/api/ → Reports.