Widgets Embutíveis

Cria e gere widgets embutíveis para o teu site. Um widget é um componente de UI pronto a usar para uma única funcionalidade de astrologia: um formulário de mapa natal, um calendário lunar, um selector de horóscopo diário. Configura-lo no painel ou através desta API e colocas-lo em qualquer página com uma única tag de script.

Duas APIs, duas chaves

A API de gestão (/api/widgets) cria e configura os widgets. Usa a tua chave de API normal.
A API do widget (/api/widget-api) é a que o SDK chama a partir do navegador do visitante. Usa a chave própria do widget, que pode ser colocada numa página sem risco porque está limitada a esse único widget.

Procuras o guia sem código? Consulta Adicionar Widgets ao Teu Site.

Os tipos de widget que podes criar dependem dos módulos activos na tua organização. GET /api/widgets/options lista os que tens disponíveis.

Tipo	Descrição	Módulos necessários
`natal`	Formulário de dados de nascimento com mapa, posições e aspectos	`module:natal`
`synastry`	Dois formulários de dados de nascimento, mapa de sinastria e aspectos cruzados	`module:natal`, `module:synastry`
`transit`	Dados de nascimento mais um momento de trânsito, mapa de roda dupla	`module:natal`, `module:transits`
`composite`	Dois formulários de dados de nascimento, mapa composto	`module:natal`, `module:composite`
`moonphase`	Fase lunar actual com a iluminação	`module:moon`
`daily-horoscope`	Selector de signo com o horóscopo de hoje	`module:daily-report`
`numerology`	Formulário de nome e data de nascimento com os números principais	`module:numerology`
`compatibility`	Duas pessoas, pontuação de compatibilidade numerológica	`module:numerology`, `module:compatibility`
`moon-calendar`	Calendário mensal com fases, nascer e pôr da Lua	`module:moon`

Gestão de Widgets

Todos os endpoints de gestão são JSON:API e usam o 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"
          }
        }
      }
    }
  }'

A resposta de uma criação é a única altura em que a chave de API completa do widget (apiKey) é devolvida. Guarda-a, ou gera uma nova mais tarde; todas as outras respostas trazem apenas 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 aceita qualquer subconjunto de name, enabled, allowedDomains e customization. A personalização é substituída por inteiro, por isso envia o objecto completo.

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"

Devolve o widget com uma apiKey nova. Actualiza o código de incorporação no teu site com a chave nova; o ID do widget mantém-se igual.

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 do Plano

Funcionalidade	Descrição
`canRemoveBranding`	`branding.showPoweredBy` pode ser `false`
`canUseCustomLogo`	`branding.logoUrl` e `branding.companyName` podem ser definidos
`canUseCustomCss`	`customCss` é servido ao widget
`maxDomains`	Número máximo de `allowedDomains` por widget, ou `"unlimited"`

Objecto de Personalização

Todos os campos são opcionais; o que omitires é preenchido a partir dos valores predefinidos abaixo quando o widget é servido. As cores são strings de cor CSS e os tamanhos são números em píxeis.

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 Personalização

Campo	Tipo	Descrição
`colors.*`	string	Dez cores CSS, aplicadas como variáveis CSS no widget
`fonts.family`	string	Valor CSS de `font-family`
`fonts.sizeBase` / `sizeHeading` / `sizeSmall`	number	Tamanhos de letra em píxeis
`fonts.weightNormal` / `weightBold`	number	Pesos da letra
`borders.radius` / `width`	number	Píxeis; usados pelos campos, pelos botões e pelo layout em cartão
`borders.style`	string	`solid`, `dashed`, `dotted` ou `none`
`spacing.padding` / `margin`	number	Píxeis; os layouts `card` e `compact` usam `padding`
`shadows.preset`	string	`none`, `sm`, `md`, `lg` ou `xl` (layout em cartão)
`shadows.custom`	string \| null	Um `box-shadow` CSS que substitui o preset
`layout.variant`	string	Ver Variantes de layout
`interaction.tooltipEnabled`	boolean	Tooltips ao passar o rato sobre linhas de planetas, linhas de aspectos e dias do calendário
`interaction.animationsEnabled`	boolean	Animações de entrada; sempre desligadas para visitantes que preferem menos movimento
`interaction.clickThroughEnabled`	boolean	Torna o mapa apresentado numa ligação para `clickThroughUrl`
`interaction.clickThroughUrl`	string \| null	Abre num separador novo
`chartSettings`	object	Um tema de mapa parcial combinado com o tema predefinido: cores por signo, ponto e aspecto, espessuras de traço, `showDegrees`, `showRetrograde` e por aí fora
`labels`	object	Substituições para qualquer chave de etiqueta; ver Idiomas e etiquetas
`language`	string	Um dos 13 códigos de idioma suportados
`branding.showPoweredBy`	boolean	Requer `canRemoveBranding` para o definir como `false`
`branding.logoUrl` / `companyName`	string \| null	Requerem `canUseCustomLogo`
`customCss`	string \| null	Injectado na página para o widget; requer `canUseCustomCss`
`widgetOptions.showAspects` / `showPoints`	boolean	Mostra as tabelas de aspectos e de posições por baixo de um mapa
`widgetOptions.showHouses`	boolean	Mostra os números das casas no mapa
`widgetOptions.chartSize`	string \| number	`small` (300), `medium` (450), `large` (600) ou uma largura em píxeis
`widgetOptions.theme`	string	`light`, `dark`, `cosmic`, `custom` ou `auto`
`numerologyOptions.*`	boolean	Que números mostra o widget de numerologia
`dailyHoroscopeOptions.autoRefresh`	boolean	Reservado
`moonCalendarOptions.*`	boolean	Que detalhes mostra um dia do calendário e que fases são realçadas
`compatibilityOptions.*`	boolean	Anel de pontuação, descrição e números do caminho de vida

Variantes de layout

Valor	Descrição
`card`	Superfície com contorno e com o raio, o espaçamento e a sombra configurados (predefinição)
`compact`	Metade do espaçamento e letra ligeiramente mais pequena, para barras laterais
`full`	De extremo a extremo, apenas com espaçamento vertical
`minimal`	Sem qualquer moldura; herda tudo da página

Temas

light, dark e cosmic são paletas fixas para superfícies e contornos. auto usa a paleta clara e muda para a escura quando o sistema do visitante prefere o modo escuro. custom não define nada e apoia-se nas tuas colors. Em qualquer tema, as dez colors que definires prevalecem sobre a paleta.

Idiomas e etiquetas

O SDK inclui etiquetas para en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja e zh-CN. As variantes regionais recorrem ao idioma base para tudo o que não substituam. labels substitui strings individuais por cima do idioma escolhido, por exemplo:

json

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

O idioma também pode ser definido por página: data-lang="de" na tag de script, ou ?lang=de no URL da página; ambos têm precedência sobre o idioma guardado.

O SDK é servido a partir de https://widgets.astroapi.cloud/sdk.js. O separador Embed do painel produz os dois excertos abaixo já com os teus IDs preenchidos.

Inicialização 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 opcionais: data-container="#my-element" para apresentar o widget noutro sítio que não o div predefinido, e data-lang="nl" para forçar o 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 é interpretado como hora local em timezone; o formulário mostra-a exactamente como foi indicada.

API da instância

Membro	Descrição
`id`, `type`	ID do widget e tipo de widget
`getResult()`	O último resultado, quer o tenha calculado o visitante quer o `calculate()`
`setBirthData(data)`	Dados de nascimento usados por `calculate()`
`calculate()`	Executa o cálculo a partir de script e mostra o resultado. Suportado para `natal`, `transit` (no momento actual), `moonphase` e `moon-calendar` (mês corrente); os outros tipos recebem os dados do visitante e devolvem uma rejeição com erro
`destroy()`	Desmonta o widget

onResult dispara para cada resultado que o widget mostra, em todos os tipos de widget. AstroWidget.version indica a build do SDK.

Domínios

allowedDomains restringe onde a chave de API do widget funciona, verificando-a contra a Origin do pedido do navegador. São suportados wildcards de subdomínio (*.example.com) e www. é tratado como o domínio sem prefixo. Com a lista vazia a chave funciona em qualquer domínio, por isso preenche-a antes de publicares o código de incorporação.

Estes são os endpoints que o SDK chama em nome de um visitante. Estão documentados para que possas construir o teu próprio frontend sobre um widget; o SDK é o cliente de referência.

A autenticação é a chave de API do widget em X-Api-Key. A pré-visualização do painel usa uma sessão em vez disso.

Endpoint	Corpo	Tipo de widget
`GET /api/widget-api/config/:widgetId`	—	qualquer; público, devolve `widgetType` e a `customization` já combinada
`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 }` (nome e partes da data de nascimento)	`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=`	—	qualquer; pesquisa de locais para o formulário de dados de nascimento

birthData, person1 e person2 nos widgets de mapas são { dateTime, latitude, longitude, timezone, placeName? }, com dateTime como hora local (1990-06-15T14:30:00) em timezone. Chamar um endpoint para um widget de outro tipo devolve 400; um widget desactivado devolve 403; um pedido de um domínio fora de allowedDomains devolve 403 DOMAIN_NOT_ALLOWED.

Próximos Passos

Adicionar Widgets ao Teu Site — passo a passo para WordPress, Wix, Squarespace, Shopify e Webflow
Renderização de Mapas — o objecto de tema que chartSettings aceita
Chatbot com IA — o chatbot tem o seu próprio widget embutível

Widgets Embutíveis

Tipos de Widget

Gestão de Widgets

Listar Widgets

Obter Widget

Criar Widget

Actualizar Widget

Eliminar Widget

Gerar uma nova chave de API do widget

Opções de Widget Disponíveis

Funcionalidades do Plano

Objecto de Personalização

Campos de Personalização

Variantes de layout

Temas

Idiomas e etiquetas

Incorporar um Widget

Inicialização automática

Uso programático

API da instância

Domínios

API do Widget

Próximos Passos

Widgets Embutíveis ​

Tipos de Widget ​

Gestão de Widgets ​

Listar Widgets ​

Obter Widget ​

Criar Widget ​

Actualizar Widget ​

Eliminar Widget ​

Gerar uma nova chave de API do widget ​

Opções de Widget Disponíveis ​

Funcionalidades do Plano ​

Objecto de Personalização ​

Campos de Personalização ​

Variantes de layout ​

Temas ​

Idiomas e etiquetas ​

Incorporar um Widget ​

Inicialização automática ​

Uso programático ​

API da instância ​

Domínios ​

API do Widget ​

Próximos Passos ​

Widgets Embutíveis

Tipos de Widget

Gestão de Widgets

Listar Widgets

Obter Widget

Criar Widget

Actualizar Widget

Eliminar Widget

Gerar uma nova chave de API do widget

Opções de Widget Disponíveis

Funcionalidades do Plano

Objecto de Personalização

Campos de Personalização

Variantes de layout

Temas

Idiomas e etiquetas

Incorporar um Widget

Inicialização automática

Uso programático

API da instância

Domínios

API do Widget

Próximos Passos