Volver a la documentación
Autenticación
Autenticación
Autenticación de la API
Todas las solicitudes a la API requieren autenticación con una clave API. Incluye tu clave en el encabezadox-api-keyen cada solicitud.
Obtener tu clave API
- Visita nuestra página de precios y elige un plan
- Selecciona el plan de suscripción que se ajuste a tus necesidades
- Abre tu panel
- Tu clave API aparecerá en la sección API Key
Base URL
https://api.freeastroapi.comEncabezados requeridos
| Encabezado | Valor | Requerido |
|---|---|---|
| x-api-key | Tu clave API | Sí |
| Content-Type | application/json | Sí (para POST) |
| Idempotency-Key | Clave de operación única generada por el cliente | No (recomendado para reintentos POST facturables) |
Reintentos seguros con Idempotency-Key
Las solicitudes astrológicas POST 请求支持 Idempotency-Key: <client-generated unique operation key>. Genera una clave por operación prevista. Reutiliza la misma clave solo cuando reintentes exactamente la misma solicitud después de un timeout o un error de red.
Node.js
const idempotencyKey = crypto.randomUUID();
await fetch("https://api.freeastroapi.com/api/v1/natal/calculate", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.FREE_ASTRO_API_KEY,
"Idempotency-Key": idempotencyKey
},
body: JSON.stringify(payload)
});Python
import uuid
idempotency_key = str(uuid.uuid4())
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
"Idempotency-Key": idempotency_key
}Ejemplos de autenticación
curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year": 1990, "month": 5, "day": 15, "hour": 10, "minute": 30, "city": "New York", "lat": 40.7128, "lng": -74.006}'Buenas prácticas de seguridad
- •Nunca expongas tu clave API en código del cliente. Realiza las llamadas a la API desde tu servidor.
- •Usa variables de entorno para almacenar tu clave API, no cadenas hardcodeadas.
- •Rota tu clave API si crees que puede estar comprometida.
- •Supervisa tu uso en el panel para detectar actividad inusual.
Errores de autenticación
| Estado | Mensaje | Descripción |
|---|---|---|
| 401 | Missing API key | No se proporcionó el encabezado x-api-key |
| 401 | Invalid API key | La clave API no existe o fue revocada |
| 429 | Rate limit exceeded | Has superado el límite de solicitudes de tu plan |
| 403 | Subscription required | Tu suscripción expiró o no está activa |
Límites de velocidad
Los límites de velocidad varían según el plan. Los siguientes encabezados se incluyen en cada respuesta:
| Encabezado | Descripción |
|---|---|
| X-RateLimit-Limit | Número total de solicitudes permitidas por periodo |
| X-RateLimit-Remaining | Solicitudes restantes en el periodo actual |
| X-RateLimit-Reset | Timestamp en el que se reinicia el límite |