Integración de API de reserva de vuelos: lo que la doc no cuenta

La tarjeta en el tablero dice solo «añadir vuelos». Ya has entregado una integración de pagos, una de tarifas de envío, quizá una de mapas, y el modelo mental que traes es el obvio: buscar, mostrar resultados, cobrar la tarjeta, listo. Entonces la primera reserva real vuelve con un precio distinto al de la página de resultados, la segunda se queda en timeout y nadie sabe decir si el cliente tiene asiento, y alguien de operaciones pregunta por qué hay una reserva pero no un billete. Una integración de API de reserva de vuelos parece, desde fuera, un checkout de comercio electrónico. Por debajo es una transacción distribuida contra sistemas diseñados mucho antes de REST, y la mayoría de las sorpresas nacen de esa distancia.
Este texto es para el desarrollador que nunca ha visto un PNR. No trata de los endpoints de un proveedor concreto: los nombres cambian de un proveedor a otro, la forma no.
La secuencia de llamadas de una integración de API de reserva de vuelos
Casi cualquier API aérea, llame como llame a sus métodos, recorre los mismos cuatro pasos. Trazar bien las fronteras entre ellos es la mayor parte del trabajo.
| Paso | Qué te devuelve | Qué debes guardar | Qué falla |
|---|---|---|---|
| Búsqueda | Itinerarios con un precio y una clave de oferta o tarifa opaca | Nada duradero: los resultados caducan rápido | Tratas el precio como definitivo; la clave expira antes del pago |
| Cotización / verificación | El precio confirmado, las reglas de tarifa, el equipaje y a veces campos obligatorios del pasajero | La oferta verificada y su caducidad | El precio cambió; la clase se agotó; las reglas difieren de lo mostrado |
| Reserva | Una reserva —el PNR— con un localizador y un plazo de emisión | Tu propia referencia, el localizador, el plazo y los datos de pasajeros tal cual se enviaron | Timeout sin respuesta; PNR duplicados; nombres rechazados |
| Emisión | Los números de billete electrónico; aquí es donde el dinero se compromete de verdad | Cada número de billete, ligado al pasajero y al segmento que le corresponde | Emisión parcial; reserva cancelada por la aerolínea porque venció el plazo |
La fila que se discute es la tercera, porque muchas API permiten reservar y emitir en una sola llamada. Úsala si quieres. Aun así, en el mundo de las aerolíneas son dos cosas distintas: un PNR puede existir sin billete, y la emisión puede fallar después de crearse el PNR. Un endpoint combinado solo esconde el momento en que una cosa salió bien y la otra no; tu modelo de datos sigue necesitando un lugar para ese estado.
Fíjate también en lo que la búsqueda no devuelve: una promesa. Es un anuncio. La cotización es el presupuesto, y solo el billete es la venta.
Por qué el precio buscado no es el precio reservado
Un desarrollador web espera un catálogo. El inventario aéreo no lo es. Un vuelo se vende por clases de reserva, cada una un cupo de asientos a una tarifa, y la aerolínea abre y cierra esos cupos continuamente a medida que el avión se llena. Los resultados se arman rápido a partir de disponibilidad que ya puede ir un poco atrasada; para cuando el usuario termina de escribir dos pasaportes, el cupo más barato de ese vuelo puede haberse cerrado. Cuando corre la cotización, vuelve a preguntar, y la respuesta honesta a veces es más alta.
Los impuestos tienen su propia deriva. Se recalculan en la cotización para los pasajeros y la ruta exactos, y un niño o un bebé se tarifican distinto del adulto que supuso la búsqueda. Si tu tienda muestra una moneda distinta de la del proveedor —por ejemplo, el sitio en EUR o MXN y el proveedor en USD—, la conversión es otro punto donde la cifra se mueve.
La consecuencia de diseño es simple y se salta a menudo: nunca cobres sobre el precio de búsqueda. Ejecuta la cotización antes del pago, compara y, si el importe cambió, muestra la cifra nueva y pregunta. El margen que apliques debe recalcularse sobre la tarifa recotizada, no arrastrarse desde la página de resultados: es la misma lógica que sigue una agencia al definir su estrategia de margen online, y se rompe igual cuando la base se mueve debajo.
Idempotencia, y qué significa un timeout durante la reserva
Esta es la sección para leer dos veces.
Cuando una llamada de reserva hace timeout, no sabes qué pasó. Quizá la petición nunca llegó. Quizá llegó y falló. O —el caso que duele— llegó, el proveedor creó el PNR con la aerolínea y la respuesta se perdió de vuelta hacia ti. Para tu código, los tres casos son idénticos. Para la aerolínea, el tercero es una reserva viva que retiene asientos a nombre de tu cliente.
El reflejo que traes de otras integraciones es reintentar. Aquí, un reintento a ciegas puede generar un segundo PNR para los mismos pasajeros en el mismo vuelo. Las aerolíneas tratan las reservas duplicadas como una infracción de sus normas; según el transportista y los acuerdos de la agencia, la consecuencia va desde la cancelación automática de una o ambas reservas hasta una nota de débito —una ADM— enviada a quien las emitió. La agencia que la reciba querrá saber por qué tu sistema reservó dos veces.
Lo que funciona, más o menos en este orden:
- Crea tu propia referencia de reserva antes de llamar afuera, persístela y envíala con la petición siempre que la API acepte una referencia de cliente. Si la API admite una clave de idempotencia, úsala; si no, tu referencia sigue siendo lo que te permite buscar la reserva después.
- Modela explícitamente el estado desconocido. Pendiente, confirmada, fallida… y desconocida. Un timeout lleva la reserva a «desconocida», no a «fallida».
- Resuelve lo desconocido preguntando, no repitiendo. Recupera la reserva por tu referencia, o lista las reservas recientes de esos pasajeros, antes de decidir si reintentar.
- Ejecuta un proceso de conciliación que recorra todo lo que siga desconocido, lo compare con lo que informa el proveedor y mande a una cola humana lo que no pueda resolver, en lugar de adivinar.
Los timeouts de emisión son el mismo problema con dinero de por medio. Si capturas la tarjeta antes de emitir y la emisión se cuelga, tienes un cliente que pagó y quizá ningún billete. Si emites antes de capturar y la captura falla, has emitido un documento que alguien tendrá que pagar a la aerolínea. La forma habitual es autorizar la tarjeta, emitir y capturar si todo sale bien; lo importante es decidirlo a propósito, no descubrirlo en producción.
Los conceptos del viaje que sorprenden a los desarrolladores web
Ninguno es difícil. Cada uno le ha costado una semana a alguien que no sabía que existía.
Un PNR no es un billete
El PNR es el registro de la reserva: pasajeros, segmentos, contactos, un plazo. El billete es el documento pagado que da derecho a volar. Un PNR sin emitir caduca en su plazo de emisión y los asientos vuelven a la venta, a veces sin que lo notes desde tu lado.
Los nombres son casi inmutables
Tras la emisión, la mayoría de las tarifas no permiten cambiar el nombre más allá de una corrección menor, y lo que cuenta como menor varía según la aerolínea. El nombre tiene que coincidir con el documento de viaje. Recoge apellidos y nombre por separado, no dejes que un tratamiento escrito a mano se cuele en un campo de nombre y valida antes de la llamada de reserva, no después.
Los tipos de pasajero se tarifican, no decoran
Adulto, niño y bebé son tipos de tarifa, y la edad que decide cuál aplica suele ser la del día del viaje, no la del día de la reserva. Un bebé en brazos normalmente no ocupa asiento y solo viaja con un adulto. Equivoca el tipo y la cotización falla o devuelve la tarifa equivocada.
Las horas son locales, y un segmento no es un tramo
Las horas de salida y llegada se dan en hora local de cada aeropuerto. No las conviertas a la zona horaria del usuario al mostrarlas, y no calcules duraciones restándolas sin las diferencias horarias. Un viaje contiene segmentos; un segmento con escala técnica contiene más de un tramo. Tu interfaz y tus datos tienen que ponerse de acuerdo sobre cuál de ellos es una «escala».
Después de la venta siguen pasando cosas
Las aerolíneas cambian horarios después de emitir los billetes. Una reserva correcta al emitirse puede mostrar semanas después una hora nueva, un número de vuelo nuevo o una conexión rota, y según el proveedor te enteras por una notificación, una cola o volviendo a consultar la reserva. Cuenta con que la reserva cambie cuando ya hayas dejado de mirarla.
Anular (void) no es reembolsar
Poco después de la emisión suele haber una ventana en la que el billete puede anularse como si nunca hubiera existido. Pasada esa ventana, solo cabe un reembolso según las reglas de la tarifa, que puede costar una penalización o no devolver nada. La ventana y sus reglas son del proveedor y del acuerdo de emisión; léelas antes de construir un botón de «cancelar».
Lo que cuesta equivocarse
Los fallos de una integración aérea son caros de una forma concreta: caen sobre personas, no en los logs. Una reserva duplicada se convierte en una llamada a la aerolínea y quizá en una nota de débito en la cuenta de la agencia. Un cliente cobrado sin billete se convierte en un reembolso, una queja y un riesgo de contracargo. Un billete emitido sin un pago correcto se convierte en una deuda con la aerolínea que alguien tiene que saldar. Un cambio de horario que nadie procesó se convierte en un viajero en el aeropuerto para un vuelo que salió antes.
Nada de eso aparece en una prueba del camino feliz. Escribe primero los caminos de error: el timeout durante la reserva, el precio que subió, el billete que falla después del PNR, la anulación tras un pago correcto. Si esos están resueltos, el camino feliz es la parte fácil.
Probar contra una API aérea
Los entornos de prueba de los proveedores son útiles e incompletos. Suelen estar más tranquilos que producción, así que las clases agotadas y los cambios de precio son más raros, y algunos no simulan timeouts en absoluto. Úsalos para la forma de las llamadas y los errores de validación, y luego planifica una prueba controlada en producción con reservas reales que anulas dentro de la ventana, con operaciones al tanto.
Si integrar o no es otra cuestión. Si lo que realmente necesitas es una tienda y no inventario en bruto dentro de tu propio sistema, el balance está explicado en marca blanca o motor de reservas propio, y el mismo razonamiento sirve para un portal B2B para subagentes. Si quieres el inventario en tu propio código, esta plataforma ofrece API de vuelos y hoteles, y el acceso empieza con una conversación sobre tu caso de uso, no con una clave de autoservicio; es también el momento de hacer cada una de las preguntas de arriba.