# Astro: documentação completa > Crie checkouts personalizados, gerencie assinaturas e conecte gateways em um só lugar. Pagamentos para SaaS sem comissão do Astro por transação. Contrato completo da API de integração (OpenAPI 3): https://astroengine.com.br/docs/openapi.json --- # Visão geral Fonte: https://astroengine.com.br/docs/visao-geral > O que é o Astro e como esta documentação está organizada. O Astro reúne checkout, orquestração de pagamentos e assinaturas em uma única plataforma. Você cria a página de venda com a sua identidade, conecta os gateways que já usa e acompanha pedidos e receita no mesmo painel. O Astro não cobra comissão sobre as suas vendas: os pagamentos passam pelos gateways que você conecta, com as taxas do seu contrato com eles. ## O que você encontra aqui - **Começando**: crie a conta e publique o primeiro checkout. - **Checkouts**: monte a página no builder e publique no seu domínio. - **Pagamentos**: conecte gateways e defina como cada cobrança é roteada. - **Desenvolvedores**: integre pela API e receba eventos por webhook. ## Por onde começar Se é o seu primeiro acesso, siga [Primeiros passos](/docs/primeiros-passos). Se você vai integrar um sistema, comece pela [API](/docs/desenvolvedores/api). > **Para IA:** esta documentação também está disponível em [/docs/llms.txt](/docs/llms.txt), pronta para Cursor, Claude e outras ferramentas. --- # Primeiros passos Fonte: https://astroengine.com.br/docs/primeiros-passos > Da criação da conta ao primeiro checkout publicado. Este guia leva você do cadastro ao primeiro checkout no ar. ## Antes de começar Tenha em mãos as credenciais de um gateway suportado: **Stripe**, **Mercado Pago** ou **AbacatePay**. Veja o que cada um oferece em [Gateways](/docs/pagamentos/gateways). ## Passo a passo 1. **Crie sua conta.** Cadastre-se com e-mail ou Google e confirme o e-mail. Ao entrar, você cai no seu workspace. 2. **Cadastre um produto.** Em **Produtos**, informe nome e preço. Para cobranças recorrentes, defina o ciclo do preço. 3. **Conecte um gateway.** Em **Gateways**, escolha o provedor, o ambiente (sandbox ou produção) e informe as credenciais. 4. **Crie o checkout.** Em **Checkouts → Criar checkout**, escolha um modelo, aplique a identidade da marca e ajuste a página no builder. 5. **Defina o pagamento no fluxo.** No fluxo de orquestração do checkout, escolha qual gateway atende cada método de pagamento. 6. **Publique.** Clique em **Publicar** e compartilhe o endereço com seus clientes. > **Dica:** comece no ambiente sandbox do gateway e faça uma compra de teste antes de publicar em produção. ## Convide sua equipe Em **Configurações → Equipe**, convide pessoas por e-mail. Cada membro recebe um convite e entra no mesmo workspace com as permissões definidas para ele. --- # Criar um checkout Fonte: https://astroengine.com.br/docs/checkouts/criar-checkout > Escolha um modelo, aplique sua identidade e ajuste a página no builder. ## Escolha um ponto de partida Em **Checkouts → Criar checkout**, escolha um modelo pronto ou comece com uma página em branco. O modelo só acelera: tudo continua editável. ## Aplique a identidade da marca Antes de abrir o editor, defina: - **Nome e endereço** da página; - **Cor principal**, usada em botões e estados selecionados; - **Tipografia** e **arredondamento** dos componentes; - **Estilo do botão principal**: sólido, degradê, brilho ou contorno. ## Monte a página no builder Arraste blocos da biblioteca para a página. Entre eles estão apresentação, logo, banner, vídeo de vendas, título, parágrafo, imagem, benefícios, depoimentos, perguntas frequentes e garantia. Em **Página**, ajuste tema, arredondamento, largura, espaçamento entre componentes e cores. Em **Bloco**, edite o conteúdo e o visual do bloco selecionado. > **Botões com ação:** um botão pode levar o comprador direto para as formas de pagamento, o carrinho, os dados pessoais, o cupom ou outra seção da página, ou abrir uma URL. ## Publique As alterações são salvas automaticamente. Quando estiver pronto, clique em **Publicar**. O checkout publicado fica disponível no endereço da página e pode ser servido no seu próprio domínio. Veja [Domínio próprio](/docs/checkouts/dominio-proprio). --- # Domínio próprio Fonte: https://astroengine.com.br/docs/checkouts/dominio-proprio > Publique o checkout em um endereço da sua marca, como checkout.empresa.com. Com domínio próprio, o comprador paga em um endereço da sua marca, como `checkout.empresa.com`, em vez do endereço padrão do Astro. > **Plano:** domínio próprio está disponível a partir do plano **Pro**, com até três domínios. ## Vincule o domínio 1. Em **Configurações → Domínios do checkout**, informe o subdomínio e escolha o checkout que ele vai servir. 2. O Astro mostra o **alvo CNAME**. No painel de DNS do seu domínio, crie um registro `CNAME` apontando o subdomínio para esse alvo. 3. Volte ao Astro e clique em **Verificar**. Quando o CNAME é encontrado, a rota é ativada e o certificado SSL é emitido. A propagação de DNS pode levar alguns minutos. Se a verificação falhar, confira o registro e tente novamente. ## Remover um domínio Ao remover um domínio, a rota pública dele é arquivada. O checkout continua disponível no endereço padrão. --- # Gateways Fonte: https://astroengine.com.br/docs/pagamentos/gateways > Conecte Stripe, Asaas, Mercado Pago, PayPal ou AbacatePay e saiba o que cada um suporta. Os pagamentos são processados pelos gateways que você conecta, com as taxas do seu contrato com eles. Você pode conectar mais de um gateway e decidir no fluxo de orquestração qual atende cada cobrança. O comprador paga na página hospedada do checkout, sem ser levado ao site do gateway. O cartão é digitado no formulário seguro do gateway, embutido no checkout, e os dados vão direto para ele, sem passar pelo Astro. Pix e boleto aparecem como QR code e linha digitável na mesma tela. O [checkout transparente](/docs/desenvolvedores/checkout-transparente), dentro do seu app, está em preparação para o lançamento. ## Gateways suportados | Gateway | Pix | Boleto | Cartão | Assinatura | | ------------ | --- | ------ | --------------------------- | --------------------------------- | | Stripe | Sim | — | Sim, no checkout | Sim, cartão | | Mercado Pago | Sim | — | Sim, no checkout, parcelado | Sim, na página do Mercado Pago | | Asaas | Sim | Sim | Sim, na fatura do Asaas | Sim, cartão (Pix/boleto opcional) | | PayPal | — | — | Sim, na página do PayPal | Sim, na página do PayPal | | AbacatePay | Sim | Sim | — (em breve) | — (em breve) | "No checkout" significa que o comprador digita o cartão na sua página. "Na página do gateway" significa que o comprador é levado ao ambiente seguro do provedor e volta ao seu checkout com o pagamento confirmado. Os dados do cartão nunca passam pelo Astro. ## Conectar um gateway 1. Em **Gateways**, escolha o provedor. 2. Selecione o ambiente: **sandbox** para testes ou **produção**. 3. Informe as credenciais da sua conta no provedor. O Astro testa a conexão antes de salvar. 4. Cadastre no painel do provedor o **endereço de webhook** exibido pelo Astro, para que as confirmações de pagamento cheguem automaticamente. > **Segurança:** credenciais e segredos de webhook são criptografados e nunca são exibidos de novo depois de salvos. O endereço de webhook e o segredo aparecem apenas na criação da conexão: guarde-os nesse momento. ## Observações por gateway - **Asaas:** exige o CPF ou CNPJ do comprador; o checkout passa a pedir o documento automaticamente quando a forma de pagamento usa o Asaas. No webhook, use o token de autenticação informado na conexão e ative os eventos de Cobranças e Assinaturas. Boleto não pode ser reembolsado pela API. - **PayPal:** configure uma URL de retorno HTTPS na conexão. O Astro captura o pagamento assim que o comprador aprova. Cancelamento de assinatura é imediato e troca de plano exige nova aprovação. - **Mercado Pago:** Pix e cartão no checkout. Para aceitar cartão, informe a **Public key** da sua conta (Suas integrações → Credenciais) na conexão; sem ela, a conexão oferece só Pix. O formulário do cartão é o do próprio Mercado Pago, com bandeira e parcelas (até 12x por padrão). Cartão no Mercado Pago não tem gateway reserva (veja [Orquestração](/docs/pagamentos/orquestracao)). Assinaturas são autorizadas com cartão na página do Mercado Pago. - **AbacatePay:** reembolso apenas integral; boleto não pode ser reembolsado pela API. - **Stripe:** cartão é confirmado no navegador do comprador; Pix exibe QR code e copia e cola quando a sua conta Stripe tem o método habilitado. --- # Orquestração Fonte: https://astroengine.com.br/docs/pagamentos/orquestracao > Defina no fluxo qual gateway atende cada método e acompanhe aprovação e custos. A orquestração decide por onde cada cobrança passa. Ela é configurada no **fluxo** do checkout, onde você liga cada método de pagamento a um gateway conectado. ## Configurar o fluxo 1. Abra o checkout e entre no fluxo de orquestração. 2. Para cada método de pagamento, escolha o gateway que vai processá-lo. 3. Salve e publique o checkout para que a regra passe a valer. O gateway escolhido fica registrado em cada pagamento. Mudanças futuras no fluxo não alteram pagamentos que já foram iniciados. ## Gateway reserva Ligue a saída **Falhou** de um gateway a outro para que ele seja tentado quando a cobrança é recusada ou o gateway está fora do ar. A reserva só entra quando mantém a mesma experiência de pagamento que o comprador já está vendo: - **Pix e boleto:** qualquer gateway que ofereça o método pode ser reserva. - **Cartão:** os dados são digitados no formulário seguro do próprio gateway, então a reserva precisa ser outra conta do **mesmo** gateway (por exemplo, duas contas Stripe). - **Cartão no Mercado Pago:** o cartão vira um token de uso único da sua conta, que não pode ser cobrado em outro lugar. Não há reserva para cartão; se ele for recusado, o comprador tenta de novo com outro cartão ou com Pix. O editor do fluxo avisa quando uma reserva não vale para cartão, e a simulação mostra o caminho real. Em caso de timeout, o Astro nunca passa para a reserva: ele confere com o gateway se a cobrança aconteceu antes de qualquer nova tentativa, para o comprador não pagar duas vezes. ## Acompanhar resultados - **Desempenho da orquestração** mostra aprovação e recusas por gateway. - **Taxas dos gateways** reúne os custos de cada provedor para comparar o que cada um cobra. --- # API Fonte: https://astroengine.com.br/docs/desenvolvedores/api > Autenticação por chave, escopos, formato de resposta, erros e limites da API de integração. A API de integração permite consultar seus dados do Astro a partir dos seus sistemas: produtos, pedidos, clientes, assinaturas, faturas e analytics. As rotas ficam sob `/developer/v1` e respondem em JSON. ## Crie uma chave de API Em **Desenvolvedores → Chaves de API**, crie uma chave e escolha os escopos que ela pode usar. A chave completa aparece **uma única vez**, na criação. Guarde-a em um cofre de segredos. As chaves têm o formato: ```text astro_live__ ``` Você pode **rotacionar** uma chave (a nova substitui a anterior na hora) ou **revogar** quando não precisar mais dela. ## Autenticação Envie a chave no header `x-api-key`: ```bash curl https://SUA_API_ASTRO/developer/v1/products \ -H "x-api-key: astro_live_xxx_yyy" ``` ## Escopos Cada chave só acessa o que seus escopos permitem. Os escopos de consulta são somente leitura. | Escopo | Permite | | ---------------------------- | ---------------------------------------------------------------- | | `products.read` | listar e consultar produtos, preços e variantes | | `orders.read` | listar e consultar pedidos | | `customers.read` | listar e consultar clientes | | `subscriptions.read` | consultar assinaturas, ciclos, histórico e faturas da assinatura | | `invoices.read` | listar e consultar faturas | | `analytics.read` | consultar relatórios, em JSON ou CSV | | `analytics.write` | enviar eventos de analytics | | `usage.read` / `usage.write` | consultar e registrar consumo | | `payments.read` | listar e consultar pagamentos, status e reembolsos | | `checkout_sessions.write` | criar o link de pagamento pelo seu servidor | | `subscriptions.write` | cancelar a assinatura de um cliente | ## Ligue a compra ao usuário do seu app O Astro devolve em **todos os webhooks** a referência que você mandou no checkout. Use o ID do usuário no seu sistema para liberar o acesso da pessoa certa. **Pelo link do checkout**, sem programar: acrescente `?ref=` e, se quiser, `meta_=` (até 20 chaves): ```text https://checkout.seudominio.com/meu-plano?ref=user_123&meta_plano=pro ``` **Pelo servidor**, quando a referência não pode ser alterada pelo comprador: ```bash curl -X POST https://api.seudominio.com/developer/v1/checkout-sessions \ -H "x-api-key: $ASTRO_API_KEY" \ -H "content-type: application/json" \ -d '{"checkout":"meu-plano","items":[{"priceId":"pri_...","quantity":1}],"externalReference":"user_123"}' ``` A resposta traz `url`: redirecione o comprador para ela. Uma referência enviada pelo servidor é confiável; a do link pode ser trocada por quem tem o link, então trate-a apenas como "quem iniciou a compra". Os modos `"embedded"` e `"custom"`, usados para pagamento dentro do app, estão em preparação para o lançamento. Enquanto o endpoint público do SDK não estiver disponível, use `"hosted"` e a `url` devolvida pela sessão. Veja a prévia do [checkout transparente](/docs/desenvolvedores/checkout-transparente). Para o botão "cancelar plano" dentro do seu app, use `POST /developer/v1/subscriptions/:id/cancel` com `{"atPeriodEnd": true}`. ## Respostas e erros Respostas de sucesso vêm em um envelope: ```json { "data": {}, "meta": {} } ``` Erros seguem o formato Problem Details, com `code`, `status`, `detail`, `instance` e `requestId`. Informe o `requestId` ao suporte para investigar uma chamada. ## Limites O limite de requisições é individual por chave, contado em janelas de um minuto. Ao ultrapassá-lo, a API responde com HTTP `429`. Recursos acima do limite do seu plano também retornam `429` com o código `FEATURE_LIMIT_EXCEEDED`. ## Idempotência O envio de eventos de analytics aceita uma `idempotencyKey`. Repetir a mesma chave retorna sucesso com `duplicate: true`, sem contar o evento duas vezes. --- # Checkout transparente Fonte: https://astroengine.com.br/docs/desenvolvedores/checkout-transparente > Venda dentro do seu app com o checkout embutido, o componente de pagamento ou a API headless. > **Disponibilidade:** o checkout transparente está em preparação para o lançamento. O > endpoint público do SDK ainda não está disponível; esta página é uma prévia técnica e não deve > ser usada em produção enquanto este aviso estiver visível. No **checkout hospedado**, o Astro devolve o link do checkout publicado e o comprador paga lá. No **checkout transparente**, a compra acontece **dentro do seu app**: você integra os componentes ou a API de pagamentos do Astro no seu frontend, e o usuário nunca troca de página. Existem três formas de integrar. As três usam a mesma sessão criada pelo seu servidor: | Forma | Como fica | Quando usar | | --------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- | | **Checkout embutido** | O checkout completo (resumo, cupom, dados e pagamento) dentro de um bloco do seu app. | Integração mais rápida. | | **Componente de pagamento** | Só as formas de pagamento. O resumo e o botão "Assinar" são seus. | Você já tem uma tela de plano e quer só o pagamento. | | **Headless** | Nenhum componente do Astro: o seu frontend chama a API da sessão. | Controle total do layout. | Nas duas primeiras, o Astro desenha o pagamento num quadro seguro (iframe) dentro da sua página. Os dados do cartão vão direto para o gateway e nunca passam pelo seu app nem pelo Astro. ## 1. Autorize o domínio do seu app Em **Desenvolvedores → Domínios do app**, informe o endereço exato do seu app, por exemplo `https://app.suaempresa.com`. Só esses domínios podem exibir o checkout embutido e chamar a API da sessão pelo navegador. Para testar na sua máquina, `http://localhost:5173` também é aceito. ## 2. Crie a sessão no seu servidor Com uma chave de API com o escopo `checkout_sessions.write`, crie a sessão quando o usuário clicar em assinar. A chave nunca pode ir para o navegador. ```bash curl -X POST https://api.seudominio.com/developer/v1/checkout-sessions \ -H "x-api-key: $ASTRO_API_KEY" \ -H "content-type: application/json" \ -d '{ "checkout": "meu-plano", "items": [{ "priceId": "pri_...", "quantity": 1 }], "uiMode": "embedded", "externalReference": "id-do-usuario-no-seu-app", "customer": { "name": "Maria Souza", "email": "maria@exemplo.com" }, "returnUrl": "https://app.suaempresa.com/assinatura/retorno" }' ``` | Campo | Para que serve | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `uiMode` | `embedded` para o checkout embutido e o componente de pagamento; `custom` para headless. `hosted` (padrão) devolve o link do checkout hospedado. | | `externalReference` | O id do usuário no seu app. Volta em todos os webhooks. | | `customer` | Opcional. Com ele, o checkout não pede nome e e-mail de novo. | | `returnUrl` | Opcional. Para onde o comprador volta quando o pagamento continua fora da página (PayPal). Precisa estar num domínio autorizado. | A resposta traz o `clientSecret`, que o seu frontend usa para operar **só esta sessão**: ```json { "data": { "id": "chs_...", "uiMode": "embedded", "clientSecret": "chs_..._secret_...", "expiresAt": "2026-11-05T15:30:00.000Z" } } ``` Entregue o `clientSecret` ao frontend do usuário logado e não o registre em logs. Ele vale enquanto a sessão estiver aberta. ## 3a. Checkout embutido ```html
``` O bloco ajusta a altura sozinho. Em React: ```tsx import { AstroCheckout } from "@astro/js/react"; router.push("/obrigado")} />; ``` ## 3b. Componente de pagamento Mostra só as formas de pagamento. O botão de finalizar é o do seu app: ```js const payment = Astro().payment({ clientSecret }); payment.mount("#pagamento"); botaoAssinar.addEventListener("click", async () => { const outcome = await payment.confirm(); if (!outcome.ok) return mostrarErro(outcome.message); // ex.: dados do cartão incompletos if (outcome.status === "approved") return mostrarObrigado(outcome.orderId); // 'pending': Pix ou boleto emitido, aparece no próprio componente }); ``` ## 3c. Headless Sem componente: o seu frontend chama a API da sessão com o `clientSecret`. Use `uiMode: "custom"` na criação. ```js const session = Astro().session(clientSecret); const { manifest } = await session.checkout(); // formas de pagamento disponíveis await session.selectPaymentMethod("pay_pix"); await session.confirm(); const result = await session.waitForResult(); mostrarPix(result.payment.artifacts.pix.copyPaste, result.payment.artifacts.pix.qrCodeBase64); ``` Sem o SDK, as mesmas rotas aceitam `Authorization: Bearer ` em `/public/v1/checkout-sessions/:id` (`/checkout`, `/customer`, `/select-payment-method`, `/apply-coupon`, `/confirm`, `/result`). **Cartão no headless:** a forma de pagamento com `clientIntegration: "card_tokenization"` traz `cardTokenization.publicKey`. Gere o token com o script do gateway no seu frontend (no Mercado Pago, o Card Payment Brick com essa chave) e envie em `session.confirm({ card: { token, installments, paymentMethodId, issuerId } })`. Os dados do cartão nunca passam pelo Astro. Se o seu app não pode carregar scripts de gateways, use o componente de pagamento. ## Eventos | Evento | Quando | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `ready` | O checkout carregou. | | `change` | O comprador escolheu outra forma de pagamento. | | `success` | Pagamento aprovado. | | `pending` | Pix ou boleto emitido, aguardando o pagamento. | | `failed` | Pagamento recusado ou expirado. | | `retry` | O comprador pediu para tentar de novo: crie outra sessão no servidor e monte de novo. | | `redirect` | O pagamento continua no site do gateway (PayPal). O SDK leva a janela do seu app até lá; chame `event.preventDefault()` para cuidar disso você mesmo. | | `error` | Falha de configuração (domínio não autorizado, sessão expirada). | > **Libere o acesso pelo webhook.** Os eventos do navegador servem para a interface. Quem libera o plano é o webhook `payment.approved` no seu servidor, com o `externalReference`. Veja [Webhooks](/docs/desenvolvedores/webhooks). ## Aparência Por padrão, o componente usa o tema do checkout publicado. Para combinar com o seu app: ```js Astro().checkout({ clientSecret, appearance: { variables: { colorPrimary: "#6048ee", colorBackground: "#ffffff", colorText: "#16161d", borderRadius: "10px", fontFamily: "Inter, sans-serif", }, }, }); ``` Para trocar depois de montado, use `checkout.update({ appearance })`. ## Se o seu app tem CSP Libere o Astro na política de segurança do seu app: ```text script-src {{ASTRO_SDK_ORIGIN}} frame-src {{ASTRO_SDK_ORIGIN}} connect-src {{ASTRO_SDK_ORIGIN}} (só no headless) ``` ## Erros comuns | Código | O que fazer | | ---------------------------------- | ------------------------------------------------------------------------ | | `EMBED_ORIGIN_REQUIRED` | Autorize o domínio do app antes de criar sessões `embedded` ou `custom`. | | `EMBED_ORIGIN_NOT_ALLOWED` | A página que chamou não está em **Domínios do app**. | | `CHECKOUT_SESSION_SECRET_REQUIRED` | Envie o `clientSecret` desta sessão no `Authorization: Bearer`. | | `RETURN_URL_NOT_ALLOWED` | O `returnUrl` precisa estar num domínio autorizado. | | `CARD_TOKEN_REQUIRED` | No headless com cartão tokenizado, envie o `card` no `confirm`. | --- # Webhooks Fonte: https://astroengine.com.br/docs/desenvolvedores/webhooks > Receba eventos de pagamentos, assinaturas e faturas no seu sistema, com assinatura HMAC. Webhooks avisam o seu sistema quando algo acontece no Astro, como um pagamento aprovado ou uma assinatura cancelada. ## Cadastre um endpoint Em **Desenvolvedores → Webhooks**, informe a URL HTTPS que vai receber os eventos e escolha quais eventos assinar. Guarde o **segredo de assinatura** exibido no cadastro: ele é usado para validar cada entrega. ## Eventos | Grupo | Eventos | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pagamentos | `payment.approved`, `payment.failed`, `payment.canceled`, `payment.refunded`, `payment.partially_refunded`, `payment.disputed` | | Assinaturas | `subscription.created`, `subscription.activated`, `subscription.renewed`, `subscription.past_due`, `subscription.canceled`, `subscription.paused`, `subscription.resumed` | | Faturas | `invoice.paid`, `invoice.payment_failed` | ## Headers da entrega Cada entrega é um `POST` com corpo JSON e estes headers: | Header | Conteúdo | | ------------------ | --------------------------------------- | | `Astro-Event-Id` | identificador único do evento | | `Astro-Event-Type` | tipo do evento, como `payment.approved` | | `Astro-Timestamp` | momento do envio, em segundos (Unix) | | `Astro-Signature` | HMAC-SHA256 em hexadecimal | ## Valide a assinatura A assinatura é o HMAC-SHA256 do texto `timestamp + "." + corpo bruto`, usando o segredo do endpoint. Calcule com o corpo **exatamente como recebido**, antes de qualquer parse: ```ts import { createHmac, timingSafeEqual } from "node:crypto"; export function isValidAstroWebhook(rawBody: string, headers: Headers, secret: string) { const timestamp = headers.get("astro-timestamp") ?? ""; const received = headers.get("astro-signature") ?? ""; const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"); return ( received.length === expected.length && timingSafeEqual(Buffer.from(received), Buffer.from(expected)) ); } ``` > **Importante:** use o `Astro-Event-Id` para ignorar entregas repetidas. O mesmo evento pode chegar mais de uma vez. ## Corpo da entrega Além do evento, cada entrega traz o contexto para você agir sem chamar a API: ```json { "paymentId": "pay_...", "status": "approved", "externalReference": "user_123", "metadata": { "plano": "pro" }, "customer": { "id": "cus_...", "email": "cliente@exemplo.com", "name": "Cliente", "externalReference": null }, "payment": { "id": "pay_...", "status": "approved", "method": "pix", "amountMinor": 9900, "capturedMinor": 9900, "refundedMinor": 0, "currency": "BRL" }, "subscription": { "id": "sub_...", "status": "active", "currentPeriodEndsAt": "2026-12-02T00:00:00Z" } } ``` Valores estão em centavos. `payment.disputed` indica chargeback: revogue o acesso até a disputa terminar. ## Teste sem fazer uma compra Na lista de endpoints, use **Enviar evento de teste**. O Astro envia um `webhook.test` assinado, com o mesmo formato acima, e o resultado aparece em **Logs → Webhooks**. ## Tentativas e reenvio Responda com um status `2xx` para confirmar o recebimento. Se a entrega falhar, o Astro tenta de novo até sete vezes: imediatamente, depois de 1 min, 5 min, 15 min, 1 h, 6 h e 24 h. Esgotadas as tentativas, a entrega fica marcada como falha e pode ser **reenviada manualmente** pelo painel. --- # Prompts para IA Fonte: https://astroengine.com.br/docs/desenvolvedores/prompts-ia > Prompts prontos para integrar o Astro ao seu app com Lovable, Bolt, Cursor, Claude e Antigravity. 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](/docs/llms.txt) | índice da documentação, no padrão llmstxt.org | | [llms-full.txt](/docs/llms-full.txt) | toda a documentação em um único arquivo Markdown | | [openapi.json](/docs/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 1. No Astro, publique o checkout do seu plano e anote o **slug** dele (o final do link). 2. Em **Desenvolvedores → Chaves de API**, crie uma chave com os escopos `products.read`, `checkout_sessions.write`, `payments.read` e `subscriptions.write`. 3. 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**. 4. 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: ```text 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.