White-label PDF بدون WordPress: inline branding عبر حقل واحد

حتى الآن whitelabel: true في نقاط تقريرنا (report-ендпоінтах) كان يتطلب حساب WordPress مع مفاتيح مكوّنة في whitelabel_configs. هذا تاريخي - سابقًا كان العلامة البيضاء ميزة Pro في إضافة WP، وكان API يقرأ ببساطة نفس جدول قاعدة البيانات.

لمستخدمي SDK بدون WP هذا يعني: لا يمكن الحصول على brand-config بدون قفزة HTTP إضافية (الحفاظ على خدمة تكوين منفصلة، مزامنتها مع خدمتنا، ثم إرسال whitelabel: true).

الآن الحقل يقبل inline-об’єкт مع جميع الـ 15 حقلًا للعلامة التجارية. طلب واحد = سياق كامل للعلامة = 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 المناسبة في مخطط SVG، وكتلة اتصالات في التذييل.

جميعها اختيارية - الحقل المفقود يأخذ القيمة من تكوين DB (إذا كان مفتاح API مرتبطًا بمستخدم WP) أو من القيم الافتراضية النظامية (لمستخدمي SDK بدون WP).

12 نقطة نهاية من عائلة /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 أو عدم وجود الحقل: العلامة التجارية القياسية لـ AstroWay
• whitelabel: {…}: كائن inline، سلوك جديد

مخطط OpenAPI لهذا الحقل أصبح boolean | BrandingObject (نوع اتحاد). لن يتعطل أي طلب موجود.

عندما يكون مفتاح API مرتبطًا بمستخدم WP و يرسل العميل كائن inline - الـ inline يتفوق على DB. بالتحديد:

1. القيم الافتراضية النظامية (علامة AstroWay)
2. تكوين DB من whitelabel_configs (إذا كان لدى مستخدم WP واحد)
3. كائن inline من جسم الطلب

الدمج - سطحي، مفتاحًا بمفتاح. أي أن inline.themeColor = "#ff5500" سيستبدل قيمة DB، لكن inline.logoUrl إذا كان مفقودًا سيترك شعار DB. هذا مفيد لسيناريوهات SaaS حيث العلامة الأساسية مخزنة في DB، وتخصيص per-tenant يأتي عبر inline.

التحويل الداخلي: themeColor يتحول إلى primaryColor بعد استدعاء applyBrandingPreferences، fontPairing يتحول إلى ستاك CSS font-family في قالب Handlebars (مثلاً، serif-sans = font-family: 'Playfair Display', serif للعناوين + 'Inter', sans-serif للجسم).

BrandingObject الآن مكوّن منفصل في /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 - في المستودعات التجريبية المناسبة (astroway-typescript-staging/ROADMAP.md، إلخ). Cron ينشر إصدارات صغرى كل 5-8 أيام؛ BrandingObject المكتوب بنوع سيكون قريبًا.

سابقًا لمستهلك SaaS الذي يدمج توليد PDF من AstroWay في منتجه الخاص، كان المسار:

1. إنشاء جدول tenants مع حقل branding_json في نظامك
2. قبل كل طلب تقرير: جلب تكوين المستخدم الخاص بك
3. عدم معرفة كيفية الإرسال إلى API بدون إضافة WP (سابقًا: لا يمكن، كان عليك طلب إدخال في whitelabel_configs لمستخدم SaaS)
4. أو القيام بمعالجة PDF بعديًا باستخدام محركك الخاص: هذه بنية تحتية إضافية

الآن المسار:

1. حفظ branding_json في نظامك
2. إرسال inline في whitelabel لكل طلب

قليل من قفزات HTTP، لا مزامنة DB بين الخدمات، تحكم كامل بالعلامة التجارية لكل طلب.

وضع inline متاح في جميع الخطط التي تحتوي على تقارير PDF - من Indie ($19/شهر) إلى Business. الطبقة المجانية لا توفر PDF (هذا مقصود - في Free تحصل على JSON مجاني، بدون توليد). تكلفة الائتمان للطلب لا تتغير - تكوين inline لا يضيف credit-cost فوق التوليد.

تم تحديث وثائق جميع الـ 12 نقطة النهاية بأمثلة وضع inline. راجع /docs/api/ → Reports