AirportFusion

Inicio rápido de la API

Integra la búsqueda de vuelos directos de dirección a dirección en tu propio producto con la API REST de AirportFusion. Esta guía te lleva desde cero hasta tu primera solicitud con éxito.

1. Crea una cuenta y una clave de API

  1. Regístrate (o inicia sesión) y abre el Panel de desarrollador.
  2. Ve a Claves de API → Crear clave, dale un nombre (p. ej., «staging») y elige un plan — el plan Free no requiere datos de pago.
  3. Copia la clave inmediatamente: se muestra una sola vez. Nosotros almacenamos únicamente un hash de ella.

Las claves tienen la forma af_live_xxxxxxxx…. Los primeros 12 caracteres (el prefijo) permanecen visibles en tu panel para que puedas distinguir unas claves de otras.

2. Autentícate

Envía la clave con cada solicitud, ya sea como token Bearer o en una cabecera X-Api-Key:

curl -H "Authorization: Bearer af_live_YOUR_KEY" \
  "https://your-airportfusion-host/api/v1/search?origin=Lyon&destination=Lisbon&originRadiusKm=100&destRadiusKm=150"

3. Tu primera búsqueda

GET /api/v1/search acepta:

| Parámetro | Obligatorio | Descripción | | --- | --- | --- | | origin | sí | Dirección, ciudad, punto de interés o lat,lon | | destination | sí | Igual que origin | | originRadiusKm | sí | Uno de 50, 100, 150, 200, 300, 500, 1000 | | destRadiusKm | sí | Las mismas opciones | | departureDate | no | YYYY-MM-DD, no puede estar en el pasado | | passengers | no | 1–9, por defecto 1 | | locale | no | en, fr, es, zh — determina el idioma del consejo de la IA |

4. Lee la respuesta

Todos los endpoints devuelven una envoltura consistente:

{
  "ok": true,
  "data": {
    "searchId": "…",
    "origin": { "displayName": "Lyon, France", "lat": 45.76, "lon": 4.83 },
    "destination": { "displayName": "Lisboa, Portugal", "lat": 38.72, "lon": -9.14 },
    "originAirports": [ { "iata": "LYS", "distanceKm": 22.1 } ],
    "destinationAirports": [ { "iata": "LIS", "distanceKm": 6.9 } ],
    "routes": [
      {
        "id": "…",
        "flight": { "airlineCode": "TP", "estimatedDurationMinutes": 155, "estimatedPrice": 178.0 },
        "totals": { "estimatedCost": 214.5, "estimatedMinutes": 305, "currency": "EUR" },
        "score": 8.7
      }
    ],
    "meta": { "routeCount": 12, "durationMs": 840 }
  }
}

Los errores usan la misma envoltura con ok: false:

{ "ok": false, "error": { "code": "validation_error", "message": "originRadiusKm must be one of …" } }

5. Límites de tasa y cuotas

Cada respuesta incluye cabeceras de límite de tasa:

  • X-RateLimit-Limit, X-RateLimit-Remaining — tu ventana por minuto;
  • con 429, Retry-After te indica cuándo reintentar.

Las cuotas mensuales se restablecen el día 1 de cada mes natural (UTC). Sigue el uso en vivo desde el panel.

6. Códigos de error que debes gestionar

| HTTP | Código | Significado | | --- | --- | --- | | 401 | invalid_api_key | Clave ausente, revocada o mal formada | | 422 | validation_error | Parámetros incorrectos — detalles en error.details | | 429 | rate_limited | Límite por minuto alcanzado — respeta Retry-After | | 429 | quota_exceeded | Cuota mensual agotada — mejora de plan o espera | | 500 | internal_error | Culpa nuestra — seguro reintentar con backoff |

7. Buenas prácticas de convivencia

  • Almacena en caché las búsquedas idénticas en tu lado durante un máximo de 24 horas.
  • Recuerda que todo valor es una estimación — muéstralo como tal a tus usuarios.
  • Las integraciones Free/Starter/Pro deben mostrar una atribución «Powered by AirportFusion» (consulta las Condiciones de la API).

¿Preguntas? El canal de soporte para desarrolladores de tu panel es la vía más rápida para contactarnos.