Reports V2: một endpoint thay vì mười hai - `/v1/reports/generate`

12 loại báo cáo PDF - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - cho đến gần đây vẫn tồn tại như 12 route riêng biệt. Mỗi loại có schema riêng, chart-payload riêng, và pricing tier riêng. Điều này tuân thủ đúng chuẩn REST, nhưng tạo ra vấn đề DX ở hai cấp độ:

1. Bề mặt SDK. TypeScript client mang theo 12 phương thức client.reports.natal(), client.reports.synastry(), … Mỗi loại báo cáo mới = breaking change trong public API SDK (phiên bản nhỏ với phương thức mới).
2. MCP catalog. Hosted MCP server hiển thị 686 công cụ: mỗi loại trong 12 báo cáo chiếm một mục tool riêng. AI agent đi qua MCP phải quét 12 mô tả công cụ để chọn đúng. Điều này gây nhiễu trong tool selection.

Endpoint mới POST /v1/reports/generate - một dispatcher duy nhất với enum report_type.

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "natal",
    "chart": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52,
      "name": "Test"
    },
    "language": "uk",
    "whitelabel": {
      "themeColor": "#ff5500",
      "reportName": "My Cosmic Map"
    }
  }'

12 giá trị hợp lệ report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Các loại khác nhau yêu cầu các payload-field khác nhau. Dispatcher thực hiện xác thực trong handler và trả về 400 được định kiểu:

Tức là report_type không chỉ điều hướng render route mà còn điều chỉnh các quy tắc xác thực trên body request.

Tương thích ngược hoàn toàn: tất cả 12 endpoint theo loại vẫn còn hoạt động. /v1/reports/generate mới là bề mặt bổ sung, không phải thay thế. Điều này có nghĩa là mã hiện tại không bị hỏng, nhưng mã mới có thể được viết ngắn gọn hơn:

// Стара модель - direct method per type
const pdf1 = await client.reports.natal.create({ chart, whitelabel });
const pdf2 = await client.reports.synastry.create({ chart1, chart2 });
const pdf3 = await client.reports.tarot.create({ seed: "abc" });

// V2 - generic dispatcher
const pdf1 = await client.reports.generate({ report_type: "natal", chart, whitelabel });
const pdf2 = await client.reports.generate({ report_type: "synastry", chart1, chart2 });
const pdf3 = await client.reports.generate({ report_type: "tarot", seed: "abc" });

Cái nào tốt hơn phụ thuộc vào use-case. Phương thức trực tiếp cung cấp type narrowing tốt hơn (TS compiler biết rằng client.reports.synastry.create() yêu cầu chart1 + chart2). Generic-dispatcher cung cấp diện tích bề mặt nhỏ hơn cho các use-case động - ví dụ khi người dùng chọn loại báo cáo qua UI dropdown và bạn không muốn 12 lần switch trong client code.

Trên hosted MCP server (mcp.astroway.info) có 12 công cụ riêng biệt, mỗi công cụ có mô tả đầy đủ các tham số. Sau khi thêm generate, chúng tôi không xóa các công cụ cũ (tương thích ngược) - nhưng công cụ mới astroway_reports_generate có một mô tả duy nhất với enum report_type:

Tool: astroway_reports_generate
Description: Generates a PDF/HTML astrology report. Pass report_type to select template.
Parameters:
  report_type (enum): "natal" | "transit-yearly" | "synastry" | "business" | ...
  chart (object, required for most types): birth chart data
  chart1, chart2 (objects, required for synastry)
  language (string): "uk" | "en" | ...
  whitelabel (boolean | object): branding override

Khi nhận nhiệm vụ “tạo cho tôi báo cáo natal cho ngày X”, AI agent nhận được một ứng cử viên với descriptor rõ ràng, thay vì 12 ứng cử viên với mô tả chồng chéo. Điều này cải thiện độ chính xác tool selection ở cấp agent.

Dispatcher không thêm chi phí riêng. Mỗi report_type được chuyển tiếp đến renderer nội bộ tương ứng, có pricing tier riêng:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → các tier tương ứng
• tarot → TIER_4

Để xem số credit cụ thể, truy cập trang Pricing. Lệnh gọi POST /v1/reports/generate với report_type: "natal" có giá trị chính xác bằng lệnh gọi trực tiếp POST /v1/reports/natal.

Chế độ whitelabel: BrandingObject inline mới (phát hành 2026-05-19) hoạt động qua generic dispatcher không thay đổi:

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "synastry",
    "chart1": { ... },
    "chart2": { ... },
    "whitelabel": {
      "companyName": "Acme Astrology",
      "logoUrl": "https://cdn.example.com/logo.png",
      "themeColor": "#ff5500"
    }
  }'

Một dispatch + một inline whitelabel = tích hợp white-label đầy đủ với bề mặt SDK tối thiểu.

GenerateReport là một thành phần riêng trong /v1/openapi.json. Nó sử dụng oneOf với report_type discriminator, cung cấp codegen chính xác trong Python (Pydantic) và PHP (typed unions qua psalm/phpstan-style hints).

Phiên bản codegen SDK tiếp theo sẽ thêm phương thức client.reports.generate() trong cả ba gói (TS / Python / PHP). Cho đến lúc đó, bạn có thể gọi qua generic HTTP client trong SDK của mình - payload được tài liệu hóa trong OpenAPI.

Không có sự cấp bách migration riêng - direct endpoints không bị deprecated. Đây chỉ là cải tiến DX cho những người thấy bề mặt 12-method gây khó chịu.