Встраиваемые виджеты
Создавайте и управляйте встраиваемыми виджетами для вашего сайта. Виджет — это готовый UI-компонент для одной астрологической функции: форма натальной карты, лунный календарь, выбор знака для ежедневного гороскопа. Вы настраиваете его в панели управления или через этот API и размещаете на любой странице одним тегом скрипта.
Два API, два ключа
- API управления (
/api/widgets) создаёт и настраивает виджеты. Он использует ваш обычный API-ключ. - API виджета (
/api/widget-api) — это то, что SDK вызывает из браузера посетителя. Он использует собственный ключ виджета, который безопасно размещать на странице, поскольку он ограничен этим одним виджетом.
Ищете руководство без написания кода? См. Добавление виджетов на ваш сайт.
Типы виджетов
Какие типы виджетов вы можете создавать, зависит от модулей, подключённых к вашей организации. GET /api/widgets/options возвращает список доступных вам типов.
| Тип | Описание | Необходимые модули |
|---|---|---|
natal | Форма данных рождения с картой, положениями и аспектами | module:natal |
synastry | Две формы данных рождения, карта синастрии и перекрёстные аспекты | module:natal, module:synastry |
transit | Данные рождения плюс момент транзита, двойная карта | module:natal, module:transits |
composite | Две формы данных рождения, композитная карта | module:natal, module:composite |
moonphase | Текущая фаза Луны с освещённостью | module:moon |
daily-horoscope | Выбор знака с гороскопом на сегодня | module:daily-report |
numerology | Форма с именем и датой рождения и основными числами | module:numerology |
compatibility | Два человека, нумерологическая оценка совместимости | module:numerology, module:compatibility |
moon-calendar | Месячный календарь с фазами, восходом и заходом Луны | module:moon |
Управление виджетами
Все эндпоинты управления работают в формате JSON:API и используют тип ресурса widget.
Список виджетов
curl "https://api.astroapi.cloud/api/widgets" \
-H "X-Api-Key: your-api-key"Получение виджета
curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
-H "X-Api-Key: your-api-key"Создание виджета
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"
}
}
}
}
}'Ответ на создание — единственный случай, когда возвращается полный API-ключ виджета (apiKey). Сохраните его или сгенерируйте новый позже; все остальные ответы содержат только apiKeyPrefix.
{
"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 и customization. Объект настройки заменяется целиком, поэтому отправляйте его полностью.
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" }
}
}
}'Удаление виджета
curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
-H "X-Api-Key: your-api-key"Перегенерация API-ключа виджета
curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
-H "X-Api-Key: your-api-key"Возвращает виджет с новым apiKey. Обновите код вставки на вашем сайте новым ключом; ID виджета остаётся прежним.
Доступные параметры виджетов
curl "https://api.astroapi.cloud/api/widgets/options" \
-H "X-Api-Key: your-api-key"{
"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 }
}
]
}
}
}Функции тарифного плана
| Функция | Описание |
|---|---|
canRemoveBranding | branding.showPoweredBy можно установить в false |
canUseCustomLogo | Можно задать branding.logoUrl и branding.companyName |
canUseCustomCss | customCss передаётся виджету |
maxDomains | Максимальное количество allowedDomains на виджет или "unlimited" |
Объект настройки
Все поля необязательны; то, что вы не указали, при отдаче виджета заполняется значениями по умолчанию, приведёнными ниже. Цвета — это CSS-строки цветов, размеры — числа в пикселях.
{
"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
}
}Поля настройки
| Поле | Тип | Описание |
|---|---|---|
colors.* | string | Десять CSS-цветов, применяемых к виджету как CSS-переменные |
fonts.family | string | Значение CSS font-family |
fonts.sizeBase / sizeHeading / sizeSmall | number | Размеры шрифта в пикселях |
fonts.weightNormal / weightBold | number | Начертания шрифта |
borders.radius / width | number | Пиксели; используются полями ввода, кнопками и карточной разметкой |
borders.style | string | solid, dashed, dotted или none |
spacing.padding / margin | number | Пиксели; разметки card и compact используют padding |
shadows.preset | string | none, sm, md, lg или xl (карточная разметка) |
shadows.custom | string | null | CSS box-shadow, переопределяющий пресет |
layout.variant | string | См. Варианты разметки |
interaction.tooltipEnabled | boolean | Всплывающие подсказки на строках планет, строках аспектов и днях календаря |
interaction.animationsEnabled | boolean | Анимации появления; всегда отключены для посетителей, предпочитающих уменьшенное движение |
interaction.clickThroughEnabled | boolean | Делает отрисованную карту ссылкой на clickThroughUrl |
interaction.clickThroughUrl | string | null | Открывается в новой вкладке |
chartSettings | object | Частичная тема карты, накладываемая на тему карты по умолчанию: цвета по знакам, точкам и аспектам, толщина линий, showDegrees, showRetrograde и так далее |
labels | object | Переопределения для любого ключа подписи; см. Языки и подписи |
language | string | Один из 13 поддерживаемых кодов языка |
branding.showPoweredBy | boolean | Для значения false требуется canRemoveBranding |
branding.logoUrl / companyName | string | null | Требуют canUseCustomLogo |
customCss | string | null | Внедряется на страницу для виджета; требует canUseCustomCss |
widgetOptions.showAspects / showPoints | boolean | Показывать таблицы аспектов и положений под картой |
widgetOptions.showHouses | boolean | Показывать номера домов на карте |
widgetOptions.chartSize | string | number | small (300), medium (450), large (600) или ширина в пикселях |
widgetOptions.theme | string | light, dark, cosmic, custom или auto |
numerologyOptions.* | boolean | Какие числа показывает нумерологический виджет |
dailyHoroscopeOptions.autoRefresh | boolean | Зарезервировано |
moonCalendarOptions.* | boolean | Какие детали показывает день календаря и какие фазы выделяются |
compatibilityOptions.* | boolean | Кольцо оценки, описание и числа жизненного пути |
Варианты разметки
| Значение | Описание |
|---|---|
card | Поверхность с границей, заданным радиусом, отступом и тенью (по умолчанию) |
compact | Вдвое меньший отступ и чуть меньший шрифт, для боковых панелей |
full | От края до края, только вертикальные отступы |
minimal | Совсем без рамки; всё наследуется от страницы |
Темы
light, dark и cosmic — это фиксированные палитры для поверхностей и границ. auto использует светлую палитру и переключается на тёмную, когда система посетителя предпочитает тёмное оформление. custom не задаёт ничего и опирается на ваши colors. В любой теме заданные вами десять colors имеют приоритет над палитрой.
Языки и подписи
SDK поставляется с подписями для en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja и zh-CN. Региональные варианты используют базовый язык для всего, что они не переопределяют. labels переопределяет отдельные строки поверх выбранного языка, например:
{ "language": "nl", "labels": { "calculateButton": "Bereken mijn horoscoop" } }Язык также можно задать для каждой страницы: data-lang="de" на теге скрипта или ?lang=de в URL страницы — оба имеют приоритет над сохранённым языком.
Встраивание виджета
SDK отдаётся с https://widgets.astroapi.cloud/sdk.js. Вкладка Embed в панели управления формирует оба приведённых ниже фрагмента с подставленными вашими ID.
Автоматическая инициализация
<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>Необязательные атрибуты: data-container="#my-element" — отрисовать не в стандартном div, а в другом месте, и data-lang="nl" — переопределить язык.
Программная инициализация
<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; форма показывает его ровно в том виде, в каком оно задано.
API экземпляра
| Член | Описание |
|---|---|
id, type | ID виджета и тип виджета |
getResult() | Последний результат, независимо от того, рассчитал ли его посетитель или calculate() |
setBirthData(data) | Данные рождения, используемые методом calculate() |
calculate() | Выполняет расчёт из скрипта и показывает результат. Поддерживается для natal, transit (на текущий момент), moonphase и moon-calendar (текущий месяц); остальные типы берут ввод от посетителя и завершаются с ошибкой |
destroy() | Демонтирует виджет |
onResult срабатывает для каждого результата, который показывает виджет, для всех типов виджетов. AstroWidget.version сообщает сборку SDK.
Домены
allowedDomains ограничивает, где работает API-ключ виджета; проверка идёт по заголовку Origin браузерного запроса. Поддерживаются подстановочные поддомены (*.example.com), а www. считается тем же доменом без префикса. При пустом списке ключ работает на любом домене, поэтому заполните его до публикации кода вставки.
API виджета
Это эндпоинты, которые SDK вызывает от имени посетителя. Они приведены здесь, чтобы вы могли построить собственный фронтенд поверх виджета; SDK служит эталонным клиентом.
Аутентификация — API-ключ виджета в заголовке X-Api-Key. Предпросмотр в панели управления вместо этого использует сессию.
| Эндпоинт | Тело | Тип виджета |
|---|---|---|
GET /api/widget-api/config/:widgetId | — | любой; публичный, возвращает widgetType и объединённый customization |
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 } (имя и части даты рождения) | 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= | — | любой; поиск места для формы данных рождения |
birthData, person1 и person2 для карточных виджетов имеют вид { dateTime, latitude, longitude, timezone, placeName? }, где dateTime — местное время (1990-06-15T14:30:00) в timezone. Вызов эндпоинта для виджета другого типа возвращает 400; отключённый виджет возвращает 403; запрос с домена вне allowedDomains возвращает 403 DOMAIN_NOT_ALLOWED.
Дальнейшие шаги
- Добавление виджетов на ваш сайт — пошаговые инструкции для WordPress, Wix, Squarespace, Shopify и Webflow
- Визуализация карт — объект темы, который принимает
chartSettings - AI-чатбот — у чатбота есть собственный встраиваемый виджет