Widgets Embebibles

Cread y gestionad widgets embebibles para vuestro sitio web. Los widgets proporcionan componentes de interfaz de usuario listos para usar con funcionalidades astrológicas que pueden integrarse en cualquier página web con una sola etiqueta de script.

Módulo Requerido

Todos los endpoints de widgets requieren el módulo module:embeddable-widgets activado para vuestra organización.

---

Tipos de Widget

Los siguientes tipos de widget están disponibles según vuestros módulos activos:

Tipo	Descripción	Módulo Requerido
natal	Carta natal interactiva	natal:calc
synastry	Carta de comparación de sinastría	synastry:calc
transit	Superposición de carta de tránsito	transit:calc
composite	Carta compuesta de relación	composite:calc
moonphase	Visualización de la fase lunar	moonphase:calc
daily-horoscope	Horóscopo diario para todos los signos	module:daily-report
numerology	Formulario de perfil numerológico	module:numerology
compatibility	Compatibilidad de signos solares	compatibility:calc
moon-calendar	Calendario lunar mensual	moon-calendar:calc

---

Gestión de Widgets

Listar Widgets

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

Obtener Widget

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

Crear Widget

Los widgets se crean usando el formato JSON:API:

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

Actualizar Widget

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

Eliminar Widget

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

---

Respuesta del Widget

{
    "data": {
        "type": "widgets",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "allowedDomains": ["example.com", "www.example.com"],
            "embedCode": "<script src=\"https://cdn.astroapi.cloud/widget.js\" data-widget-id=\"wgt_abc123\"></script>",
            "customization": {
                "language": "en",
                "layout": "card",
                "colors": {
                    "primary": "#5b2d8e",
                    "background": "#ffffff",
                    "text": "#1a1a1a"
                },
                "widgetOptions": {
                    "showAspects": true,
                    "showPoints": true,
                    "showHouses": true,
                    "chartSize": 500,
                    "theme": "light"
                }
            },
            "createdAt": "2024-06-15T12:00:00Z",
            "updatedAt": "2024-06-15T12:00:00Z"
        }
    }
}

---

Regenerar Clave de API

Regenerad la clave de API embebida del widget. Usad esto si la clave ha sido comprometida:

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

Rotación de Claves

Después de regenerar la clave, los embeds existentes que usen la clave antigua dejarán de funcionar inmediatamente. No necesitáis actualizar el código de embed — el ID del widget permanece igual.

---

Opciones de Widget Disponibles

Recuperad los tipos de widget disponibles para vuestra organización según vuestros módulos activos:

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

Respuesta

{
    "data": {
        "availableTypes": ["natal", "moonphase", "daily-horoscope"],
        "planFeatures": {
            "canRemoveBranding": false,
            "canUseCustomLogo": false,
            "canUseCustomCss": true,
            "maxDomains": 5
        }
    }
}

Funcionalidades del Plan

Funcionalidad	Descripción
canRemoveBranding	Si se puede ocultar la marca de AstroAPI
canUseCustomLogo	Si se puede mostrar un logo personalizado en lugar del predeterminado
canUseCustomCss	Si se puede inyectar CSS personalizado en el widget
maxDomains	Número máximo de dominios permitidos por widget

---

Objeto de Personalización

El objeto customization controla la apariencia y el comportamiento del widget:

{
    "colors": {
        "primary": "#5b2d8e",
        "secondary": "#a07cc5",
        "background": "#ffffff",
        "text": "#1a1a1a",
        "border": "#e0e0e0"
    },
    "fonts": {
        "family": "Inter, sans-serif",
        "size": "14px"
    },
    "borders": {
        "radius": "8px",
        "width": "1px"
    },
    "spacing": {
        "padding": "16px",
        "gap": "12px"
    },
    "shadows": {
        "card": "0 2px 8px rgba(0,0,0,0.1)"
    },
    "layout": "card",
    "interaction": {
        "allowUserInput": true,
        "showTooltips": true
    },
    "branding": {
        "showPoweredBy": true,
        "logoUrl": null
    },
    "language": "en",
    "customCss": ".astroapi-widget { font-weight: 500; }",
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": 500,
        "theme": "light"
    }
}

Campos de Personalización

Campo	Tipo	Descripción
colors.primary	string	Color de acento principal (hex)
colors.secondary	string	Color de acento secundario (hex)
colors.background	string	Color de fondo del widget (hex)
colors.text	string	Color del texto principal (hex)
colors.border	string	Color del borde (hex)
fonts.family	string	Valor CSS font-family
fonts.size	string	Tamaño de fuente base (valor CSS)
borders.radius	string	Radio del borde para tarjetas e inputs (valor CSS)
borders.width	string	Ancho del borde (valor CSS)
spacing.padding	string	Relleno interno (valor CSS)
spacing.gap	string	Separación entre elementos (valor CSS)
shadows.card	string	CSS box-shadow para elementos de tarjeta
layout	string	Estilo de diseño del widget (ver más abajo)
interaction.allowUserInput	boolean	Si los usuarios pueden introducir sus propios datos de nacimiento
interaction.showTooltips	boolean	Mostrar tooltips al pasar el ratón
branding.showPoweredBy	boolean	Mostrar el distintivo "Powered by AstroAPI"
branding.logoUrl	string | null	URL del logo personalizado (requiere canUseCustomLogo)
language	string	Código de idioma de visualización
customCss	string | null	Inyección de CSS personalizado (requiere canUseCustomCss)
widgetOptions.showAspects	boolean	Mostrar líneas de aspectos en las cartas
widgetOptions.showPoints	boolean	Mostrar símbolos planetarios en las cartas
widgetOptions.showHouses	boolean	Mostrar divisiones de casas en las cartas
widgetOptions.chartSize	number	Tamaño de la carta en píxeles
widgetOptions.theme	string	Tema de color ("light" o "dark")

Opciones de Diseño

Valor	Descripción
compact	Espacio mínimo, adecuado para barras laterales
card	Tarjeta redondeada con sombra (predeterminado)
full	Ancho completo, sin bordes
minimal	Sin fondo, sin bordes

---

Incrustar un Widget

Después de crear un widget, copiad el embedCode de la respuesta y pegadlo en el HTML de vuestro sitio web:

<!-- Colocad esto donde queréis que aparezca el widget -->
<div id="astroapi-widget-container"></div>

<!-- Cargad el script del widget -->
<script
    src="https://cdn.astroapi.cloud/widget.js"
    data-widget-id="wgt_abc123">
</script>

Lista de Dominios Permitidos

Los widgets solo se cargarán en los dominios listados en allowedDomains. Aseguraos de añadir todos los dominios (incluidas las variantes con www) donde planeáis incrustar el widget.