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:
astro_live_<prefixo>_<segredo>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:
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=<id do usuário> e, se quiser,
meta_<chave>=<valor> (até 20 chaves):
https://checkout.seudominio.com/meu-plano?ref=user_123&meta_plano=proPelo servidor, quando a referência não pode ser alterada pelo comprador:
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”.
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:
{ "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.