Reports V2: un endpoint en lugar de doce - `/v1/reports/generate`

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 valores válidos de report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Diferentes tipos requieren diferentes campos en el payload. El dispatcher realiza la validación en el handler y devuelve un 400 tipificado:

Es decir, report_type controla no solo la ruta de renderizado, sino también las reglas de validación para el cuerpo de la solicitud.

La compatibilidad con versiones anteriores es completa: todos los 12 endpoints específicos por tipo permanecen vivos. El nuevo /v1/reports/generate es una superficie aditiva, no un reemplazo. Esto significa que el código existente no se romperá, pero el nuevo código puede ser más compacto:

// Стара модель - 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" });

Qué es mejor depende del caso de uso. El método directo proporciona un mejor narrowing de tipos (el compilador de TS sabe que client.reports.synastry.create() requiere chart1 + chart2). El dispatcher genérico proporciona una superficie más pequeña para casos de uso dinámicos, por ejemplo, cuando el usuario selecciona el tipo de informe a través de un dropdown en la UI y no quieres un switch de 12 veces en el código del cliente.

En el servidor MCP alojado (mcp.astroway.info) había 12 herramientas separadas, cada una con una descripción completa de los parámetros. Después de agregar generate, no eliminamos las antiguas (compatibilidad con versiones anteriores), pero la nueva herramienta astroway_reports_generate tiene una sola descripción con el 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

El agente de IA al recibir la tarea “genera un informe natal para la fecha X” recibe un solo candidato con un descriptor obvio, en lugar de 12 candidatos con descripciones superpuestas. Esto mejora la precisión de la selección de herramientas a nivel de agente.

El dispatcher no agrega un costo separado. Cada report_type se reenvía a su renderizador interno, que tiene su propio nivel de precios:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → niveles correspondientes
• tarot → TIER_4

Para los números específicos de créditos, consulta la página Precios. Una llamada POST /v1/reports/generate con report_type: "natal" cuesta exactamente lo mismo que el directo POST /v1/reports/natal.

El nuevo modo inline whitelabel: BrandingObject (lanzado 2026-05-19) funciona a través del dispatcher genérico sin cambios:

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

Un dispatch + un whitelabel inline = una integración whitelabel completa con una mínima superficie del SDK.

GenerateReport es un componente separado en /v1/openapi.json. Utiliza oneOf con el discriminador report_type, lo que proporciona un codegen correcto en Python (Pydantic) y PHP (uniones tipadas a través de hints psalm/phpstan-style).

El próximo lanzamiento de codegen del SDK agregará el método client.reports.generate() en los tres paquetes (TS / Python / PHP). Hasta entonces, puedes llamarlo a través de un cliente HTTP genérico en tu SDK - el payload está documentado en OpenAPI.

No hay urgencia de migración - los endpoints directos no están deprecated. Es puramente una mejora de DX para aquellos a quienes la superficie de 12 métodos les causa problemas.