Saltar al contenido
Blog

Manejo de errores de la API de un motor de reservas: tres fallos que cuestan dinero

Redacción de Tekravel
Escrito con la ayuda de IA

El ticket de soporte llega un jueves por la noche. Un cliente pagó, la página giró y luego mostró un error genérico. La tarjeta fue cargada. Sus logs muestran un POST al proveedor que nunca recibió respuesta. ¿La aerolínea retuvo un asiento? Nadie puede decirlo, y el cliente espera. Un buen manejo de errores de la API de un motor de reservas es sobre todo el trabajo de no llegar nunca a esa situación, o al menos de saber exactamente qué hacer cuando se llega.

La mayoría de las guías de integración tratan los errores como un catálogo de códigos de estado. En reservas, los códigos son la parte fácil. Lo que cuesta dinero es un puñado de situaciones en las que la solicitud parece haber fallado y el mundo cambió igualmente, o parece haber funcionado y no cambió nada. Tres importan más que el resto.

Fallo uno: el precio se movió entre la búsqueda y la reserva

Un resultado de búsqueda es una cotización, no un contrato. Las tarifas están en caché, el inventario se comparte entre todos los canales del proveedor y la cifra que mostró hace unos minutos puede estar vencida. El proveedor se lo dice en el paso de crear la reserva, a veces con una respuesta clara de «tarifa modificada», a veces devolviendo en silencio otro total dentro de una respuesta por lo demás exitosa.

La segunda variante es la peligrosa. Si su código lee la confirmación, guarda la reserva y cobra al cliente el importe que vio, la diferencia sale de su margen o, más tarde, de un ADM. La regla es simple: compare el total que confirma el proveedor con el total que aceptó el cliente, siempre, en código, antes de capturar el pago.

Qué hacer cuando difieren depende del tamaño de la brecha y de quién la asume. Unos céntimos de redondeo entre monedas son una tolerancia que se fija una vez. Cualquier cosa mayor vuelve al cliente con un precio nuevo y un botón de aceptación explícito. Nunca la absorba automáticamente, nunca la cobre automáticamente.

Fallo dos: reservado, pero no emitido

Que exista un PNR no significa que exista un billete. Muchos flujos crean primero la reserva y emiten el e-ticket en un paso aparte, con un límite de tiempo entre ambos. Si el pago pasa y la emisión falla, usted tiene el dinero de un cliente y una reserva que caducará con su propio reloj.

Este fallo rara vez es ruidoso. La llamada de emisión devuelve un error o un timeout, y la reserva queda en un estado que su base de datos llama «pagada» mientras el proveedor sigue diciendo «retenida». Mientras tanto corre el límite de emisión y, a diferencia de su cola de soporte, la aerolínea no espera.

Trátelo como un estado propio, no como una variante del éxito o del fracaso. Una reserva necesita al menos estos: creada, retenida, pago capturado, emitiendo, emitida, fallida y reembolsable. «Pago capturado, emitiendo» es el estado que necesita un temporizador: si una reserva lleva allí demasiado, un proceso debe releerla en el proveedor y decidir, sin esperar a que un humano lo note. La decisión es barata cuando conoce el límite del proveedor, porque le dice cuánto puede reintentar con seguridad antes de reembolsar.

Fallo tres: el timeout con resultado desconocido

Es el ticket del jueves por la noche. Su solicitud salió; no volvió respuesta; la conexión se cayó o el gateway se rindió. El proveedor pudo procesarla por completo, en parte o nada.

La tentación es reintentar. No repita a ciegas una llamada de creación: el segundo intento puede producir una segunda reserva, y un duplicado cuesta de verdad: dos asientos retenidos, quizá dos billetes emitidos, una disputa de reembolso sobre uno.

El orden seguro es parar, leer, decidir. Detenga el flujo del cliente con un estado honesto como «estamos confirmando su reserva». Lea el lado del proveedor buscando la reserva con la referencia que generó antes de la llamada (por eso crea primero su propia referencia de cliente y la envía si el proveedor la acepta). Solo entonces decida: si la encuentra, continúe desde el estado real; si no existe tras la ventana de procesamiento del proveedor, es seguro reintentar una vez.

Si el proveedor no permite buscar por su referencia, busque por nombre del pasajero, ruta y fecha en una ventana estrecha y trate una coincidencia como encontrada. Feo, pero mucho más barato que un duplicado.

Una tabla de decisión con la que puede discrepar

Lo que veLo que sabeQué hacerQué no hacer
El proveedor devuelve «tarifa modificada»No se reservó nadaMostrar el nuevo total, pedir aceptación, relanzar la creaciónReenviar con el precio viejo esperando que pase
Éxito, pero el total difiere del aceptadoExiste una reserva al nuevo precioRetener el pago, preguntar al cliente, anular la reserva si rechazaCapturar el importe viejo y asumir la diferencia
Pago capturado, la emisión fallaExiste un PNR, estado del billete desconocidoReleer la reserva, reintentar la emisión dentro del límite, reembolsar despuésMarcar la reserva como fallida y olvidar el PNR
Timeout al crearResultado desconocidoBuscar por su referencia, luego continuar o reintentar una vezReintento ciego inmediato
Timeout al cancelarPuede seguir siendo responsable del segmentoReleer el estado antes de decirle algo al clienteMostrar «cancelada» porque se hizo clic

Una fila discutible: algunos equipos reembolsan al primer error de emisión para calmar al cliente. Es defendible en billetes baratos y un mal hábito en los caros, porque puede perder una tarifa que habría salvado un minuto después.

Cuánto le cuesta equivocarse

Cada fallo tiene su factura. Un cambio de precio ignorado es margen perdido en cada reserva que toca, a menudo sin notarlo hasta la conciliación. Un caso reservado-no-emitido es un cliente que llega al aeropuerto con una reserva caducada y un cargo en la tarjeta: contracargo y problema de reputación a la vez. Un reintento ciego tras un timeout es una reserva duplicada, y las aerolíneas auditan los duplicados; un patrón de ellos acaba en un ADM.

Nada de esto es exótico. Es la fontanería sin brillo que separa una demo de algo que puede dejar funcionando todo un fin de semana.

Construya el proceso de conciliación antes de necesitarlo

Los tres fallos terminan igual: su base de datos y la del proveedor discrepan. Escriba entonces el proceso que las compara antes del primer incidente, no después. Una pasada nocturna es el mínimo; cada pocos minutos para lo que esté en estado transitorio es mejor. Lista las reservas atascadas en retenida, emitiendo o desconocida, pregunta al proveedor y repara el registro o abre un ticket con la evidencia adjunta.

Guarde cada solicitud y respuesta de las llamadas de reserva, incluidos los timeouts, con la referencia enviada. Cuando un cliente disputa un cargo, ese log es su argumento. También mantiene honesta la conversación sobre la latencia: vea qué puede y qué no puede arreglar de la latencia de una API para entender por qué los timeouts son un hecho y no un bug a erradicar.

Si aún decide cómo cablear la conexión con el proveedor, la guía de integración de una API de reservas de vuelos cubre el orden de llamadas que este artículo supone. Y si quiere hablar de cómo se corresponden estos estados con nuestras API de vuelos y hoteles, el acceso empieza con una conversación: vea la página de la API de viajes.

Redacción de Tekravel

Mesa de tecnología de viajes

La mesa de tecnología de viajes de Tekravel escribe para el sector: propietarios de agencias, consolidadores y los desarrolladores que los integran. Cada artículo se comprueba contra la plataforma que describe antes de publicarse.