Widgets Embebibles

Cread y gestionad widgets embebibles para vuestro sitio web. Un widget es un componente de interfaz listo para usar para una única funcionalidad astrológica: un formulario de carta natal, un calendario lunar, un selector de horóscopo diario. Lo configuráis en el panel o mediante esta API, y lo colocáis en cualquier página con una sola etiqueta de script.

Dos APIs, dos claves

La API de gestión (/api/widgets) crea y configura los widgets. Usa vuestra clave de API habitual.
La API de widget (/api/widget-api) es la que llama el SDK desde el navegador del visitante. Usa la clave propia del widget, que se puede publicar en una página sin riesgo porque está limitada a ese único widget.

¿Buscáis la guía sin código? Consultad Añadir Widgets a Vuestro Sitio Web.

Los tipos de widget que podéis crear dependen de los módulos activos en vuestra organización. GET /api/widgets/options lista los que tenéis disponibles.

Tipo	Descripción	Módulos requeridos
`natal`	Formulario de datos de nacimiento con carta, posiciones y aspectos	`module:natal`
`synastry`	Dos formularios de datos de nacimiento, carta de sinastría y aspectos cruzados	`module:natal`, `module:synastry`
`transit`	Datos de nacimiento más un momento de tránsito, carta de doble rueda	`module:natal`, `module:transits`
`composite`	Dos formularios de datos de nacimiento, carta compuesta	`module:natal`, `module:composite`
`moonphase`	Fase lunar actual con su iluminación	`module:moon`
`daily-horoscope`	Selector de signo con el horóscopo de hoy	`module:daily-report`
`numerology`	Formulario de nombre y fecha de nacimiento con los números principales	`module:numerology`
`compatibility`	Dos personas, puntuación de compatibilidad numerológica	`module:numerology`, `module:compatibility`
`moon-calendar`	Calendario mensual con fases, salida y puesta de la Luna	`module:moon`

Gestión de Widgets

Todos los endpoints de gestión son JSON:API y usan el tipo de recurso widget.

Listar Widgets

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

La respuesta de una creación es la única ocasión en la que se devuelve la clave de API completa del widget (apiKey). Guardadla, o regeneradla más adelante; el resto de respuestas solo incluyen 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_..." } }
        }
    }
}

PATCH acepta cualquier subconjunto de name, enabled, allowedDomains y customization. La personalización se sustituye por completo, así que enviad el objeto entero.

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"

Devuelve el widget con una apiKey nueva. Actualizad el código de incrustación de vuestro sitio con la clave nueva; el ID del widget no cambia.

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

Funcionalidades del Plan

Funcionalidad	Descripción
`canRemoveBranding`	`branding.showPoweredBy` puede ponerse a `false`
`canUseCustomLogo`	`branding.logoUrl` y `branding.companyName` pueden establecerse
`canUseCustomCss`	`customCss` se sirve al widget
`maxDomains`	Número máximo de `allowedDomains` por widget, o `"unlimited"`

Objeto de Personalización

Todos los campos son opcionales; lo que omitáis se completa con los valores predeterminados de abajo cuando se sirve el widget. Los colores son cadenas de color CSS y los tamaños son números en píxeles.

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

Campos de Personalización

Campo	Tipo	Descripción
`colors.*`	string	Diez colores CSS, aplicados como variables CSS en el widget
`fonts.family`	string	Valor CSS de `font-family`
`fonts.sizeBase` / `sizeHeading` / `sizeSmall`	number	Tamaños de fuente en píxeles
`fonts.weightNormal` / `weightBold`	number	Grosores de fuente
`borders.radius` / `width`	number	Píxeles; los usan los inputs, los botones y el diseño de tarjeta
`borders.style`	string	`solid`, `dashed`, `dotted` o `none`
`spacing.padding` / `margin`	number	Píxeles; los diseños `card` y `compact` usan `padding`
`shadows.preset`	string	`none`, `sm`, `md`, `lg` o `xl` (diseño de tarjeta)
`shadows.custom`	string \| null	Un `box-shadow` CSS que anula el preset
`layout.variant`	string	Ved Variantes de layout
`interaction.tooltipEnabled`	boolean	Tooltips al pasar el ratón sobre filas de planetas, filas de aspectos y días del calendario
`interaction.animationsEnabled`	boolean	Animaciones de entrada; siempre desactivadas para visitantes que prefieren menos movimiento
`interaction.clickThroughEnabled`	boolean	Convierte la carta renderizada en un enlace a `clickThroughUrl`
`interaction.clickThroughUrl`	string \| null	Se abre en una pestaña nueva
`chartSettings`	object	Un tema de carta parcial que se fusiona sobre el tema predeterminado: colores por signo, punto y aspecto, grosores de trazo, `showDegrees`, `showRetrograde`, etc.
`labels`	object	Sustituciones de cualquier clave de etiqueta; ved Idiomas y etiquetas
`language`	string	Uno de los 13 códigos de idioma admitidos
`branding.showPoweredBy`	boolean	Requiere `canRemoveBranding` para ponerlo a `false`
`branding.logoUrl` / `companyName`	string \| null	Requieren `canUseCustomLogo`
`customCss`	string \| null	Se inyecta en la página para el widget; requiere `canUseCustomCss`
`widgetOptions.showAspects` / `showPoints`	boolean	Muestra las tablas de aspectos y posiciones bajo una carta
`widgetOptions.showHouses`	boolean	Muestra los números de casa en la carta
`widgetOptions.chartSize`	string \| number	`small` (300), `medium` (450), `large` (600) o un ancho en píxeles
`widgetOptions.theme`	string	`light`, `dark`, `cosmic`, `custom` o `auto`
`numerologyOptions.*`	boolean	Qué números muestra el widget de numerología
`dailyHoroscopeOptions.autoRefresh`	boolean	Reservado
`moonCalendarOptions.*`	boolean	Qué detalles muestra cada día del calendario y qué fases se resaltan
`compatibilityOptions.*`	boolean	Anillo de puntuación, descripción y números de senda de vida

Variantes de layout

Valor	Descripción
`card`	Superficie con borde y con el radio, el relleno y la sombra configurados (predeterminado)
`compact`	La mitad de relleno y una tipografía algo menor, para barras laterales
`full`	De borde a borde, solo con relleno vertical
`minimal`	Sin marco alguno; lo hereda todo de la página

Temas

light, dark y cosmic son paletas fijas para superficies y bordes. auto usa la paleta clara y cambia a la oscura cuando el sistema del visitante prefiere el modo oscuro. custom no establece nada y se apoya en vuestros colors. En todos los temas, los diez colors que definís tienen prioridad sobre la paleta.

Idiomas y etiquetas

El SDK incluye etiquetas para en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja y zh-CN. Las variantes regionales recurren a su idioma base para todo lo que no sobrescriban. labels sustituye cadenas concretas por encima del idioma elegido, por ejemplo:

json

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

El idioma también se puede fijar por página: data-lang="de" en la etiqueta de script, o ?lang=de en la URL de la página; ambos tienen prioridad sobre el idioma guardado.

El SDK se sirve desde https://widgets.astroapi.cloud/sdk.js. La pestaña Embed del panel genera los dos fragmentos siguientes con vuestros IDs ya rellenados.

Inicialización automática

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>

Atributos opcionales: data-container="#my-element" para renderizar en un sitio distinto del div predeterminado, y data-lang="nl" para forzar el idioma.

Uso programático

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 se interpreta como hora local en timezone; el formulario la muestra exactamente tal como se indica.

API de la instancia

Miembro	Descripción
`id`, `type`	ID del widget y tipo de widget
`getResult()`	El último resultado, tanto si lo ha calculado el visitante como si lo ha hecho `calculate()`
`setBirthData(data)`	Datos de nacimiento que usa `calculate()`
`calculate()`	Ejecuta el cálculo desde script y muestra el resultado. Compatible con `natal`, `transit` (en el momento actual), `moonphase` y `moon-calendar` (mes actual); los demás tipos toman los datos del visitante y devuelven un rechazo con error
`destroy()`	Desmonta el widget

onResult se dispara con cada resultado que muestra el widget, en todos los tipos de widget. AstroWidget.version indica la build del SDK.

Dominios

allowedDomains restringe dónde funciona la clave de API del widget, comprobándola contra el Origin de la petición del navegador. Se admiten comodines de subdominio (*.example.com) y www. se trata como el dominio sin prefijo. Con la lista vacía la clave funciona en cualquier dominio, así que rellenadla antes de publicar el código de incrustación.

Estos son los endpoints que el SDK llama en nombre de un visitante. Se documentan para que podáis construir vuestro propio frontend contra un widget; el SDK es el cliente de referencia.

La autenticación es la clave de API del widget en X-Api-Key. La vista previa del panel usa una sesión en su lugar.

Endpoint	Cuerpo	Tipo de widget
`GET /api/widget-api/config/:widgetId`	—	cualquiera; público, devuelve `widgetType` y la `customization` ya fusionada
`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 }` (nombre y partes de la fecha de nacimiento)	`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=`	—	cualquiera; búsqueda de lugares para el formulario de datos de nacimiento

birthData, person1 y person2 en los widgets de cartas son { dateTime, latitude, longitude, timezone, placeName? }, con dateTime como hora local (1990-06-15T14:30:00) en timezone. Llamar a un endpoint desde un widget de otro tipo devuelve 400; un widget desactivado devuelve 403; una petición desde un dominio fuera de allowedDomains devuelve 403 DOMAIN_NOT_ALLOWED.

Próximos Pasos

Añadir Widgets a Vuestro Sitio Web — paso a paso para WordPress, Wix, Squarespace, Shopify y Webflow
Renderizado de Cartas — el objeto de tema que acepta chartSettings
Chatbot con IA — el chatbot tiene su propio widget embebible

Widgets Embebibles

Tipos de Widget

Gestión de Widgets

Listar Widgets

Obtener Widget

Crear Widget

Actualizar Widget

Eliminar Widget

Regenerar la clave de API del widget

Opciones de Widget Disponibles

Funcionalidades del Plan

Objeto de Personalización

Campos de Personalización

Variantes de layout

Temas

Idiomas y etiquetas

Incrustar un Widget

Inicialización automática

Uso programático

API de la instancia

Dominios

API de Widget

Próximos Pasos

Widgets Embebibles ​

Tipos de Widget ​

Gestión de Widgets ​

Listar Widgets ​

Obtener Widget ​

Crear Widget ​

Actualizar Widget ​

Eliminar Widget ​

Regenerar la clave de API del widget ​

Opciones de Widget Disponibles ​

Funcionalidades del Plan ​

Objeto de Personalización ​

Campos de Personalización ​

Variantes de layout ​

Temas ​

Idiomas y etiquetas ​

Incrustar un Widget ​

Inicialización automática ​

Uso programático ​

API de la instancia ​

Dominios ​

API de Widget ​

Próximos Pasos ​

Widgets Embebibles

Tipos de Widget

Gestión de Widgets

Listar Widgets

Obtener Widget

Crear Widget

Actualizar Widget

Eliminar Widget

Regenerar la clave de API del widget

Opciones de Widget Disponibles

Funcionalidades del Plan

Objeto de Personalización

Campos de Personalización

Variantes de layout

Temas

Idiomas y etiquetas

Incrustar un Widget

Inicialización automática

Uso programático

API de la instancia

Dominios

API de Widget

Próximos Pasos