Reports API - 21 готовий PDF-звіт під вашим брендом

Ви надсилаєте дату народження, отримуєте готовий документ. Не JSON, з якого треба зверстати PDF, а сам PDF: посторінково зверстаний, з вашим логотипом, вашою назвою звіту і без жодної згадки про нас усередині.

Двадцять один такий звіт уже працює. Разом із диспетчером, історією експортів і п’ятьма AI-наративами це 28 шляхів під /v1/reports/*.

Каталог

Кожен рядок має готовий зразок. Це не макет: файл згенеровано тим самим викликом, що надрукований у довіднику цього ендпоінта, і перевипускається разом із шаблонами.

Кількість сторінок це та, що дав саме цей зразок, виміряна 2026-09-21 (для BaZi, нумерології, сумісності кундлі й китайського року 2026-11-07). Вона плаває від карти: більше аспектів це більше рядків, а relocation додає по дві-три сторінки на кожне місто (4 сторінки для одного міста, 13 для п’яти).

Ендпоінт	Що всередині	Сторінок	Кредитів	Зразок
/v1/reports/natal	Велика трійка, планети, доми, аспекти	3	5 000	PDF
/v1/reports/synastry	Міжкартові аспекти двох карт, баланс стихій	2	5 000	PDF
/v1/reports/transit-yearly	Прогноз транзитів на вибраний рік	5	5 000	PDF
/v1/reports/relocation	Вихідна карта, до 5 міст, планети що змінили дім, лінії поруч, 19 сфер життя	6	5 000	PDF
/v1/reports/vedic-kundli	Лагна і накшатра, сідеричні позиції, махадаші Вімшоттарі	2	5 000	PDF
/v1/reports/lal-kitab	Кісмат, тева, виявлені ріни, упайї	2	5 000	PDF
/v1/reports/gemstone	Рекомендація каменів з мантрами, камені яких не носити, стан грах	7	5 000	PDF
/v1/reports/human-design	Ключові параметри, центри, канали	2	5 000	PDF
/v1/reports/muhurta	Ранжовані сприятливі дні під одну активність	4	5 000	PDF
/v1/reports/love	Ключові точки кохання, велика трійка, аспекти	2	5 000	PDF
/v1/reports/career	Ключові точки кар’єри, контекст особистості, аспекти	2	5 000	PDF
/v1/reports/money	Ключові фінансові точки, доми, аспекти	3	5 000	PDF
/v1/reports/business	Ключові точки бізнесу, доми, аспекти	2	5 000	PDF
/v1/reports/child	Ключові риси характеру, велика трійка, планети	2	5 000	PDF
/v1/reports/stellaforge	Постер карти на одну сторінку: планети, баланс, ключові аспекти	1	5 000	PDF
/v1/reports/tarot	Опис розкладу і карти	2	100	PDF
/v1/reports/vastu	План дому з мандалою, оцінка, знахідки Васту з джерелами й виправленнями	2	5 000	PDF
/v1/reports/bazi	Чотири стовпи з божествами й прихованими стовбурами, господар дня, п’ять стихій, сила, символічні зірки, взаємодії, стовпи удачі	4	5 000	PDF
/v1/reports/numerology	Шість основних чисел з тлумаченням, число рівноваги, вершини й виклики з віком, особистий рік	3	5 000	PDF
/v1/reports/kundli-matching	Гуна Мілан з 36, Порутам з 10, Мангал, Наді й Бхакут доші з правилами скасування, навамша, даші пари поруч	4	5 000	PDF
/v1/reports/chinese-year	Ваша тварина, стовп року і його стосунок до вашого знака, союзники, дванадцять сонячних місяців	3	5 000	PDF

Таро коштує в п’ятдесят разів менше: це одна сторінка розкладу без астрономічних обчислень.

Глибина: standard або extended

/v1/reports/natal (і /v1/reports/generate з report_type: "natal") приймає depth. standard це документ вище, 5000 кредитів. extended коштує 10000 кредитів і додає колесо карти та розділ для кожного з тіл від Сонця до Плутона, Хірона й Асцендента у знаку: дванадцять розділів, кожен на дві-чотири сторінки відредагованого тексту (зразок PDF, 13 сторінок) з того самого корпусу, що віддає /v1/natal-texts. Нічого не генерується під запит, тож та сама карта дає той самий документ.

Розділи є 20 мовами, мовами сайту; depth: "extended" з іншою мовою відхиляється з 400, а не заповнюється з іншої мови. Інші типи звітів поки мають одну глибину: їхні довгі розділи ще не написані.

Один шлях замість шістнадцяти

POST /v1/reports/generate приймає поле report_type і робить те саме, що й окремий шлях. Дванадцять типів: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Для SDK це один метод замість дванадцяти, для MCP один інструмент замість дванадцяти. Ціна однакова: виклик через диспетчер списує рівно стільки, скільки прямий шлях.

PDF, HTML чи Markdown

Кожен тип звіту, і диспетчер теж, приймає format: у тілі запиту або як ?format= у рядку запиту (передайте один раз; два різні значення дають 400). Ціна однакова в усіх трьох, бо ви платите за документ, а не за файл, у якому він приходить.

format	Що повертається	Зберігається
pdf (за замовчуванням)	JSON з url PDF, page_count і expires_at	24 години або retain_days
html	Сам документ, Content-Type: text/html	не зберігається
markdown	Той самий документ у Markdown, Content-Type: text/markdown	не зберігається

HTML це один самодостатній файл: стилі всередині, колесо карти й план Васту як вбудований SVG, без скриптів і без зовнішніх шрифтів. Це та сама сторінка, з якої друкується PDF, з тим самим white-label блоком: назва компанії, назва звіту, кольори й підвал. Єдине зовнішнє посилання це ваш logoUrl, він лишається посиланням на ваше https-зображення, так само як у PDF. Кожне ім’я, місце й текст, які ви надсилаєте, екрануються, тож ім’я на кшталт <img onerror=...> друкується як текст. Документ можна вставити у свою сторінку чи в iframe.

Markdown має ті самі заголовки, текст і таблиці. Рівні заголовків збережені: # це назва звіту, ## розділ, ### підрозділ, у тому самому порядку, що й у PDF, тож поділ за рядками, що починаються з ## , дає розділи. Таблиці у форматі GitHub. Малюнок (колесо, план) пропущено, на його місці один рядок примітки. Кожен символ, який Markdown чи рендерер з HTML усередині прочитав би як розмітку, екранується зворотною скісною рискою.

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

Посилання на PDF живе 24 години. Щоб віддати клієнту посилання на довше, додайте ?retain_days=30 (до 90): файл лежатиме стільки днів, а expires_at у відповіді це покаже. Безстроково ми чужі документи не хостимо, а видалити файл раніше можна через DELETE /v1/reports/files/{filename}, безкоштовно. Файл містить те, що ви надіслали, разом з ім’ям, тому строк зберігання описаний у DPA, розділ 2. GET /v1/reports/history безкоштовно показує останні експорти цього ключа, і протермінований запис приходить з expired: true.

Ваш бренд, не наш

whitelabel приймає об’єкт із 15 полів: companyName, companyUrl, companyEmail, companyMobile, companyBio, logoUrl, frontImage, reportName, footerText, fontPairing і п’ять кольорів (themeColor, headingColor, textPrimaryColor, textSecondaryColor, backgroundColor).

Передати його можна прямо в запиті, і тоді жодного налаштування акаунта не потрібно:

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

У згенерованому документі назва студії, власний заголовок звіту, акцентний колір у заголовках секцій і ваш підвал. Слова AstroWay у ньому немає жодного разу.

Альтернатива для тих, хто не хоче повторювати об’єкт у кожному запиті: whitelabel: true бере збережену конфігурацію акаунта. Задайте її на сторінці Брендинг звітів у кабінеті: назва компанії, назва звіту, контакти, логотип і два кольори, з превʼю зразка натального звіту. Ті самі налаштування доступні з ключем через /v1/whitelabel/config і /v1/whitelabel/logo, а POST /v1/whitelabel/preview малює зразок у PDF. Поле, передане в об’єкті, має перевагу над збереженим.

Готовий застосунок, який можна клонувати

Живе демо і код на GitHub, MIT.

Стіл практика: дані клієнта зліва, готовий PDF справа. Кожна плитка звіту показує ціну в кредитах до кліку й веде на готовий зразок. White-label вмикається галочкою. Бекенд це один маршрут без залежностей, бо саме в ньому суть: браузер не може звернутися до API напряму, тож ключ живе на сервері.

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

Чотири речі, які варто забрати. Ціна показана там, де ухвалюється рішення: сервер віддає X-Credits-Used назад на сторінку, а не тільки в лог. Шістнадцять звітів мають чотири форми запиту, а не шістнадцять. Той самий запит удруге коштує нуль, бо кеш відповідей віддає той самий файл. І ALLOWED_REPORTS обмежує, що саме інстанс погодиться рендерити: публічне демо рендерить лише розклад Таро (/v1/reports/tarot, 100 кредитів), бо сторінка у відкритому інтернеті, яка робить натальний звіт (/v1/reports/natal, 5 000) будь-кому, витрачає місячний безкоштовний ліміт за два кліки.

Мови

Поле language приймає 21 код. Повністю перекладені три: українська, англійська, російська. Для решти вісімнадцяти локалізуються назви знаків, а заголовки й пояснення лишаються англійськими: німецький звіт напише “Löwe” під заголовком “Planets”.

Ми пишемо це прямо, бо звіт це документ, який ваш клієнт залишає собі. Продати його як німецький, побачивши німецькі назви знаків у прикладі, було б неприємним відкриттям на боці клієнта, а не на нашому. Звіт muhurta поки що англійський цілком. Звіти vastu, bazi, numerology, kundli-matching і chinese-year написані українською та англійською; з будь-якою іншою мовою приходить англійський документ, а не українські заголовки над англійськими даними. Ім’я для numerology пишіть латиницею: таблиці літер знають лише A-Z, і ім’я іншим письмом повертає 400 NAME_NOT_LATIN, а не нулі.

Обережно

Виміряно 2026-09-20. Якщо вам потрібна конкретна мова повністю, напишіть: черга ручних перекладів іде за попитом, а не за списком.

Скільки звітів виходить на плані

/v1/reports/natal і решта PDF коштують 5 000 кредитів, тож місячний ліміт плану переводиться в кількість звітів просто:

План	Кредитів/міс	PDF-звітів	Таро-звітів
Free	10 000	звіти недоступні	недоступні
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

На Free звіти закриті навмисно: кожен PDF це секунди рендера на нашому боці, і безкоштовний тариф їх не покриває. Найдешевший вхід це Indie за $5.

Reports Pack це окремий додаток для тих, кому потрібні тільки звіти: $99 на місяць, 1 500 000 кредитів, тобто 300 PDF по 33 центи за штуку, з white-label. Це дешевше за PDF, ніж на Pro, бо ключ не ходить нікуди, крім звітів. Ключ такого плану ходить лише в /v1/reports/* і /v1/whitelabel/*.

Перепродаж звітів: скільки вам коштує PDF

Якщо ви продаєте звіти своїм клієнтам, важить одне число: скільки вам коштує один PDF на вашому обсязі. У межах ліміту плану це ціна плану, поділена на кількість PDF. Понад ліміт кожен PDF іде як овередж, який рахується за кожні 10 000 кредитів понад ліміт, тож PDF за 5000 кредитів коштує половину ставки овереджу плану.

План	PDF у плані	Ціна PDF у межах	Кожен PDF понад
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

Тож найдешевший план залежить від того, скільки PDF на місяць ви продаєте, з овереджем включно:

PDF на місяць	Найдешевший план	Ваші витрати	За 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

Точки перемикання: Starter вигідніший за Indie від 16 PDF, Pro за Starter від 57, Reports Pack за Pro від 187, якщо вам не потрібно нічого, крім звітів, Business за Reports Pack від 367. Pro і Business відкривають ще й решту API, Pack лише звіти та white-label.

Маржу ставите ви. На 300 PDF у Reports Pack ваші витрати $99 на місяць. По $9 за штуку це $2700 доходу проти $99 витрат, по $19 це $5700. Роздрібну ціну ми не радимо, але арифметика однакова за будь-якої: ваша ціна мінус 33 центи.

Розширений натальний звіт коштує вдвічі більше за стандартний, тож на кожному плані вище це подвійна ціна за PDF: $0.66 у Reports Pack.

Дві речі знижують реальні витрати ще. Повторний запит з тими самими даними повертає той самий файл із кешу відповідей і нічого не коштує, тож клієнт, який завантажив звіт двічі, оплачується один раз. А річний план це 12 місяців за ціною 9, і Reports Pack виходить $0.25 за PDF.

Перш ніж продавати, відкрийте зразки: кожен це саме той файл, який повертає API, а з whitelabel ваша назва й кольори стають на місце типових.

Якщо потрібен текст, а не документ

П’ять ендпоінтів повертають AI-наратив як JSON, без верстки й без PDF: /v1/reports/ai/natal-narrative, /transit-narrative, /synastry-narrative, /year-ahead-narrative, /monthly-narrative. По 250 кредитів. Беріть їх, коли текст іде у ваш власний макет, застосунок або розсилку.

Натальний звіт уміє й змішаний режим: enrich: true додає AI-наратив усередину PDF. На тій самій тестовій карті це 5 сторінок замість 3.