FAQ answers

Generalidades

¿Qué es la API de AstroWay?

API HTTP profesional para cálculos astrológicos. 748 endpoints basados en Swiss Ephemeris (WASM): cartas natales, sinastría, progresiones, direcciones, tránsitos, Human Design, astrocartografía, rectificación e interpretaciones con IA. Todos los cálculos se realizan en el servidor: sin dependencias en el lado del cliente.

¿Para quién es esta API?

Para desarrolladores que construyen aplicaciones astrológicas (web/móvil), empresas de IA que añaden funciones astrológicas, astrólogos profesionales con scripts y investigadores que necesitan acceso programático a los cálculos.

¿Qué precisión tienen los cálculos?

Swiss Ephemeris garantiza una precisión en las posiciones planetarias de hasta ±1 segundo de arco y en los cúspides de casas de hasta ±1 minuto de arco. Los resultados están verificados frente a Astrodienst (Astro.com), Solar Fire, Zet 9 y Kepler. Desviación inferior a un segundo de arco frente a los ephemeris de la NASA JPL y el Catálogo de Eclipses de 5 Milenios de la NASA.

¿Cómo se compara AstroWay con Astro.com o Solar Fire?

Motor idéntico de Swiss Ephemeris: el mismo que en Solar Fire (licencia de $495), Kepler ($995), Astro Gold ($29.99/mes) y Astrodienst (Astro.com). Validado frente a los ephemeris de la NASA JPL y el reference swetest oficial de Astrodienst. Desviación inferior a 0.1 segundos de arco en posiciones planetarias y ≤1 minuto en eclipses. Diferencia: AstroWay es una API REST desde $5/mes en lugar de una licencia única o una interfaz de escritorio.

¿Qué sistemas de casas se admiten?

15 sistemas: Placidus (por defecto), Koch, Whole Sign, Equal, Regiomontanus, Campanus, Topocéntrico, Alcabitius, Morinus, Porfirio, Vehlow, Krusinski-Pisa, Bhava Hindú, APC y Equal desde MC. Pasa el código correspondiente en el parámetro houseSystem.

Créditos y facturación

¿Cómo funciona el sistema de créditos?

Cada endpoint tiene un coste fijo en créditos (de 10 a 500), dependiendo de la complejidad del cálculo. Una consulta simple son 10 créditos, una carta natal 20, una sinastría 50 y una rectificación 500. Consulta la tabla completa en la página de Tarifas.

¿Hay un plan gratuito?

Sí. El plan Free incluye 10 000 créditos/mes y 10 req/min. No requiere tarjeta de crédito. Es suficiente para evaluar el producto y prototipar.

¿Qué ocurre cuando se agotan los créditos?

En el plan Free, las solicitudes se bloquean hasta el próximo mes (429 CREDITS_EXHAUSTED). En los planes Indie/Starter/Pro/Business se activa el overage: $5/$3/$2 por cada 10 000 créditos adicionales.

¿Se cachean las solicitudes idénticas?

Sí. Una entrada idéntica dentro de 5 minutos se devuelve desde la caché sin consumir créditos. Se confirma con el encabezado X-Cache: HIT.

¿Puedo comprar créditos sin suscripción?

Por ahora, no. La suscripción ofrece un presupuesto predecible y un mejor límite de tasa. Se planea un plan pay-as-you-go.

Técnico

¿Qué SDK están disponibles?

• Servidor MCP ✅ lanzado: npx -y @astroway/mcp - expone todos los 748+ endpoints como herramientas para Claude Desktop, Cursor, GPT y otros agentes de IA compatibles con MCP
• SDK TypeScript ✅ lanzado: npm install @astroway/sdk - tipos + autocompletado con OpenAPI 3.1, reintentos + idempotencia, errores estilo Stainless
• SDK Python ✅ lanzado: pip install astroway - Astroway síncrono + AsyncAstroway asíncrono, basado en httpx, tipado PEP 561
• SDK PHP ✅ lanzado: composer require astroway/sdk - PHP 8.1+, Guzzle 7 + PSR-18, middleware de reintentos
• Go / Ruby / Rust 📋 planeado - suscríbete a la notificación por email en la página de cada SDK (/sdk/<language>/)

El contrato de la API es REST + JSON estándar, por lo que cualquier cliente HTTP funciona sin SDK. La colección de Postman y la especificación OpenAPI 3.1 están disponibles públicamente.

¿Hay modo sandbox?

Sí. Las claves aw_test_* no consumen créditos y devuelven los mismos resultados. Ideal para desarrollo y pruebas.

¿Cuál es el límite de tasa (rate limit)?

Depende del plan: Free - 10, Indie - 30, Starter - 120, Pro - 400, Business - 1 000 req/min. Al excederse, se devuelve un 429 con el encabezado Retry-After.

¿Se admite el zodíaco sideral?

Sí. Pasa "zodiacType": "sidereal" y opcionalmente "ayanamsaId" (por defecto, Lahiri). Funciona con todos los endpoints.

¿Qué son los endpoints de Human Design?

12 endpoints para calcular Human Design: tipo, estrategia, autoridad, perfil, definición, cruz de encarnación, canales, centros, Dream Rave, Perfil Hologenético, Penta (dinámica grupal) y sensibilidad temporal. La cobertura más profunda de HD entre las APIs comerciales.

Seguridad y privacidad

¿Se guardan los datos de las solicitudes?

La API funciona sin estado (stateless): los datos como fecha/hora o coordenadas de nacimiento no se guardan tras procesar la solicitud. Solo se registran metadatos: key_id, endpoint, timestamp, latencia y créditos. No hay datos personales.

¿Cumple la API con el GDPR?

Sí. No se guardan datos. Para usuarios de la UE: no hay procesamiento de PII, ni perfilado, ni cookies. La clave de API está vinculada a la cuenta, no al usuario final.

¿Son seguras las interpretaciones con IA?

Los endpoints de IA (/interpret/*, /horoscope/*) incluyen salvaguardas integradas: prohibición de consejos médicos, legales o financieros. Cada respuesta incluye un disclaimer. Hay un registro completo de auditoría para cumplimiento empresarial.

Soporte

¿Cómo obtener ayuda?

Depende del plan: Free - comunidad, Indie - email (48 h), Starter - email (24 h), Pro - email (4 h), Business - email + Slack (1 h), Enterprise - gestor dedicado en Slack. Los contactos están en la página de Contacto.

¿Hay SLA?

Indie: 99% de tiempo de actividad. Starter y Pro: 99.9%. Business: 99.95%. Enterprise: SLA personalizado con garantías financieras.