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

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 ve | Lo que sabe | Qué hacer | Qué no hacer |
|---|---|---|---|
| El proveedor devuelve «tarifa modificada» | No se reservó nada | Mostrar el nuevo total, pedir aceptación, relanzar la creación | Reenviar con el precio viejo esperando que pase |
| Éxito, pero el total difiere del aceptado | Existe una reserva al nuevo precio | Retener el pago, preguntar al cliente, anular la reserva si rechaza | Capturar el importe viejo y asumir la diferencia |
| Pago capturado, la emisión falla | Existe un PNR, estado del billete desconocido | Releer la reserva, reintentar la emisión dentro del límite, reembolsar después | Marcar la reserva como fallida y olvidar el PNR |
| Timeout al crear | Resultado desconocido | Buscar por su referencia, luego continuar o reintentar una vez | Reintento ciego inmediato |
| Timeout al cancelar | Puede seguir siendo responsable del segmento | Releer el estado antes de decirle algo al cliente | Mostrar «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.