Widgets Embutíveis

Cria e gere widgets embutíveis para o teu site. Os widgets fornecem componentes de UI prontos a usar para funcionalidades de astrologia que podem ser integrados em qualquer página web com uma única tag de script.

Módulo Necessário

Todos os endpoints de widgets requerem que o módulo module:embeddable-widgets esteja activado para a tua organização.

---

Tipos de Widget

Os seguintes tipos de widget estão disponíveis com base nos teus módulos activos:

Tipo	Descrição	Módulo Necessário
natal	Mapa natal interactivo	natal:calc
synastry	Mapa de comparação de sinastria	synastry:calc
transit	Sobreposição de mapa de trânsito	transit:calc
composite	Mapa de relacionamento composto	composite:calc
moonphase	Visualização da fase lunar	moonphase:calc
daily-horoscope	Horóscopo diário para todos os signos	module:daily-report
numerology	Formulário de perfil de numerologia	module:numerology
compatibility	Compatibilidade pelo signo solar	compatibility:calc
moon-calendar	Calendário lunar mensal	moon-calendar:calc

---

Gestão de Widgets

Listar Widgets

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

Obter Widget

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

Criar Widget

Os widgets são criados usando o 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"

---

Resposta do 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 Chave de API

Regenera a chave de API embutida do widget. Usa isto se a chave tiver sido comprometida:

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

Rotação de Chaves

Após regenerar a chave, os embeds existentes que usam a chave antiga deixarão de funcionar imediatamente. Não precisas de actualizar o código de embed — o ID do widget permanece o mesmo.

---

Opções de Widget Disponíveis

Obtém os tipos de widget disponíveis para a tua organização com base nos teus módulos activos:

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

Resposta

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

Funcionalidades do Plano

Funcionalidade	Descrição
canRemoveBranding	Se a marca AstroAPI pode ser ocultada
canUseCustomLogo	Se um logótipo personalizado pode ser mostrado em vez do padrão
canUseCustomCss	Se CSS personalizado pode ser injectado no widget
maxDomains	Número máximo de domínios permitidos por widget

---

Objecto de Personalização

O objecto customization controla a aparência e o comportamento do 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 Personalização

Campo	Tipo	Descrição
colors.primary	string	Cor de destaque principal (hex)
colors.secondary	string	Cor de destaque secundária (hex)
colors.background	string	Cor de fundo do widget (hex)
colors.text	string	Cor do texto principal (hex)
colors.border	string	Cor da borda (hex)
fonts.family	string	Valor CSS de font-family
fonts.size	string	Tamanho de letra base (valor CSS)
borders.radius	string	Raio de borda para cartões e entradas (valor CSS)
borders.width	string	Largura da borda (valor CSS)
spacing.padding	string	Preenchimento interno (valor CSS)
spacing.gap	string	Espaço entre elementos (valor CSS)
shadows.card	string	CSS box-shadow para elementos de cartão
layout	string	Estilo de layout do widget (ver abaixo)
interaction.allowUserInput	boolean	Se os utilizadores podem inserir os próprios dados de nascimento
interaction.showTooltips	boolean	Mostrar dicas ao passar o cursor
branding.showPoweredBy	boolean	Mostrar o emblema "Powered by AstroAPI"
branding.logoUrl	string | null	URL do logótipo personalizado (requer canUseCustomLogo)
language	string	Código de idioma de exibição
customCss	string | null	Injecção de CSS personalizado (requer canUseCustomCss)
widgetOptions.showAspects	boolean	Mostrar linhas de aspectos nos mapas
widgetOptions.showPoints	boolean	Mostrar símbolos de planetas nos mapas
widgetOptions.showHouses	boolean	Mostrar divisões de casas nos mapas
widgetOptions.chartSize	number	Tamanho do mapa em píxeis
widgetOptions.theme	string	Tema de cores ("light" ou "dark")

Opções de Layout

Valor	Descrição
compact	Espaço mínimo, adequado para barras laterais
card	Cartão arredondado com sombra (padrão)
full	Largura total, sem bordas
minimal	Sem fundo, sem bordas

---

Incorporar um Widget

Após criar um widget, copia o embedCode da resposta e cola-o no HTML do teu site:

<!-- Coloca isto onde queres que o widget apareça -->
<div id="astroapi-widget-container"></div>

<!-- Carrega o script do widget -->
<script
    src="https://cdn.astroapi.cloud/widget.js"
    data-widget-id="wgt_abc123">
</script>

Lista de Domínios Permitidos

Os widgets só carregam em domínios listados em allowedDomains. Certifica-te de que adicionas todos os domínios (incluindo variantes com www) onde planeias incorporar o widget.