Reports API - 16 report PDF pronti con il tuo brand

Tu invii la data di nascita, ricevi un documento pronto. Non un JSON da cui devi creare un PDF, ma il PDF stesso: impaginato, con il tuo logo, il tuo nome del report e senza alcuna menzione di noi all’interno.

Sedici di questi report sono già operativi. Insieme al gestore, alla cronologia delle esportazioni e a cinque narrazioni AI, questo significa 23 percorsi sotto /v1/reports/*.

Catalogo

Ogni riga ha un esempio pronto. Questo non è un mockup: il file è generato dalla stessa chiamata stampata nella documentazione di questo endpoint e viene ripubblicato insieme ai template.

Il numero di pagine è quello fornito da questo specifico esempio, misurato il 2026-09-21. Fluttua a seconda della carta: più aspetti significano più righe, e relocation aggiunge due o tre pagine per ogni città (4 pagine per una città, 13 per cinque).

Endpoint	Contenuto	Pagine	Crediti	Esempio
/v1/reports/natal	La grande triade, pianeti, case, aspetti	3	5 000	PDF
/v1/reports/synastry	Aspetti inter-carta di due carte, equilibrio degli elementi	2	5 000	PDF
/v1/reports/transit-yearly	Previsione dei transiti per l’anno selezionato	5	5 000	PDF
/v1/reports/relocation	Carta natale, fino a 5 città, pianeti che hanno cambiato casa, linee vicine, 19 sfere della vita	6	5 000	PDF
/v1/reports/vedic-kundli	Lagna e nakshatra, posizioni siderali, mahadasha Vimsottari	2	5 000	PDF
/v1/reports/lal-kitab	Kismat, tewa, rina rilevate, upayas	2	5 000	PDF
/v1/reports/gemstone	Raccomandazione di pietre con mantra, pietre da non indossare, stato dei graha	7	5 000	PDF
/v1/reports/human-design	Parametri chiave, centri, canali	2	5 000	PDF
/v1/reports/muhurta	Giorni propizi classificati per una singola attività	4	5 000	PDF
/v1/reports/love	Punti chiave dell’amore, la grande triade, aspetti	2	5 000	PDF
/v1/reports/career	Punti chiave della carriera, contesto della personalità, aspetti	2	5 000	PDF
/v1/reports/money	Punti finanziari chiave, case, aspetti	3	5 000	PDF
/v1/reports/business	Punti chiave del business, case, aspetti	2	5 000	PDF
/v1/reports/child	Tratti caratteriali chiave, la grande triade, pianeti	2	5 000	PDF
/v1/reports/stellaforge	Poster della carta su una pagina: pianeti, equilibrio, aspetti chiave	1	5 000	PDF
/v1/reports/tarot	Descrizione della lettura e delle carte	2	100	PDF
/v1/reports/vastu	Pianta della casa con mandala, valutazione, scoperte Vastu con fonti e correzioni	2	5 000	PDF

Il Tarot costa cinquanta volte meno perché non ci sono effemeridi: una pagina di lettura senza calcoli astronomici.

Profondità: standard o extended

/v1/reports/natal (e /v1/reports/generate con report_type: "natal") accetta depth. standard è il documento sopra, 5000 crediti. extended costa 10000 crediti e aggiunge la ruota della carta e una sezione per ogni corpo dal Sole a Plutone, Chirone e l’Ascendente nel segno: dodici sezioni, ciascuna di due-quattro pagine di testo modificato (esempio PDF, 13 pagine) dallo stesso corpus che restituisce /v1/natal-texts. Nulla viene generato su richiesta, quindi la stessa carta produce lo stesso documento.

Le sezioni sono disponibili in 20 lingue, le lingue del sito; depth: "extended" con una lingua diversa viene rifiutato con un 400, anziché essere compilato da un’altra lingua. Altri tipi di report hanno per ora una sola profondità: le loro sezioni lunghe non sono ancora state scritte.

Un unico percorso invece di sedici

POST /v1/reports/generate accetta il campo report_type e fa lo stesso di un percorso separato. Dodici tipi: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Per l’SDK è un metodo invece di dodici, per l’MCP uno strumento invece di dodici. Il prezzo è lo stesso: una chiamata tramite il gestore addebita esattamente quanto un percorso diretto.

PDF o HTML

Per impostazione predefinita, ricevi un PDF e un link ad esso. ?format=html restituisce una pagina HTML pronta direttamente nella risposta, senza rendering e senza archiviazione: comodo quando incorpori il report nella tua pagina o vuoi applicare il tuo CSS.

Il link al PDF è valido per 24 ore. Per fornire al cliente un link più duraturo, aggiungi ?retain_days=30 (fino a 90): il file rimarrà per quel numero di giorni, e expires_at nella risposta lo indicherà. Non ospitiamo documenti di terzi a tempo indeterminato, e puoi eliminare un file prima tramite DELETE /v1/reports/files/{filename}, gratuitamente. Il file contiene ciò che hai inviato, insieme al nome, quindi il periodo di conservazione è descritto nel DPA, sezione 2. GET /v1/reports/history mostra gratuitamente le ultime esportazioni di questa chiave, e una voce scaduta viene restituita con expired: true.

Il tuo brand, non il nostro

whitelabel accetta un oggetto con 15 campi: companyName, companyUrl, companyEmail, companyMobile, companyBio, logoUrl, frontImage, reportName, footerText, fontPairing e cinque colori (themeColor, headingColor, textPrimaryColor, textSecondaryColor, backgroundColor).

Puoi passarlo direttamente nella richiesta, e in tal caso non è necessaria alcuna configurazione dell’account:

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" } }'

Nel documento generato, il nome dello studio, il titolo del report personalizzato, il colore d’accento nei titoli delle sezioni e il tuo piè di pagina. La parola AstroWay non compare mai.

Un’alternativa per chi non vuole ripetere l’oggetto in ogni richiesta: whitelabel: true utilizza la configurazione dell’account salvata. Impostala nella pagina Branding dei report nel pannello di controllo: nome dell’azienda, nome del report, contatti, logo e due colori, con un’anteprima di un esempio di report natale. Le stesse impostazioni sono disponibili con la chiave tramite /v1/whitelabel/config e /v1/whitelabel/logo, e POST /v1/whitelabel/preview disegna un esempio in PDF. Un campo passato nell’oggetto ha la precedenza su quello salvato.

Applicazione pronta da clonare

Demo live e codice su GitHub, MIT.

Il tavolo del praticante: dati del cliente a sinistra, PDF pronto a destra. Ogni riquadro del report mostra il prezzo in crediti prima del clic e porta a un esempio pronto. Il white-label si attiva con una spunta. Il backend è un unico percorso senza dipendenze, perché è proprio qui il punto: il browser non può accedere direttamente all’API, quindi la chiave risiede sul server.

git clone https://github.com/astroway/starter-practice
cd starter-practice && npm install
cp .env.example .env     # your key goes here
npm run dev

Quattro cose da considerare. Il prezzo è mostrato dove viene presa la decisione: il server restituisce X-Credits-Used alla pagina, non solo nel log. Sedici report hanno quattro forme di richiesta, non sedici. La stessa richiesta una seconda volta costa zero, perché la cache delle risposte restituisce lo stesso file. E ALLOWED_REPORTS limita ciò che l’istanza accetterà di renderizzare: la demo pubblica renderizza solo la lettura dei Tarocchi (/v1/reports/tarot, 100 crediti), perché una pagina su internet aperta che crea un report natale (/v1/reports/natal, 5 000) per chiunque, esaurisce il limite mensile gratuito in due clic.

Lingue

Il campo language accetta 21 codici. Tre sono completamente tradotte: ucraino, inglese, russo. Per le restanti diciotto, i nomi dei segni sono localizzati, mentre i titoli e le spiegazioni rimangono in inglese: un report tedesco scriverà “Löwe” sotto il titolo “Planets”.

Lo scriviamo chiaramente, perché il report è un documento che il tuo cliente conserva. Venderlo come tedesco, vedendo i nomi dei segni tedeschi nell’esempio, sarebbe una spiacevole scoperta da parte del cliente, non nostra. Il report muhurta è per ora interamente in inglese.

Attenzione

Misurato il 2026-09-20. Se hai bisogno di una lingua specifica completamente tradotta, scrivici: la coda delle traduzioni manuali segue la domanda, non un elenco.

Quanti report sono inclusi nel piano

/v1/reports/natal e gli altri PDF costano 5 000 crediti, quindi il limite mensile del piano si traduce semplicemente in numero di report:

Piano	Crediti/mese	Report PDF	Report Tarocchi
Free	10 000	report non disponibili	non disponibili
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

Sul piano Free i report sono intenzionalmente disabilitati: un singolo PDF richiede secondi di lavoro di Chrome da parte nostra, e il piano gratuito non li copre. L’ingresso più economico è Indie a $5.

Reports Pack è un add-on separato per chi ha bisogno solo dei report: $99 al mese, 1 500 000 crediti, ovvero 300 PDF a 33 centesimi l’uno, con white-label. Questo è più economico per PDF rispetto al piano Pro, perché la chiave non va da nessuna parte tranne che ai report. Una chiave di questo piano funziona solo con /v1/reports/* e /v1/whitelabel/*.

Rivendita di report: quanto ti costa un PDF

Se vendi report ai tuoi clienti, un numero è importante: quanto ti costa un PDF al tuo volume. Entro il limite del piano, è il prezzo del piano diviso per il numero di PDF. Oltre il limite, ogni PDF è considerato un overage, calcolato per ogni 10 000 crediti oltre il limite, quindi un PDF da 5000 crediti costa la metà della tariffa di overage del piano.

Piano	PDF inclusi nel piano	Prezzo PDF entro il limite	Ogni PDF oltre il limite
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

Quindi il piano più economico dipende da quanti PDF vendi al mese, inclusi gli overage:

PDF al mese	Piano più economico	Le tue spese	Per 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

Punti di svolta: Starter è più vantaggioso di Indie da 16 PDF, Pro di Starter da 57, Reports Pack di Pro da 187, se non ti serve altro che i report, Business di Reports Pack da 367. Pro e Business aprono anche il resto dell’API, Pack solo report e white-label.

Il margine lo decidi tu. Per 300 PDF nel Reports Pack, le tue spese sono $99 al mese. A $9 l’uno, sono $2700 di entrate contro $99 di spese; a $19, sono $5700. Non consigliamo un prezzo al dettaglio, ma l’aritmetica è la stessa per qualsiasi prezzo: il tuo prezzo meno 33 centesimi.

Un report natale esteso costa il doppio di uno standard, quindi su ogni piano superiore è il doppio del prezzo per PDF: $0.66 nel Reports Pack.

Due cose riducono ulteriormente i costi reali. Una richiesta ripetuta con gli stessi dati restituisce lo stesso file dalla cache delle risposte e non costa nulla, quindi un cliente che scarica un report due volte viene addebitato una sola volta. E un piano annuale sono 12 mesi al prezzo di 9, e il Reports Pack risulta a $0.25 per PDF.

Prima di vendere, apri gli esempi: ognuno è esattamente il file che l’API restituisce, e con whitelabel il tuo nome e i tuoi colori prendono il posto di quelli predefiniti.

Se hai bisogno di testo, non di un documento

Cinque endpoint restituiscono una narrazione AI come JSON, senza impaginazione e senza PDF: /v1/reports/ai/natal-narrative, /transit-narrative, /synastry-narrative, /year-ahead-narrative, /monthly-narrative. Costano 250 crediti ciascuno. Usali quando il testo va nel tuo layout, applicazione o newsletter.

Il report natale supporta anche una modalità mista: enrich: true aggiunge la narrazione AI all’interno del PDF. Sulla stessa carta di test, questo significa 5 pagine invece di 3.