Prompts para IA — Docs Astro

Se você constrói o seu SaaS com uma ferramenta de IA, ela pode fazer a integração com o Astro por você. Esta página traz o material que a IA precisa ler e um prompt pronto para colar.

O que a IA precisa ler

Arquivo	Para que serve
llms.txt	índice da documentação, no padrão llmstxt.org
llms-full.txt	toda a documentação em um único arquivo Markdown
openapi.json	contrato OpenAPI 3 da API de integração (rotas `/developer/v1`)

Se a ferramenta não consegue abrir links, baixe o llms-full.txt e anexe na conversa.

Antes de colar o prompt

No Astro, publique o checkout do seu plano e anote o slug dele (o final do link).
Em Desenvolvedores → Chaves de API, crie uma chave com os escopos products.read, checkout_sessions.write, payments.read e subscriptions.write.
Em Desenvolvedores → Webhooks, cadastre a URL que o seu app vai expor (por exemplo https://seuapp.com/api/astro/webhook) com os eventos de pagamento e assinatura, e anote o segredo de assinatura.
Guarde a chave e o segredo como variáveis de ambiente do seu app: ASTRO_API_KEY e ASTRO_WEBHOOK_SECRET. Nunca cole esses valores no chat.

Prompt de integração

Troque meu-plano pelo slug do seu checkout e cole na ferramenta:

Integre o meu app ao Astro, a plataforma de checkout e assinaturas que cobra os meus clientes.

Leia antes de escrever código:
- Documentação completa: https://astroengine.com.br/docs/llms-full.txt
- Contrato da API: https://astroengine.com.br/docs/openapi.json

O que eu preciso:
0. Descubra o priceId (pri_...) do plano: liste os produtos com GET /developer/v1/products e os
   preços com GET /developer/v1/products/:id/prices. Guarde-o como ASTRO_PRICE_ID.
1. Um botão "Assinar" que chama uma rota do MEU servidor. Essa rota cria a sessão com
   POST /developer/v1/checkout-sessions (header x-api-key com ASTRO_API_KEY), enviando
   checkout "meu-plano", items [{ priceId: ASTRO_PRICE_ID, quantity: 1 }] e
   externalReference = id do usuário logado, e redireciona
   o comprador para a "url" da resposta. A chave nunca pode ir para o navegador.
2. Uma rota de webhook que valida o header Astro-Signature: HMAC-SHA256 de
   `${Astro-Timestamp}.${corpo bruto}` com ASTRO_WEBHOOK_SECRET, comparado em tempo constante,
   antes de qualquer parse do JSON. Ignore eventos repetidos pelo Astro-Event-Id e responda 2xx.
3. Em payment.approved e subscription.activated, libere o acesso do usuário cujo id veio em
   externalReference. Em subscription.canceled, subscription.past_due e payment.disputed,
   retire o acesso.
4. Um botão "Cancelar plano" que chama, pelo meu servidor,
   POST /developer/v1/subscriptions/:id/cancel com {"atPeriodEnd": true}.

Use somente rotas e eventos que existem na documentação. Se faltar alguma informação,
pergunte antes de inventar.

Checkout transparente em preparação: não peça à ferramenta de IA para integrar o SDK enquanto o painel do Astro não fornecer a URL pública. Até lá, use o fluxo hospedado e redirecione o comprador para a url devolvida pela criação da sessão.

Para testar, use Enviar evento de teste na lista de webhooks: o Astro manda um webhook.test assinado, e o resultado aparece em Logs → Webhooks.

Onde colar em cada ferramenta

Ferramenta	Como usar
Lovable	Cole no chat do projeto. O webhook e a criação da sessão precisam rodar no backend (por exemplo, uma Edge Function do Supabase), com os segredos guardados lá.
Bolt	Cole no chat do projeto e configure `ASTRO_API_KEY` e `ASTRO_WEBHOOK_SECRET` como variáveis de ambiente do backend.
Cursor	Cole no chat do agente. Para manter o contexto em outras conversas, salve o prompt como uma regra do projeto.
Claude	No Claude Code, cole no terminal do projeto ou salve no `CLAUDE.md`. No claude.ai, anexe o `llms-full.txt` e o `openapi.json` à conversa.
Antigravity	Cole como tarefa para o agente, dentro do workspace do seu app.

Importante: revise o código gerado antes de publicar, principalmente a validação da assinatura do webhook. Ela é o que impede alguém de liberar acesso com uma requisição falsa.