Gömülü Widget'lar

Web siteniz için gömülü widget'lar oluşturun ve yönetin. Widget, tek bir astroloji özelliği için hazır bir kullanıcı arayüzü bileşenidir: bir doğum haritası formu, bir ay takvimi, günlük burç yorumu için bir burç seçici. Widget'ı panelden veya bu API üzerinden yapılandırır ve tek bir script etiketiyle herhangi bir sayfaya yerleştirirsiniz.

İki API, iki anahtar

Yönetim API'si (/api/widgets) widget'ları oluşturur ve yapılandırır. Normal API anahtarınızı kullanır.
Widget API'si (/api/widget-api), SDK'nın ziyaretçinin tarayıcısından çağırdığı API'dir. Widget'ın kendi anahtarını kullanır; bu anahtar yalnızca o tek widget ile sınırlı olduğu için bir sayfaya konulması güvenlidir.

Kod gerektirmeyen rehberi mi arıyorsunuz? Bkz. Web Sitenize Widget Ekleme.

Hangi widget türlerini oluşturabileceğiniz, kuruluşunuzdaki modüllere bağlıdır. GET /api/widgets/options size açık olanları listeler.

Tür	Açıklama	Gerekli modüller
`natal`	Harita, konumlar ve açılarla birlikte doğum verisi formu	`module:natal`
`synastry`	İki doğum verisi formu, sinastri haritası ve çapraz açılar	`module:natal`, `module:synastry`
`transit`	Doğum verisi ve bir geçiş anı, çift çemberli harita	`module:natal`, `module:transits`
`composite`	İki doğum verisi formu, kompozit harita	`module:natal`, `module:composite`
`moonphase`	Aydınlanma oranıyla birlikte güncel ay evresi	`module:moon`
`daily-horoscope`	Bugünün burç yorumuyla birlikte burç seçici	`module:daily-report`
`numerology`	Ad ve doğum tarihi formu ile temel sayılar	`module:numerology`
`compatibility`	İki kişi, numeroloji uyum puanı	`module:numerology`, `module:compatibility`
`moon-calendar`	Evreler, ay doğuşu ve ay batışıyla aylık takvim	`module:moon`

Tüm yönetim uç noktaları JSON:API biçimindedir ve widget kaynak türünü kullanır.

bash

curl "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key"

bash

curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

bash

curl -X POST "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "attributes": {
        "name": "My Natal Chart Widget",
        "widgetType": "natal",
        "allowedDomains": ["example.com", "www.example.com"],
        "customization": {
          "language": "en",
          "layout": { "variant": "card" },
          "colors": {
            "primary": "#5b2d8e",
            "background": "#ffffff",
            "text": "#1a1a1a"
          },
          "widgetOptions": {
            "showAspects": true,
            "showPoints": true,
            "showHouses": true,
            "chartSize": "medium",
            "theme": "auto"
          }
        }
      }
    }
  }'

Oluşturma yanıtı, tam widget API anahtarının (apiKey) döndürüldüğü tek yerdir. Anahtarı saklayın veya daha sonra yeniden oluşturun; diğer tüm yanıtlar yalnızca apiKeyPrefix içerir.

json

{
    "data": {
        "type": "widget",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "customization": { "...": "as sent, merged with defaults when served" },
            "allowedDomains": ["example.com", "www.example.com"],
            "enabled": true,
            "createdAt": "2026-06-15T12:00:00.000Z",
            "updatedAt": "2026-06-15T12:00:00.000Z",
            "apiKey": "wk_live_...",
            "apiKeyPrefix": "wk_live_abc1"
        },
        "relationships": {
            "organization": { "data": { "type": "organization", "id": "org_..." } }
        }
    }
}

PATCH, name, enabled, allowedDomains ve customization alanlarının herhangi bir alt kümesini kabul eder. Özelleştirme bir bütün olarak değiştirilir, bu nedenle nesnenin tamamını gönderin.

bash

curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "id": "wgt_abc123",
      "attributes": {
        "name": "Updated Widget Name",
        "customization": { "language": "nl" }
      }
    }
  }'

bash

curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

bash

curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
  -H "X-Api-Key: your-api-key"

Widget'ı yeni bir apiKey ile döndürür. Sitenizdeki gömme kodunu yeni anahtarla güncelleyin; widget ID'si aynı kalır.

bash

curl "https://api.astroapi.cloud/api/widgets/options" \
  -H "X-Api-Key: your-api-key"

json

{
    "data": {
        "type": "widget-options",
        "id": "org_...",
        "attributes": {
            "plan": "Gold",
            "organizationModules": ["module:natal", "module:moon"],
            "availableWidgetTypes": ["natal", "moonphase", "moon-calendar"],
            "features": {
                "canRemoveBranding": false,
                "canUseCustomLogo": false,
                "canUseCustomCss": false,
                "maxDomains": 5
            },
            "allWidgetTypes": [
                {
                    "id": "natal",
                    "name": "Natal Chart",
                    "requiredModules": ["module:natal"],
                    "displayOptions": { "showChartSize": true, "showAspects": true, "showPoints": true }
                }
            ]
        }
    }
}

Plan Özellikleri

Özellik	Açıklama
`canRemoveBranding`	`branding.showPoweredBy` değeri `false` yapılabilir
`canUseCustomLogo`	`branding.logoUrl` ve `branding.companyName` ayarlanabilir
`canUseCustomCss`	`customCss` widget'a gönderilir
`maxDomains`	Widget başına en fazla `allowedDomains` sayısı veya `"unlimited"`

Özelleştirme Nesnesi

Her alan isteğe bağlıdır; belirtmediğiniz alanlar, widget sunulurken aşağıdaki varsayılan değerlerle doldurulur. Renkler CSS renk dizeleridir, boyutlar piksel cinsinden sayılardır.

json

{
    "colors": {
        "primary": "#6366f1",
        "secondary": "#8b5cf6",
        "background": "#ffffff",
        "surface": "#f8fafc",
        "text": "#1e293b",
        "textSecondary": "#64748b",
        "border": "#e2e8f0",
        "error": "#ef4444",
        "success": "#22c55e",
        "accent": "#f59e0b"
    },
    "fonts": {
        "family": "Inter, system-ui, sans-serif",
        "sizeBase": 16,
        "sizeHeading": 24,
        "sizeSmall": 12,
        "weightNormal": 400,
        "weightBold": 600
    },
    "borders": { "radius": 8, "width": 1, "style": "solid" },
    "spacing": { "padding": 16, "margin": 16 },
    "shadows": { "preset": "sm", "custom": null },
    "layout": { "variant": "card" },
    "interaction": {
        "tooltipEnabled": true,
        "animationsEnabled": true,
        "clickThroughEnabled": false,
        "clickThroughUrl": null
    },
    "chartSettings": {},
    "labels": {},
    "language": "en",
    "branding": { "showPoweredBy": true, "logoUrl": null, "companyName": null },
    "customCss": null,
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": "medium",
        "theme": "light"
    },
    "numerologyOptions": {
        "showLifePath": true,
        "showExpression": true,
        "showSoulUrge": true,
        "showPersonality": true,
        "showBirthday": true,
        "showPersonalCycles": true
    },
    "dailyHoroscopeOptions": { "autoRefresh": false },
    "moonCalendarOptions": {
        "showMoonrise": true,
        "showMoonset": true,
        "showIllumination": true,
        "showPhaseEmoji": true,
        "highlightFullMoon": true,
        "highlightNewMoon": true
    },
    "compatibilityOptions": {
        "showScore": true,
        "showDescription": true,
        "showLifePaths": true
    }
}

Özelleştirme Alanları

Alan	Tür	Açıklama
`colors.*`	string	Widget'a CSS değişkenleri olarak uygulanan on CSS rengi
`fonts.family`	string	CSS `font-family` değeri
`fonts.sizeBase` / `sizeHeading` / `sizeSmall`	number	Piksel cinsinden yazı tipi boyutları
`fonts.weightNormal` / `weightBold`	number	Yazı tipi kalınlıkları
`borders.radius` / `width`	number	Piksel; giriş alanları, düğmeler ve kart düzeni tarafından kullanılır
`borders.style`	string	`solid`, `dashed`, `dotted` veya `none`
`spacing.padding` / `margin`	number	Piksel; `card` ve `compact` düzenleri `padding` değerini kullanır
`shadows.preset`	string	`none`, `sm`, `md`, `lg` veya `xl` (kart düzeni)
`shadows.custom`	string \| null	Ön ayarı geçersiz kılan bir CSS `box-shadow`
`layout.variant`	string	Bkz. Düzen varyantları
`interaction.tooltipEnabled`	boolean	Gezegen satırlarında, açı satırlarında ve takvim günlerinde fareyle üzerine gelme ipuçları
`interaction.animationsEnabled`	boolean	Giriş animasyonları; azaltılmış hareketi tercih eden ziyaretçiler için her zaman kapalıdır
`interaction.clickThroughEnabled`	boolean	Oluşturulan haritayı `clickThroughUrl` adresine bir bağlantı yapar
`interaction.clickThroughUrl`	string \| null	Yeni sekmede açılır
`chartSettings`	object	Varsayılan harita temasının üzerine birleştirilen kısmi bir harita teması: burç, nokta ve açı başına renkler, çizgi kalınlıkları, `showDegrees`, `showRetrograde` ve benzeri
`labels`	object	Herhangi bir etiket anahtarı için geçersiz kılmalar; bkz. Diller ve etiketler
`language`	string	Desteklenen 13 dil kodundan biri
`branding.showPoweredBy`	boolean	`false` yapmak için `canRemoveBranding` gerekir
`branding.logoUrl` / `companyName`	string \| null	`canUseCustomLogo` gerektirir
`customCss`	string \| null	Widget için sayfaya enjekte edilir; `canUseCustomCss` gerektirir
`widgetOptions.showAspects` / `showPoints`	boolean	Bir haritanın altındaki açı ve konum tablolarını göster
`widgetOptions.showHouses`	boolean	Haritada ev numaralarını göster
`widgetOptions.chartSize`	string \| number	`small` (300), `medium` (450), `large` (600) veya piksel cinsinden bir genişlik
`widgetOptions.theme`	string	`light`, `dark`, `cosmic`, `custom` veya `auto`
`numerologyOptions.*`	boolean	Numeroloji widget'ının hangi sayıları göstereceği
`dailyHoroscopeOptions.autoRefresh`	boolean	Ayrılmış
`moonCalendarOptions.*`	boolean	Bir takvim gününün hangi ayrıntıları göstereceği ve hangi evrelerin vurgulanacağı
`compatibilityOptions.*`	boolean	Puan halkası, açıklama ve yaşam yolu sayıları

Düzen varyantları

Değer	Açıklama
`card`	Yapılandırılan yarıçap, dolgu ve gölgeye sahip kenarlıklı yüzey (varsayılan)
`compact`	Yarı yarıya dolgu ve biraz daha küçük yazı, kenar çubukları için
`full`	Kenardan kenara, yalnızca dikey dolgu
`minimal`	Hiç çerçeve yok; her şeyi sayfadan devralır

Temalar

light, dark ve cosmic, yüzeyler ve kenarlıklar için sabit paletlerdir. auto açık paleti kullanır ve ziyaretçinin sistemi koyu görünümü tercih ettiğinde koyu palete geçer. custom hiçbir şey ayarlamaz ve sizin colors değerlerinize dayanır. Her temada, belirlediğiniz on colors değeri paletin önüne geçer.

Diller ve etiketler

SDK; en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja ve zh-CN için etiketlerle birlikte gelir. Bölgesel varyantlar, geçersiz kılmadıkları her şey için temel dile geri döner. labels, seçilen dilin üzerine tek tek dizeleri geçersiz kılar, örneğin:

json

{ "language": "nl", "labels": { "calculateButton": "Bereken mijn horoscoop" } }

Dil sayfa başına da ayarlanabilir: script etiketinde data-lang="de" veya sayfa URL'sinde ?lang=de; her ikisi de kayıtlı dilin önüne geçer.

SDK, https://widgets.astroapi.cloud/sdk.js adresinden sunulur. Panelin Embed sekmesi, aşağıdaki iki parçacığı da kendi ID'leriniz doldurulmuş halde üretir.

Otomatik başlatma

html

<script
  src="https://widgets.astroapi.cloud/sdk.js"
  data-widget-id="wgt_abc123"
  data-api-key="your-widget-api-key"
  data-api-url="https://api.astroapi.cloud"
></script>
<div id="astro-widget-wgt_abc123"></div>

İsteğe bağlı öznitelikler: varsayılan div yerine başka bir yerde oluşturmak için data-container="#my-element" ve dili geçersiz kılmak için data-lang="nl".

Programatik

html

<script src="https://widgets.astroapi.cloud/sdk.js"></script>
<div id="my-widget"></div>
<script>
  AstroWidget.create({
    widgetId: "wgt_abc123",
    apiKey: "your-widget-api-key",
    apiBaseUrl: "https://api.astroapi.cloud",
    container: "#my-widget",
    language: "nl",
    defaultValues: {
      dateTime: "1990-06-15T14:30:00",
      latitude: 52.3676,
      longitude: 4.9041,
      timezone: "Europe/Amsterdam",
      placeName: "Amsterdam"
    },
    onLoad: () => console.log("Widget loaded"),
    onResult: (result) => console.log("Result", result),
    onError: (err) => console.error(err)
  }).then((widget) => {
    // widget.type, widget.getResult(), widget.setBirthData(), widget.calculate(), widget.destroy()
  });
</script>

defaultValues.dateTime, timezone içindeki yerel saat olarak yorumlanır; form onu tam olarak verildiği şekilde gösterir.

Örnek API'si

Üye	Açıklama
`id`, `type`	Widget ID'si ve widget türü
`getResult()`	Ziyaretçinin mi yoksa `calculate()` fonksiyonunun mu hesapladığından bağımsız olarak en son sonuç
`setBirthData(data)`	`calculate()` tarafından kullanılan doğum verileri
`calculate()`	Hesaplamayı script üzerinden çalıştırır ve sonucu gösterir. `natal`, `transit` (geçerli an için), `moonphase` ve `moon-calendar` (geçerli ay) türlerinde desteklenir; diğer türler girdilerini ziyaretçiden alır ve bir hatayla reddeder
`destroy()`	Widget'ı kaldırır

onResult, tüm widget türlerinde widget'ın gösterdiği her sonuç için tetiklenir. AstroWidget.version, SDK derlemesini bildirir.

Alan adları

allowedDomains, widget API anahtarının nerede çalışacağını sınırlar; tarayıcı isteğinin Origin değerine göre denetlenir. Alt alan adı joker karakterleri (*.example.com) desteklenir ve www. çıplak alan adı olarak değerlendirilir. Liste boşken anahtar herhangi bir alan adında çalışır, bu yüzden gömme kodunu yayınlamadan önce listeyi doldurun.

Bunlar, SDK'nın bir ziyaretçi adına çağırdığı uç noktalardır. Bir widget için kendi ön yüzünüzü geliştirebilesiniz diye listelenmişlerdir; SDK referans istemcidir.

Kimlik doğrulama, X-Api-Key başlığındaki widget API anahtarıyla yapılır. Panel önizlemesi bunun yerine bir oturum kullanır.

Uç nokta	Gövde	Widget türü
`GET /api/widget-api/config/:widgetId`	—	herhangi biri; herkese açık, `widgetType` ve birleştirilmiş `customization` döndürür
`POST /api/widget-api/natal/:widgetId`	`{ birthData }`	`natal`
`POST /api/widget-api/synastry/:widgetId`	`{ person1, person2 }`	`synastry`
`POST /api/widget-api/transit/:widgetId`	`{ birthData, transitDateTime, transitTimezone? }`	`transit`
`POST /api/widget-api/composite/:widgetId`	`{ person1, person2 }`	`composite`
`POST /api/widget-api/moonphase/:widgetId`	`{ date?, latitude? }`	`moonphase`
`POST /api/widget-api/daily-horoscope/:widgetId`	`{ zodiacSign, date? }`	`daily-horoscope`
`POST /api/widget-api/numerology/:widgetId`	`{ fullName, birthYear, birthMonth, birthDay }`	`numerology`
`POST /api/widget-api/compatibility/:widgetId`	`{ person1, person2 }` (ad ve doğum tarihi parçaları)	`compatibility`
`POST /api/widget-api/moon-calendar/:widgetId`	`{ year, month, latitude?, longitude?, timezone? }`	`moon-calendar`
`GET /api/widget-api/geocoding/search/:widgetId?q=&limit=&lang=`	—	herhangi biri; doğum verisi formu için yer arama

Harita widget'larındaki birthData, person1 ve person2 alanları { dateTime, latitude, longitude, timezone, placeName? } biçimindedir; burada dateTime, timezone içindeki yerel saattir (1990-06-15T14:30:00). Başka türden bir widget için bir uç noktayı çağırmak 400 döndürür; devre dışı bırakılmış bir widget 403 döndürür; allowedDomains dışındaki bir alan adından gelen istek 403 DOMAIN_NOT_ALLOWED döndürür.

Sonraki Adımlar

Web Sitenize Widget Ekleme — WordPress, Wix, Squarespace, Shopify ve Webflow için adım adım rehber
Harita Görselleştirme — chartSettings alanının kabul ettiği tema nesnesi
Yapay Zeka Sohbet Botu — sohbet botunun kendi gömülü widget'ı vardır

Gömülü Widget'lar

Widget Türleri

Widget Yönetimi

Widget'ları Listele

Widget Al

Widget Oluştur

Widget Güncelle

Widget Sil

Widget API anahtarını yeniden oluştur

Mevcut Widget Seçenekleri

Plan Özellikleri

Özelleştirme Nesnesi

Özelleştirme Alanları

Düzen varyantları

Temalar

Diller ve etiketler

Widget Yerleştirme

Otomatik başlatma

Programatik

Örnek API'si

Alan adları

Widget API'si

Sonraki Adımlar

Gömülü Widget'lar ​

Widget Türleri ​

Widget Yönetimi ​

Widget'ları Listele ​

Widget Al ​

Widget Oluştur ​

Widget Güncelle ​

Widget Sil ​

Widget API anahtarını yeniden oluştur ​

Mevcut Widget Seçenekleri ​

Plan Özellikleri ​

Özelleştirme Nesnesi ​

Özelleştirme Alanları ​

Düzen varyantları ​

Temalar ​

Diller ve etiketler ​

Widget Yerleştirme ​

Otomatik başlatma ​

Programatik ​

Örnek API'si ​

Alan adları ​

Widget API'si ​

Sonraki Adımlar ​

Gömülü Widget'lar

Widget Türleri

Widget Yönetimi

Widget'ları Listele

Widget Al

Widget Oluştur

Widget Güncelle

Widget Sil

Widget API anahtarını yeniden oluştur

Mevcut Widget Seçenekleri

Plan Özellikleri

Özelleştirme Nesnesi

Özelleştirme Alanları

Düzen varyantları

Temalar

Diller ve etiketler

Widget Yerleştirme

Otomatik başlatma

Programatik

Örnek API'si

Alan adları

Widget API'si

Sonraki Adımlar