AstroAPI

Appearance

Widget Có thể Nhúng ​

Tạo và quản lý các widget có thể nhúng cho website của bạn. Widget là một thành phần giao diện sẵn dùng cho một tính năng chiêm tinh: biểu mẫu lá số tử vi, lịch mặt trăng, bộ chọn cung cho tử vi hàng ngày. Bạn cấu hình widget trong bảng điều khiển hoặc qua API này, rồi đặt nó lên bất kỳ trang nào chỉ với một thẻ script.

Hai API, hai khóa

  • API quản lý (/api/widgets) tạo và cấu hình widget. Nó dùng API key thông thường của bạn.
  • API widget (/api/widget-api) là thứ SDK gọi từ trình duyệt của khách truy cập. Nó dùng khóa riêng của widget; khóa này an toàn để đặt trong trang vì chỉ có phạm vi trong đúng widget đó.

Bạn đang tìm hướng dẫn không cần lập trình? Xem Thêm Widget vào Website của Bạn.

Các Loại Widget ​

Bạn có thể tạo những loại widget nào là tùy thuộc vào các module của tổ chức bạn. GET /api/widgets/options liệt kê những loại có sẵn cho bạn.

LoạiMô tảModule bắt buộc
natalBiểu mẫu dữ liệu sinh kèm lá số, vị trí và góc chiếumodule:natal
synastryHai biểu mẫu dữ liệu sinh, lá số hợp tinh và góc chiếu chéomodule:natal, module:synastry
transitDữ liệu sinh cộng với một thời điểm quá độ, lá số hai vòngmodule:natal, module:transits
compositeHai biểu mẫu dữ liệu sinh, lá số kết hợpmodule:natal, module:composite
moonphasePha trăng hiện tại kèm độ chiếu sángmodule:moon
daily-horoscopeBộ chọn cung kèm tử vi hôm naymodule:daily-report
numerologyBiểu mẫu tên và ngày sinh kèm các con số cốt lõimodule:numerology
compatibilityHai người, điểm tương hợp theo số họcmodule:numerology, module:compatibility
moon-calendarLịch tháng kèm các pha, giờ trăng mọc và trăng lặnmodule:moon

Quản lý Widget ​

Tất cả endpoint quản lý đều theo JSON:API và dùng loại tài nguyên widget.

Liệt kê Widget ​

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

Lấy Widget ​

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

Tạo Widget ​

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

Phản hồi khi tạo là lần duy nhất API key đầy đủ của widget (apiKey) được trả về. Hãy lưu lại, hoặc tái tạo về sau; mọi phản hồi khác chỉ mang apiKeyPrefix.

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_..." } }
        }
    }
}

Cập nhật Widget ​

PATCH chấp nhận bất kỳ tập con nào của name, enabled, allowedDomains và customization. Phần tùy chỉnh được thay thế toàn bộ, vì vậy hãy gửi trọn đối tượng.

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

Xóa Widget ​

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

Tái tạo API key của widget ​

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

Trả về widget với apiKey mới. Hãy cập nhật mã nhúng trên site của bạn bằng khóa mới; ID widget vẫn giữ nguyên.

Các Tùy chọn Widget Có sẵn ​

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 }
                }
            ]
        }
    }
}

Tính năng Gói ​

Tính năngMô tả
canRemoveBrandingbranding.showPoweredBy có thể đặt thành false
canUseCustomLogoCó thể đặt branding.logoUrl và branding.companyName
canUseCustomCsscustomCss được gửi tới widget
maxDomainsSố lượng allowedDomains tối đa mỗi widget, hoặc "unlimited"

Đối tượng Tùy chỉnh ​

Mọi trường đều không bắt buộc; những gì bạn bỏ trống sẽ được điền từ các giá trị mặc định bên dưới khi widget được phục vụ. Màu sắc là chuỗi màu CSS, kích thước là số tính bằng pixel.

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

Các Trường Tùy chỉnh ​

TrườngKiểuMô tả
colors.*stringMười màu CSS, được áp dụng cho widget dưới dạng biến CSS
fonts.familystringGiá trị CSS font-family
fonts.sizeBase / sizeHeading / sizeSmallnumberKích thước phông chữ tính bằng pixel
fonts.weightNormal / weightBoldnumberĐộ đậm phông chữ
borders.radius / widthnumberPixel; dùng bởi các trường nhập, nút bấm và bố cục thẻ
borders.stylestringsolid, dashed, dotted hoặc none
spacing.padding / marginnumberPixel; bố cục card và compact dùng padding
shadows.presetstringnone, sm, md, lg hoặc xl (bố cục thẻ)
shadows.customstring | nullMột box-shadow CSS ghi đè giá trị dựng sẵn
layout.variantstringXem Các biến thể bố cục
interaction.tooltipEnabledbooleanTooltip khi di chuột trên hàng hành tinh, hàng góc chiếu và ngày trong lịch
interaction.animationsEnabledbooleanHiệu ứng xuất hiện; luôn tắt với khách truy cập ưu tiên giảm chuyển động
interaction.clickThroughEnabledbooleanBiến lá số đã vẽ thành một liên kết tới clickThroughUrl
interaction.clickThroughUrlstring | nullMở trong tab mới
chartSettingsobjectMột chủ đề lá số dạng một phần, hợp nhất lên trên chủ đề lá số mặc định: màu theo cung, điểm và góc chiếu, độ dày nét, showDegrees, showRetrograde và tương tự
labelsobjectGhi đè cho bất kỳ khóa nhãn nào; xem Ngôn ngữ và nhãn
languagestringMột trong 13 mã ngôn ngữ được hỗ trợ
branding.showPoweredBybooleanCần canRemoveBranding để đặt thành false
branding.logoUrl / companyNamestring | nullYêu cầu canUseCustomLogo
customCssstring | nullĐược chèn vào trang cho widget; yêu cầu canUseCustomCss
widgetOptions.showAspects / showPointsbooleanHiển thị bảng góc chiếu và vị trí bên dưới lá số
widgetOptions.showHousesbooleanHiển thị số cung nhà trên lá số
widgetOptions.chartSizestring | numbersmall (300), medium (450), large (600) hoặc một chiều rộng tính bằng pixel
widgetOptions.themestringlight, dark, cosmic, custom hoặc auto
numerologyOptions.*booleanWidget số học hiển thị những con số nào
dailyHoroscopeOptions.autoRefreshbooleanDành riêng cho tương lai
moonCalendarOptions.*booleanMột ngày trong lịch hiển thị chi tiết nào và những pha nào được làm nổi bật
compatibilityOptions.*booleanVòng điểm số, mô tả và các số đường đời

Các biến thể bố cục ​

Giá trịMô tả
cardBề mặt có viền với bán kính, khoảng đệm và bóng đã cấu hình (mặc định)
compactKhoảng đệm giảm một nửa và chữ nhỏ hơn đôi chút, dành cho sidebar
fullTràn viền, chỉ có khoảng đệm dọc
minimalHoàn toàn không có khung; kế thừa mọi thứ từ trang

Chủ đề ​

light, dark và cosmic là các bảng màu cố định cho bề mặt và viền. auto dùng bảng màu sáng và chuyển sang bảng màu tối khi hệ thống của khách truy cập ưu tiên giao diện tối. custom không đặt gì cả và dựa hoàn toàn vào colors của bạn. Trong mọi chủ đề, mười colors bạn đặt sẽ được ưu tiên hơn bảng màu.

Ngôn ngữ và nhãn ​

SDK đi kèm nhãn cho en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja và zh-CN. Các biến thể vùng sẽ quay về ngôn ngữ gốc cho bất kỳ nội dung nào chúng không ghi đè. labels ghi đè từng chuỗi riêng lẻ lên trên ngôn ngữ đã chọn, ví dụ:

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

Ngôn ngữ cũng có thể được đặt theo từng trang: data-lang="de" trên thẻ script, hoặc ?lang=de trong URL trang; cả hai đều được ưu tiên hơn ngôn ngữ đã lưu.

Nhúng Widget ​

SDK được phục vụ từ https://widgets.astroapi.cloud/sdk.js. Tab Embed trong bảng điều khiển tạo ra cả hai đoạn mã bên dưới với ID của bạn đã được điền sẵn.

Tự động khởi tạo ​

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>

Các thuộc tính tùy chọn: data-container="#my-element" để vẽ ở nơi khác thay vì div mặc định, và data-lang="nl" để ghi đè ngôn ngữ.

Khởi tạo bằng mã ​

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 được hiểu là giờ địa phương trong timezone; biểu mẫu hiển thị đúng như giá trị bạn đưa vào.

API của Đối tượng Widget ​

Thành phầnMô tả
id, typeID widget và loại widget
getResult()Kết quả mới nhất, dù do khách truy cập tính hay do calculate() tính
setBirthData(data)Dữ liệu sinh mà calculate() sử dụng
calculate()Chạy tính toán từ script và hiển thị kết quả. Được hỗ trợ cho natal, transit (tại thời điểm hiện tại), moonphase và moon-calendar (tháng hiện tại); các loại còn lại lấy dữ liệu nhập từ khách truy cập và sẽ trả về lỗi
destroy()Gỡ widget khỏi trang

onResult kích hoạt cho mọi kết quả mà widget hiển thị, với mọi loại widget. AstroWidget.version cho biết bản dựng của SDK.

Tên miền ​

allowedDomains giới hạn nơi API key của widget hoạt động, được kiểm tra dựa trên Origin của yêu cầu từ trình duyệt. Hỗ trợ ký tự đại diện cho tên miền phụ (*.example.com) và www. được xem như tên miền gốc. Với danh sách rỗng, khóa hoạt động trên mọi tên miền, vì vậy hãy điền danh sách trước khi bạn công bố mã nhúng.

API Widget ​

Đây là các endpoint mà SDK gọi thay mặt cho khách truy cập. Chúng được liệt kê để bạn có thể tự xây dựng giao diện riêng cho một widget; SDK là ứng dụng khách tham chiếu.

Xác thực bằng API key của widget trong X-Api-Key. Bản xem trước trong bảng điều khiển dùng phiên đăng nhập thay thế.

EndpointNội dungLoại widget
GET /api/widget-api/config/:widgetId—bất kỳ; công khai, trả về widgetType và customization đã hợp nhất
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 } (tên và các phần của ngày sinh)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=—bất kỳ; tìm kiếm địa điểm cho biểu mẫu dữ liệu sinh

birthData, person1 và person2 của các widget lá số có dạng { dateTime, latitude, longitude, timezone, placeName? }, trong đó dateTime là giờ địa phương (1990-06-15T14:30:00) theo timezone. Gọi một endpoint cho widget thuộc loại khác sẽ trả về 400; widget đã tắt trả về 403; yêu cầu từ tên miền ngoài allowedDomains trả về 403 DOMAIN_NOT_ALLOWED.

Các Bước Tiếp theo ​

AstroAPI Documentation

Copyright © 2026 AstroAPI