Reports API - 16 báo cáo PDF hoàn chỉnh mang thương hiệu của bạn

Last updated 1 thg 11, 2026 Xem dưới dạng Markdown Thiết lập tác nhân

Bạn gửi ngày sinh, nhận về một tài liệu hoàn chỉnh. Không phải JSON để bạn phải tự dàn trang PDF, mà chính là file PDF: đã được dàn trang từng trang một, có logo của bạn, tên báo cáo của bạn và không hề có bất kỳ đề cập nào đến chúng tôi bên trong.

Mười sáu loại báo cáo như vậy đã sẵn sàng hoạt động. Cùng với bộ điều phối (dispatcher), lịch sử xuất file và năm loại nội dung kể chuyện bằng AI, chúng tạo thành 23 đường dẫn dưới /v1/reports/*.

Danh mục

Mỗi dòng đều có một mẫu sẵn có. Đây không phải là bản thiết kế (mockup): file được tạo ra bởi chính lệnh gọi được in trong tài liệu hướng dẫn của endpoint này, và được cập nhật cùng với các template.

Số lượng trang là số trang của chính mẫu đó, được đo vào ngày 2026-09-21. Số trang sẽ thay đổi tùy theo bản đồ: càng nhiều khía cạnh (aspects) thì càng nhiều dòng, và relocation sẽ thêm khoảng hai đến ba trang cho mỗi thành phố (4 trang cho một thành phố, 13 trang cho năm thành phố).

Endpoint	Nội dung bên trong	Số trang	Credit	Mẫu
`/v1/reports/natal`	Big Three, các hành tinh, nhà, khía cạnh	3	5 000	PDF
`/v1/reports/synastry`	Các khía cạnh giữa hai bản đồ, sự cân bằng các nguyên tố	2	5 000	PDF
`/v1/reports/transit-yearly`	Dự báo transit cho năm được chọn	5	5 000	PDF
`/v1/reports/relocation`	Bản đồ gốc, lên đến 5 thành phố, các hành tinh thay đổi nhà, các đường liên quan, 19 lĩnh vực cuộc sống	6	5 000	PDF
`/v1/reports/vedic-kundli`	Lagna và Nakshatra, vị trí sidereal, Mahadasha Vimshottari	2	5 000	PDF
`/v1/reports/lal-kitab`	Kismat, deva, các rini được phát hiện, upayee	2	5 000	PDF
`/v1/reports/gemstone`	Khuyến nghị đá quý kèm mantra, các loại đá không nên đeo, trạng thái các Graha	7	5 000	PDF
`/v1/reports/human-design`	Các thông số chính, các trung tâm, các kênh	2	5 000	PDF
`/v1/reports/muhurta`	Các ngày thuận lợi được xếp hạng cho một hoạt động	4	5 000	PDF
`/v1/reports/love`	Các điểm then chốt về tình yêu, Big Three, các khía cạnh	2	5 000	PDF
`/v1/reports/career`	Các điểm then chốt về sự nghiệp, bối cảnh cá nhân, các khía cạnh	2	5 000	PDF
`/v1/reports/money`	Các điểm tài chính then chốt, các nhà, các khía cạnh	3	5 000	PDF
`/v1/reports/business`	Các điểm kinh doanh then chốt, các nhà, các khía cạnh	2	5 000	PDF
`/v1/reports/child`	Các nét tính cách chính, Big Three, các hành tinh	2	5 000	PDF
`/v1/reports/stellaforge`	Poster bản đồ trên một trang: các hành tinh, sự cân bằng, các khía cạnh chính	1	5 000	PDF
`/v1/reports/tarot`	Mô tả trải bài và các lá bài	2	100	PDF
`/v1/reports/vastu`	Sơ đồ nhà với mandala, đánh giá, các phát hiện Vastu kèm nguồn và cách khắc phục	2	5 000	PDF

Tarot rẻ hơn năm mươi lần vì nó không sử dụng ephemeris: một trang trải bài không cần tính toán thiên văn.

Độ sâu: `standard` hoặc `extended`

/v1/reports/natal (và /v1/reports/generate với report_type: "natal") chấp nhận tham số depth. standard là tài liệu ở trên, tốn 5000 credit. extended tốn 10000 credit và thêm vòng tròn bản đồ cùng một phần cho mỗi thiên thể từ Mặt Trời đến Pluto, Chiron và Ascendant trong cung: mười hai phần, mỗi phần gồm hai đến bốn trang văn bản đã được biên tập (mẫu PDF, 13 trang) từ cùng một kho dữ liệu mà /v1/natal-texts cung cấp. Không có gì được tạo ra theo yêu cầu (on-the-fly), vì vậy cùng một bản đồ sẽ cho ra cùng một tài liệu.

Các phần được hỗ trợ bằng 20 ngôn ngữ của trang web; nếu dùng depth: "extended" với một ngôn ngữ khác, nó sẽ trả về lỗi 400 thay vì tự động điền bằng ngôn ngữ khác. Các loại báo cáo khác hiện tại chỉ có một độ sâu: các phần dài của chúng vẫn chưa được viết xong.

Một đường dẫn thay vì mười sáu

POST /v1/reports/generate chấp nhận trường report_type và thực hiện cùng một việc như các đường dẫn riêng biệt. Mười hai loại: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Đối với SDK, đây là một phương thức thay vì mười hai; đối với MCP, đây là một công cụ thay vì mười hai. Giá cả là như nhau: gọi qua bộ điều phối sẽ trừ chính xác số lượng như khi gọi đường dẫn trực tiếp.

PDF hay HTML

Theo mặc định, bạn sẽ nhận được PDF và một liên kết đến nó. ?format=html sẽ trả về một trang HTML hoàn chỉnh ngay trong phản hồi, không cần render và không cần lưu trữ: rất tiện khi bạn muốn nhúng báo cáo vào trang web của mình hoặc muốn áp dụng CSS riêng.

Liên kết đến PDF có hiệu lực trong 24 giờ. Để cung cấp liên kết cho khách hàng lâu hơn, hãy thêm ?retain_days=30 (tối đa 90): file sẽ được lưu trữ trong số ngày đó, và expires_at trong phản hồi sẽ hiển thị điều này. Chúng tôi không lưu trữ tài liệu của người khác vô thời hạn, nhưng bạn có thể xóa file sớm hơn thông qua DELETE /v1/reports/files/{filename} một cách miễn phí. File chứa những gì bạn đã gửi cùng với tên của nó, vì vậy thời hạn lưu trữ được mô tả trong DPA, mục 2. GET /v1/reports/history cho phép bạn xem miễn phí các lần xuất file gần nhất của key này, và các bản ghi hết hạn sẽ trả về expired: true.

Thương hiệu của bạn, không phải của chúng tôi

whitelabel chấp nhận một đối tượng với 15 trường: companyName, companyUrl, companyEmail, companyMobile, companyBio, logoUrl, frontImage, reportName, footerText, fontPairing và năm màu sắc (themeColor, headingColor, textPrimaryColor, textSecondaryColor, backgroundColor).

Bạn có thể truyền nó trực tiếp trong yêu cầu, và khi đó không cần bất kỳ thiết lập tài khoản nào:

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

Trong tài liệu được tạo ra, tên studio, tiêu đề báo cáo riêng, màu nhấn trong các tiêu đề phần và chân trang của bạn sẽ xuất hiện. Từ AstroWay không hề xuất hiện dù chỉ một lần.

Một lựa chọn thay thế cho những ai không muốn lặp lại đối tượng trong mỗi yêu cầu: whitelabel: true sẽ sử dụng cấu hình tài khoản đã lưu. Bạn có thể thiết lập nó tại trang Branding báo cáo trong dashboard: tên công ty, tên báo cáo, thông tin liên hệ, logo và hai màu sắc, kèm theo bản xem trước của báo cáo natal. Các thiết lập tương tự có thể được truy cập bằng key qua /v1/whitelabel/config và /v1/whitelabel/logo, còn POST /v1/whitelabel/preview sẽ vẽ một mẫu PDF. Trường được truyền trong đối tượng sẽ có ưu tiên cao hơn cấu hình đã lưu.

Ứng dụng hoàn chỉnh có thể clone

Demo trực tiếp và mã nguồn trên GitHub, MIT.

Bàn làm việc thực tế: dữ liệu khách hàng bên trái, PDF hoàn chỉnh bên phải. Mỗi ô báo cáo hiển thị giá bằng credit trước khi click và dẫn đến mẫu có sẵn. White-label được bật bằng một dấu tích. Backend là một route duy nhất không có phụ thuộc, vì bản chất nằm ở đó: trình duyệt không thể gọi trực tiếp đến API, vì vậy key phải được lưu trên 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

Bốn điều đáng chú ý. Giá được hiển thị ngay tại nơi đưa ra quyết định: server trả X-Credits-Used về lại trang web, chứ không chỉ trong log. Mười sáu báo cáo chỉ có bốn dạng yêu cầu, chứ không phải mười sáu. Cùng một yêu cầu thực hiện lần thứ hai sẽ tốn 0 credit vì cache phản hồi sẽ trả về chính file đó. Và ALLOWED_REPORTS giới hạn những gì một instance sẽ đồng ý render: bản demo công khai chỉ render trải bài Tarot (/v1/reports/tarot, 100 credit), vì một trang web mở trên internet có thể tạo báo cáo natal (/v1/reports/natal, 5 000) cho bất kỳ ai sẽ làm cạn kiệt hạn mức miễn phí hàng tháng chỉ trong hai lần click.

Ngôn ngữ

Trường language chấp nhận 21 mã ngôn ngữ. Có ba ngôn ngữ được dịch hoàn toàn: tiếng Ukraine, tiếng Anh, tiếng Nga. Đối với mười tám ngôn ngữ còn lại, tên các cung hoàng đạo được bản địa hóa, nhưng tiêu đề và giải thích vẫn giữ tiếng Anh: một báo cáo tiếng Đức sẽ viết “Löwe” dưới tiêu đề “Planets”.

Chúng tôi nói thẳng điều này vì báo cáo là một tài liệu mà khách hàng của bạn sẽ giữ lại. Việc bán nó như một báo cáo tiếng Đức nhưng khách hàng lại thấy tên các cung bằng tiếng Anh trong ví dụ sẽ là một trải nghiệm không tốt cho khách hàng, và đó là lỗi của chúng tôi. Báo cáo muhurta hiện tại vẫn hoàn toàn bằng tiếng Anh.

Số lượng báo cáo có thể tạo theo gói

/v1/reports/natal và các file PDF khác tốn 5 000 credit, vì vậy hạn mức hàng tháng của gói được quy đổi ra số lượng báo cáo rất đơn giản:

Gói	Credit/tháng	Báo cáo PDF	Báo cáo Tarot
Free	10 000	báo cáo không khả dụng	không khả dụng
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

Ở gói Free, các báo cáo bị khóa một cách có chủ đích: một file PDF tiêu tốn vài giây chạy Chrome ở phía chúng tôi, và gói miễn phí không đủ để chi trả cho việc đó. Điểm bắt đầu rẻ nhất là gói Indie với $5.

Reports Pack là một gói bổ sung riêng biệt cho những ai chỉ cần báo cáo: $99 mỗi tháng, 1 500 000 credit, nghĩa là 300 PDF với giá 33 cent mỗi file, có kèm white-label. Giá này cho PDF rẻ hơn so với gói Pro, vì key này không dùng cho bất kỳ mục đích nào khác ngoài báo cáo. Key của gói này chỉ hoạt động trong /v1/reports/* và /v1/whitelabel/*.

Bán lại báo cáo: chi phí PDF của bạn là bao nhiêu

Nếu bạn bán báo cáo cho khách hàng của mình, chỉ có một con số quan trọng: chi phí cho một file PDF dựa trên quy mô của bạn. Trong hạn mức của gói, đó là giá của gói chia cho số lượng PDF. Vượt quá hạn mức, mỗi PDF sẽ được tính theo giá trung bình (average), được tính dựa trên mỗi 10 000 credit vượt mức, vì vậy một PDF tốn 5000 credit sẽ có giá bằng một nửa mức giá trung bình của gói đó.

Gói	PDF trong gói	Giá PDF trong hạn mức	Mỗi PDF vượt mức
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

Vì vậy, gói rẻ nhất phụ thuộc vào việc bạn bán bao nhiêu PDF mỗi tháng, bao gồm cả phần vượt mức:

PDF mỗi tháng	Gói rẻ nhất	Chi phí của bạn	Mỗi 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

Các điểm chuyển đổi: Starter có lợi hơn Indie từ 16 PDF, Pro có lợi hơn Starter từ 57, Reports Pack có lợi hơn Pro từ 187 (nếu bạn không cần gì ngoài báo cáo), và Business có lợi hơn Reports Pack từ 367. Pro và Business còn mở khóa các API khác, trong khi Pack chỉ dành cho báo cáo và white-label.

Bạn là người quyết định biên lợi nhuận. Với 300 PDF trong Reports Pack, chi phí của bạn là $99 mỗi tháng. Nếu bán $9 mỗi file, bạn có $2700 doanh thu so với $99 chi phí; nếu bán $19, bạn có $5700. Chúng tôi không khuyên dùng giá bán lẻ, nhưng phép tính là như nhau: giá của bạn trừ đi 33 cent.

Báo cáo natal extended tốn gấp đôi so với standard, vì vậy ở mọi gói trên, đó sẽ là gấp đôi giá PDF: $0.66 trong Reports Pack.

Hai điều sau đây sẽ giúp giảm chi phí thực tế thêm nữa. Một yêu cầu lặp lại với cùng dữ liệu sẽ trả về chính file đó từ cache và không tốn gì cả, vì vậy một khách hàng tải báo cáo hai lần thì bạn chỉ tính tiền một lần. Và gói năm (yearly plan) là 12 tháng với giá của 9 tháng, giúp Reports Pack chỉ còn $0.25 cho mỗi PDF.

Trước khi bán, hãy xem các mẫu: mỗi mẫu chính là file mà API trả về, và với whitelabel, tên và màu sắc của bạn sẽ thay thế các thông tin mặc định.

Nếu bạn cần văn bản thay vì tài liệu

Năm endpoint trả về nội dung kể chuyện bằng AI dưới dạng JSON, không có dàn trang và không có PDF: /v1/reports/ai/natal-narrative, /transit-narrative, /synastry-narrative, /year-ahead-narrative, /monthly-narrative. Mỗi cái tốn 250 credit. Hãy dùng chúng khi bạn muốn đưa văn bản vào layout riêng, ứng dụng hoặc bản tin của mình.

Báo cáo natal còn có chế độ hỗn hợp: enrich: true sẽ thêm nội dung kể chuyện AI vào bên trong PDF. Trên cùng một bản đồ thử nghiệm, nó sẽ là 5 trang thay vì 3.