Reports API - 16 relatórios PDF prontos com a tua marca
Tu envias a data de nascimento, recebes um documento pronto. Não um JSON do qual precisas de renderizar um PDF, mas o próprio PDF: paginado, com o teu logótipo, o teu nome de relatório e sem qualquer menção a nós no seu interior.
Dezasseis desses relatórios já estão a funcionar. Juntamente com o gestor, o histórico de exportações e cinco narrativas de IA, são 23 caminhos em /v1/reports/*.
Catálogo
Seção intitulada “Catálogo”Cada linha tem um exemplo pronto. Não é um mockup: o ficheiro é gerado pela mesma chamada impressa na documentação deste endpoint e é relançado juntamente com os modelos.
O número de páginas é o que este exemplo específico forneceu, medido em 2026-09-21. Varia consoante o mapa: mais aspetos significam mais linhas, e relocation adiciona duas a três páginas por cada cidade (4 páginas para uma cidade, 13 para cinco).
| Endpoint | O que está incluído | Páginas | Créditos | Exemplo |
|---|---|---|---|---|
/v1/reports/natal | Grande Trindade, planetas, casas, aspetos | 3 | 5 000 | |
/v1/reports/synastry | Aspetos inter-mapas de dois mapas, equilíbrio de elementos | 2 | 5 000 | |
/v1/reports/transit-yearly | Previsão de trânsitos para o ano selecionado | 5 | 5 000 | |
/v1/reports/relocation | Mapa natal, até 5 cidades, planetas que mudaram de casa, linhas próximas, 19 áreas da vida | 6 | 5 000 | |
/v1/reports/vedic-kundli | Lagna e Nakshatra, posições siderais, Mahadashas Vimshottari | 2 | 5 000 | |
/v1/reports/lal-kitab | Kismat, Teva, Rinas detetadas, Upayas | 2 | 5 000 | |
/v1/reports/gemstone | Recomendação de pedras com mantras, pedras a não usar, estado dos Grahas | 7 | 5 000 | |
/v1/reports/human-design | Parâmetros chave, centros, canais | 2 | 5 000 | |
/v1/reports/muhurta | Dias favoráveis classificados para uma atividade | 4 | 5 000 | |
/v1/reports/love | Pontos chave do amor, Grande Trindade, aspetos | 2 | 5 000 | |
/v1/reports/career | Pontos chave da carreira, contexto da personalidade, aspetos | 2 | 5 000 | |
/v1/reports/money | Pontos financeiros chave, casas, aspetos | 3 | 5 000 | |
/v1/reports/business | Pontos chave de negócios, casas, aspetos | 2 | 5 000 | |
/v1/reports/child | Traços chave de caráter, Grande Trindade, planetas | 2 | 5 000 | |
/v1/reports/stellaforge | Poster de mapa numa página: planetas, equilíbrio, aspetos chave | 1 | 5 000 | |
/v1/reports/tarot | Descrição da tiragem e das cartas | 2 | 100 | |
/v1/reports/vastu | Planta da casa com mandala, avaliação, descobertas Vastu com fontes e correções | 2 | 5 000 |
O Tarot custa cinquenta vezes menos porque não há efemérides: uma página de tiragem sem cálculos astronómicos.
Profundidade: standard ou extended
Seção intitulada “Profundidade: standard ou extended”/v1/reports/natal (e /v1/reports/generate com report_type: "natal") aceita depth. standard é o documento acima, 5000 créditos. extended custa 10000 créditos e adiciona a roda do mapa e uma secção para cada corpo do Sol a Plutão, Quíron e Ascendente no signo: doze secções, cada uma com duas a quatro páginas de texto editado (exemplo PDF, 13 páginas) do mesmo corpo que /v1/natal-texts retorna. Nada é gerado sob pedido, então o mesmo mapa dá o mesmo documento.
As secções estão disponíveis em 20 idiomas, os idiomas do site; depth: "extended" com um idioma diferente é rejeitado com 400, e não preenchido com outro idioma. Outros tipos de relatórios têm, por enquanto, uma única profundidade: as suas secções longas ainda não foram escritas.
Um caminho em vez de dezasseis
Seção intitulada “Um caminho em vez de dezasseis”POST /v1/reports/generate aceita o campo report_type e faz o mesmo que um caminho separado. Doze tipos: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.
Para o SDK, é um método em vez de doze; para o MCP, uma ferramenta em vez de doze. O preço é o mesmo: uma chamada através do gestor debita exatamente o mesmo que um caminho direto.
PDF, HTML ou Markdown
Seção intitulada “PDF, HTML ou Markdown”Cada tipo de relatório, e o gestor também, aceita format: no corpo do pedido ou como ?format= na string de consulta (passa uma vez; dois valores diferentes resultam em 400). O preço é o mesmo para os três, porque pagas pelo documento, e não pelo ficheiro em que ele chega.
format | O que é retornado | Armazenado |
|---|---|---|
pdf (predefinição) | JSON com url do PDF, page_count e expires_at | 24 horas ou retain_days |
html | O próprio documento, Content-Type: text/html | não armazenado |
markdown | O mesmo documento em Markdown, Content-Type: text/markdown | não armazenado |
HTML é um ficheiro autónomo: estilos internos, roda do mapa e plano Vastu como SVG incorporado, sem scripts e sem fontes externas. É a mesma página da qual o PDF é impresso, com o mesmo bloco white-label: nome da empresa, nome do relatório, cores e rodapé. O único link externo é o teu logoUrl, que permanece um link para a tua imagem https, tal como no PDF. Cada nome, local e texto que envias é escapado, então um nome como <img onerror=...> é impresso como texto. O documento pode ser inserido na tua página ou num iframe.
Markdown tem os mesmos títulos, texto e tabelas. Os níveis dos títulos são preservados: # é o nome do relatório, ## é uma secção, ### é uma subsecção, na mesma ordem que no PDF, então a divisão por linhas que começam com ## dá as secções. As tabelas estão no formato GitHub. A imagem (roda, plano) é omitida, com uma linha de nota no seu lugar. Cada caractere que o Markdown ou um renderizador de HTML leria como marcação é escapado com uma barra invertida.
curl -X POST "https://api.astroway.info/v1/reports/natal?format=markdown" \ -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \ -d '{ "chart": { "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52 }, "language": "uk" }'O link para o PDF está ativo por 24 horas. Para dar ao cliente um link por mais tempo, adiciona ?retain_days=30 (até 90): o ficheiro permanecerá por esses dias, e expires_at na resposta mostrará isso. Não alojamos documentos de terceiros indefinidamente, e podes apagar o ficheiro mais cedo através de DELETE /v1/reports/files/{filename}, gratuitamente. O ficheiro contém o que enviaste, juntamente com o nome, por isso o período de retenção é descrito no DPA, secção 2. GET /v1/reports/history mostra gratuitamente as últimas exportações desta chave, e um registo expirado vem com expired: true.
A tua marca, não a nossa
Seção intitulada “A tua marca, não a nossa”whitelabel aceita um objeto com 15 campos: companyName, companyUrl, companyEmail, companyMobile, companyBio, logoUrl, frontImage, reportName, footerText, fontPairing e cinco cores (themeColor, headingColor, textPrimaryColor, textSecondaryColor, backgroundColor).
Podes passá-lo diretamente no pedido, e então nenhuma configuração de conta é necessária:
curl -X POST https://api.astroway.info/v1/reports/natal \ -H "X-Api-Key: aw_live_..." \ -H "Content-Type: application/json" \ -d '{ "chart": { "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52 }, "whitelabel": { "companyName": "Zoryana Studio", "reportName": "Your Birth Blueprint", "themeColor": "#7c3aed", "footerText": "zoryana.example" } }'No documento gerado, o nome do estúdio, o título do relatório personalizado, a cor de destaque nos títulos das secções e o teu rodapé. A palavra AstroWay não aparece nenhuma vez.
Uma alternativa para quem não quer repetir o objeto em cada pedido: whitelabel: true usa a configuração de conta guardada. Define-a na página Branding de Relatórios no painel de controlo: nome da empresa, nome do relatório, contactos, logótipo e duas cores, com uma pré-visualização do exemplo de relatório natal. As mesmas configurações estão disponíveis com a chave via /v1/whitelabel/config e /v1/whitelabel/logo, e POST /v1/whitelabel/preview desenha um exemplo em PDF. Um campo passado no objeto tem precedência sobre o guardado.
Aplicação pronta a clonar
Seção intitulada “Aplicação pronta a clonar”Demo ao vivo e código no GitHub, MIT.
Mesa do praticante: dados do cliente à esquerda, PDF pronto à direita. Cada cartão de relatório mostra o preço em créditos antes do clique e leva a um exemplo pronto. O white-label é ativado com uma caixa de seleção. O backend é uma rota sem dependências, porque é aí que reside a essência: o navegador não pode aceder diretamente à API, então a chave reside no servidor.
git clone https://github.com/astroway/starter-practicecd starter-practice && npm installcp .env.example .env # your key goes herenpm run devQuatro coisas a reter. O preço é mostrado onde a decisão é tomada: o servidor retorna X-Credits-Used de volta à página, e não apenas no log. Dezasseis relatórios têm quatro formas de pedido, e não dezasseis. O mesmo pedido pela segunda vez custa zero, porque a cache de respostas retorna o mesmo ficheiro. E ALLOWED_REPORTS limita o que a instância concordará em renderizar: a demo pública renderiza apenas a tiragem de Tarot (/v1/reports/tarot, 100 créditos), porque uma página na internet aberta que faz um relatório natal (/v1/reports/natal, 5 000) para qualquer pessoa esgota o limite mensal gratuito em dois cliques.
Idiomas
Seção intitulada “Idiomas”O campo language aceita 21 códigos. Três estão totalmente traduzidos: ucraniano, inglês, russo. Para os restantes dezoito, os nomes dos signos são localizados, mas os títulos e explicações permanecem em inglês: um relatório alemão escreverá “Löwe” sob o título “Planets”.
Escrevemos isto diretamente, porque o relatório é um documento que o teu cliente guarda. Vendê-lo como alemão, vendo os nomes dos signos alemães no exemplo, seria uma descoberta desagradável para o cliente, e não para nós. O relatório muhurta é, por enquanto, inteiramente em inglês.
Quantos relatórios estão incluídos no plano
Seção intitulada “Quantos relatórios estão incluídos no plano”/v1/reports/natal e os restantes PDFs custam 5 000 créditos, então o limite mensal do plano é convertido em número de relatórios de forma simples:
| Plano | Créditos/mês | Relatórios PDF | Relatórios de Tarot |
|---|---|---|---|
| Free | 10 000 | relatórios indisponíveis | indisponíveis |
| Indie, $5 | 50 000 | 10 | 500 |
| Starter, $19 | 200 000 | 40 | 2 000 |
| Pro, $59 | 800 000 | 160 | 8 000 |
| Business, $199 | 3 500 000 | 700 | 35 000 |
| Reports Pack, $99 | 1 500 000 | 300 | 15 000 |
No plano Free, os relatórios estão desativados intencionalmente: cada PDF são segundos de renderização do nosso lado, e o plano gratuito não os cobre. A entrada mais barata é o Indie por $5.
Reports Pack é um add-on separado para quem precisa apenas de relatórios: $99 por mês, 1 500 000 créditos, ou seja, 300 PDFs a 33 cêntimos cada, com white-label. É mais barato por PDF do que no Pro, porque a chave não vai a lado nenhum, exceto aos relatórios. A chave de tal plano só funciona em /v1/reports/* e /v1/whitelabel/*.
Revenda de relatórios: quanto te custa um PDF
Seção intitulada “Revenda de relatórios: quanto te custa um PDF”Se vendes relatórios aos teus clientes, um número importa: quanto te custa um PDF no teu volume. Dentro do limite do plano, é o preço do plano dividido pelo número de PDFs. Acima do limite, cada PDF é cobrado como excedente, que é calculado por cada 10 000 créditos acima do limite, então um PDF de 5000 créditos custa metade da taxa de excedente do plano.
| Plano | PDFs no plano | Preço do PDF dentro do limite | Cada PDF excedente |
|---|---|---|---|
| Indie, $5 | 10 | $0.50 | $2.50 |
| Starter, $19 | 40 | $0.48 | $2.50 |
| Pro, $59 | 160 | $0.37 | $1.50 |
| Reports Pack, $99 | 300 | $0.33 | $1.50 |
| Business, $199 | 700 | $0.28 | $1.00 |
Assim, o plano mais barato depende de quantos PDFs vendes por mês, incluindo o excedente:
| PDFs por mês | Plano mais barato | Os teus custos | Por PDF |
|---|---|---|---|
| 10 | Indie | $5 | $0.50 |
| 40 | Starter | $19 | $0.48 |
| 100 | Pro | $59 | $0.59 |
| 160 | Pro | $59 | $0.37 |
| 300 | Reports Pack | $99 | $0.33 |
| 500 | Business | $199 | $0.40 |
| 700 | Business | $199 | $0.28 |
Pontos de transição: Starter é mais vantajoso que Indie a partir de 16 PDFs, Pro que Starter a partir de 57, Reports Pack que Pro a partir de 187, se não precisares de mais nada além de relatórios, Business que Reports Pack a partir de 367. Pro e Business também desbloqueiam o resto da API, Pack apenas relatórios e white-label.
A margem és tu quem define. Para 300 PDFs no Reports Pack, os teus custos são $99 por mês. A $9 por unidade, são $2700 de receita contra $99 de custos; a $19, são $5700. Não aconselhamos um preço de retalho, mas a aritmética é a mesma para qualquer um: o teu preço menos 33 cêntimos.
Um relatório natal estendido custa o dobro do padrão, então em cada plano acima, é o dobro do preço por PDF: $0.66 no Reports Pack.
Duas coisas reduzem ainda mais os custos reais. Um pedido repetido com os mesmos dados retorna o mesmo ficheiro da cache de respostas e não custa nada, então um cliente que descarregou o relatório duas vezes é cobrado apenas uma vez. E um plano anual são 12 meses pelo preço de 9, e o Reports Pack sai a $0.25 por PDF.
Antes de vender, abre os exemplos: cada um é exatamente o ficheiro que a API retorna, e com whitelabel o teu nome e cores substituem os predefinidos.
Se precisares de texto, e não de um documento
Seção intitulada “Se precisares de texto, e não de um documento”Cinco endpoints retornam uma narrativa de IA como JSON, sem formatação e sem PDF: /v1/reports/ai/natal-narrative, /transit-narrative, /synastry-narrative, /year-ahead-narrative, /monthly-narrative. Por 250 créditos. Usa-os quando o texto for para o teu próprio layout, aplicação ou newsletter.
O relatório natal também suporta um modo misto: enrich: true adiciona a narrativa de IA dentro do PDF. No mesmo mapa de teste, são 5 páginas em vez de 3.