Integración de Estado de Vuelo

Informe a los pasajeros sobre los cambios en su vuelo en el momento en que ocurren: una nueva puerta de embarque, un retraso, el embarque, la llegada o una cancelación. La integración de Estado de Vuelo conecta Pushwoosh con AeroDataBox, un proveedor de datos de vuelos, para que un customer journey pueda monitorear el vuelo de un pasajero específico y reaccionar en el momento en que su estado cambie.

Se necesita asistencia de un desarrollador

Necesitará que su equipo de desarrollo envíe el evento de reserva con los atributos correctos y que construya el cuerpo de la solicitud del paso Webhook. Comparta esta guía con ellos.

Resumen de la integración

Tipo de integración

Fuente: usted suscribe una reserva a su vuelo desde dentro de un journey. Pushwoosh devuelve los cambios de estado como un evento que usted utiliza más tarde en ese mismo journey.

Requisitos previos

Antes de conectar el Estado de Vuelo, asegúrese de tener:

• Una cuenta activa de Pushwoosh con una aplicación en el centro de datos NUE de Pushwoosh. El Estado de Vuelo aún no está disponible en otros centros de datos.
• Una cuenta y clave de API de AeroDataBox. El feed se factura en su propia cuenta de AeroDataBox.
• Un evento de reserva que contenga la aerolínea, el número, la fecha y el aeropuerto de salida del vuelo (consulte Construir el journey de estado de vuelo).
• Un API Access token dedicado para que el journey se autentique.

¿Cómo funciona la integración?

Conectar la integración y monitorear un vuelo son dos pasos separados, que se realizan en momentos diferentes:

1. Conecte su clave de AeroDataBox en Ajustes → Integraciones de terceros.
2. Un evento de reserva introduce a un pasajero en su journey.
3. El paso de Webhook del journey suscribe esa reserva a su vuelo a través de la API pública de Pushwoosh.
4. Pushwoosh monitorea el vuelo con AeroDataBox y detecta cambios: puerta de embarque, retraso, embarque, llegada, cancelación o asignación de cinta de equipaje.
5. Cada cambio se entrega a la aplicación como un evento PW_FlightStatusChanged, que los elementos Wait for Trigger y Condition split del journey dirigen al mensaje correcto.

Cada suscripción a un vuelo finaliza automáticamente 36 horas después de la fecha de salida local. Puede finalizar antes: cuando el vuelo aterriza o se cancela, o cuando ya nada lo está monitoreando. Entonces Pushwoosh cancela la suscripción correspondiente de AeroDataBox, para que no siga facturando en segundo plano.

Este periodo se fija en el momento de la suscripción, a partir de la fecha de salida reservada, y no se desplaza si AeroDataBox informa más tarde de un retraso. Un retraso que lleve el vuelo al día siguiente puede hacer que la suscripción finalice antes de la salida real retrasada.

Casos de uso

El Estado de Vuelo cubre cuatro tipos de actualizaciones, cada una utilizable por sí sola o combinada en un solo journey:

• Alertas de cambio de puerta de embarque: notifique a los pasajeros en el momento en que cambie su puerta de embarque.
• Notificaciones de retraso: alerte a los pasajeros una vez que el retraso de un vuelo supere unos minutos, para que puedan ajustar sus planes.
• Actualizaciones de embarque y llegada: informe a los pasajeros cuándo se abre el embarque o cuándo aterriza su vuelo.
• Recogida de equipaje: envíe el número de la cinta de equipaje tan pronto como se asigne.

Configurar la integración

Conectar Estado de Vuelo a Pushwoosh

Conecte su clave de AeroDataBox una vez por aplicación:

1. Abra su aplicación y vaya a Ajustes → Integraciones de terceros.

2. En Servicios disponibles, busque la tarjeta Estado de Vuelo y haga clic en Configurar.

   

3. Pegue su clave de AeroDataBox en Clave de API y haga clic en Conectar.

   

Después de hacer clic en Conectar, la tarjeta se mueve a Servicios conectados.

Si la clave es rechazada

Pushwoosh verifica la clave en segundo plano. Si algo está mal, la tarjeta muestra uno de estos mensajes:

Mensaje	Causa
provider rejected the API key	La clave no es válida o fue revocada en AeroDataBox
provider account is out of credits	Su plan de AeroDataBox se ha quedado sin créditos
provider rate limit reached	AeroDataBox está limitando las solicitudes, y esto se resuelve por sí solo
provider is unavailable	No se pudo contactar con AeroDataBox, debido a un problema de red o una interrupción en cualquiera de los lados
provider refused the request	AeroDataBox devolvió un error que Pushwoosh no reconoce de otra manera

Reemplazar la clave

Vuelva a abrir la tarjeta Estado de Vuelo en Servicios conectados, por ejemplo, después de que la clave sea rechazada:

• Reemplazar la clave: pegue una nueva en Clave de API.
• Mantener la clave actual: deje Clave de API vacío. El campo muestra solo los últimos caracteres de la clave guardada.

Desconectar la integración

1. Abra la tarjeta Estado de Vuelo en Servicios conectados.
2. Elimine la clave.

Después de desconectar:

• Ya no se crean nuevas suscripciones.
• Los vuelos que los journeys ya monitorean mantienen sus suscripciones hasta que finalicen por sí solas o usted las elimine del journey.
• El recuento de suscripciones activas en la tarjeta incluye estas suscripciones hasta que finalicen.

Construir el journey de estado de vuelo

Antes de construir el journey

Asegúrese de tener:

• Un evento de reserva que contenga la aerolínea, el número, la fecha (YYYY-MM-DD) y el aeropuerto de salida del vuelo, más un atributo que contenga la clave del vuelo en formato <carrier><number>/<date>/<departure airport>, por ejemplo LH400/2026-09-20/MUC. Esto es lo que utiliza la coincidencia de sesiones a lo largo del journey.
• Un API Access token dedicado. El método de suscripción acepta cualquier token de su cuenta, sin necesidad de conceder permisos. Cree uno específicamente para este journey para poder revocarlo más tarde sin afectar a nada más.
• El host de la API pública de su centro de datos. Para las cuentas NUE, es rpc-api.svc-nue.pushwoosh.com.
• El Límite de entrada a la campaña del journey, desactivado. El límite de entrada a la campaña solo realiza un seguimiento de las entradas por usuario. No tiene conocimiento del identificador de sesión que configure a continuación, por lo que bloquearía el segundo vuelo de un pasajero hasta que pase el período límite.

Iniciar el journey desde un evento de reserva

1. Añada una Entrada basada en disparador y seleccione su evento de reserva, por ejemplo flight_booked.
2. En Controlar cuántas sesiones puede tener un usuario al mismo tiempo, elija Múltiples sesiones activas por usuario.
3. Elija el atributo de clave de vuelo como identificador de sesión. Esto permite que el mismo pasajero monitoree más de un vuelo a la vez, cada uno en su propia sesión.

Suscribir la reserva con un paso de Webhook

Añada un paso de Webhook directamente después de la entrada. El cuerpo de su solicitud extrae los campos del vuelo del evento de entrada, por lo que el paso debe situarse justo después de la entrada para poder utilizarlos.

1. Establezca TIPO DE SOLICITUD en POST.

2. Establezca la URL en https://rpc-api.svc-nue.pushwoosh.com/api/integrations/flight-status/subscriptions.

3. En CABECERAS, mantenga Content-Type: application/json.

4. Añada una cabecera Authorization: Token <su token de API>. Pushwoosh enmascara este valor después de guardar, porque cualquier cabecera llamada Authorization se trata como un secreto automáticamente. Consulte Marcar el valor de una cabecera como secreto para saber qué significa esto para la edición y el historial de versiones.

5. En DATOS, introduzca el cuerpo de la solicitud a continuación, escribiendo su propio código de aplicación directamente:

   {
     "application": "<your application code>",
     "user_id": "{{device:user_id}}",
     "source": "journey",
     "flight": {
       "carrier": "",
       "flight_number": "",
       "flight_date": "",
       "departure_airport": ""
     }
   }

6. Para cada uno de los cuatro valores vacíos de flight, abra el CONSTRUCTOR DE DATOS.

7. Seleccione la categoría Evento.

8. Elija el atributo correspondiente de su evento de reserva (aerolínea, número de vuelo, fecha de vuelo, aeropuerto de salida).

9. Copie la macro que Pushwoosh genera y péguela como el valor de ese campo. Repita para los tres valores restantes.

No necesita mapear nada de la respuesta. Devuelve flight_key, que ya está en su evento de reserva.

Precaución

Si la llamada de suscripción falla, el pasajero sale del journey en este paso, al igual que con cualquier paso de Webhook. Su vuelo no se monitorea y no recibirá ninguna de las alertas más adelante en el journey. Consulte Qué sucede cuando una solicitud falla.

Esperar una actualización de estado

Añada un paso de Esperar Disparador después del paso de Webhook.

1. Añada una rama y establezca su evento en PW_FlightStatusChanged.
2. En la coincidencia de atributos de múltiples sesiones, seleccione el mismo atributo de clave de vuelo que utilizó en la entrada. Esto asegura que una actualización de estado solo despierte al pasajero cuyo vuelo realmente concierne.
3. Establezca el período de espera para cubrir cómodamente el vuelo. 48 horas es suficiente para la mayoría de los itinerarios.
4. Deje la rama No disparado sin un siguiente paso, o añada un mensaje de respaldo. Los pasajeros cuyo vuelo no tiene ninguna actualización antes de que termine la espera salen del journey aquí, y eso es lo esperado.

Bifurcar por tipo de evento

Añada una División por Condición después del paso de Esperar Disparador.

1. Seleccione Evento como el tipo de condición.
2. En Evento del Journey, elija PW_FlightStatusChanged.
3. En Atributo, seleccione event_type.
4. Establezca la condición en es.
5. Añada una rama con el valor gate_change.
6. Haga clic en Guardar. Esto crea dos ramas: la que nombró para un cambio de puerta de embarque, y Todos los demás usuarios para todos los demás tipos de eventos.

Repita este elemento, o añada más ramas, para los otros valores de event_type sobre los que quiera actuar: delay, boarding, departed, arrived, cancelled, y baggage_ready funcionan de la misma manera.

Notificar al pasajero

Añada un elemento Push en la rama de cambio de puerta de embarque.

1. Seleccione o cree un preset de push.
2. Establezca el Tipo de mensaje en Mensaje transaccional, ya que una alerta de estado de vuelo es una notificación de servicio, no una promoción. El límite de frecuencia no se aplica, y aun así llega a los pasajeros en un grupo de control.
3. Habilite la personalización con atributos de evento.
4. Elija PW_FlightStatusChanged como el evento de origen.
5. Rellene los marcadores de posición de su preset con flight_number y gate_new.

Mostrar una tarjeta de Live Activity en su lugar

Añada tres elementos Live Activity, en lugar de Push o además de él:

• Start: justo después del paso de Webhook, no directamente después de la entrada. La entrada se conecta con un solo paso siguiente, por lo que Webhook y Start no pueden ir ambos justo después de ella.
• Update: en la rama de cambio de puerta de embarque.
• End: una vez que el journey ya no necesite rastrear el vuelo, por ejemplo tras la llegada o la cancelación.

En el elemento Start, bajo Card attributes, añada los seis campos que necesita el tipo ActivityAttributes de la tarjeta. Card attributes es una lista libre de nombres y valores, y la interfaz no comprueba los nombres, así que introduzca cada uno exactamente como aparece en la lista. Cinco de ellos ya están en su evento de reserva:

• carrier
• flight_number
• flight_date
• departure_airport
• flight_key
• arrival_airport: la llamada de suscripción no lo necesita, así que añádalo a su evento de reserva solo si usa Live Activity.

Precaución

Si falta cualquiera de los seis Card attributes, la interfaz no muestra ningún error, pero la tarjeta nunca aparece en el dispositivo. Cada Update o End posterior para ese pasajero falla entonces con el código de entrega 1031 (“push token not found for the specified Live Activity ID”).

Solo Start establece Card attributes, y permanecen iguales durante toda la vida de la tarjeta. Update y End no los establecen. Los campos que cambian, como el estado, la puerta de embarque y el retraso, son Card content, y provienen del esquema de widget que publique para esta app.

Referencia del evento PW_FlightStatusChanged

Cada cambio que la integración detecta se entrega como un evento PW_FlightStatusChanged, con todos los atributos siempre presentes: los vacíos se envían como valores en blanco, nunca se omiten.

Atributo	Tipo	Descripción
event_type	Cadena	Qué cambió (consulte los valores a continuación)
flight_key	Cadena	La misma clave de vuelo que estableció en el evento de reserva
flight_number	Cadena	El número de vuelo
departure_airport	Cadena	Código del aeropuerto de salida
arrival_airport	Cadena	Código del aeropuerto de llegada
status	Cadena	Estado actual del vuelo (consulte los valores a continuación)
gate_old / gate_new	Cadena	Puerta de embarque antes y después del cambio
terminal_old / terminal_new	Cadena	Terminal de salida antes y después del cambio
baggage_claim	Cadena	Número de la cinta de equipaje, una vez asignado
provider	Cadena	El proveedor de datos que informó del cambio (aerodatabox)
delay_minutes	Entero	Minutos de retraso respecto al horario previsto, presente en cada evento
scheduled_at / estimated_at / actual_at	Cadena	Horas de salida programadas, estimadas actualmente y reales, en el formato propio del proveedor
arrival_terminal	Cadena	Terminal de llegada, una vez asignada
arrival_scheduled_at / arrival_estimated_at / arrival_actual_at	Cadena	Horas de llegada programadas, estimadas actualmente y reales, en el formato propio del proveedor
scheduled_at_local / estimated_at_local / actual_at_local	Cadena	Las tres horas de salida anteriores, en la hora local del aeropuerto de salida
arrival_scheduled_at_local / arrival_estimated_at_local / arrival_actual_at_local	Cadena	Las tres horas de llegada anteriores, en la hora local del aeropuerto de llegada
flight_date / event_time	Fecha	La fecha del vuelo y cuándo ocurrió el cambio

Valores y formatos de los atributos

• Valores de event_type: gate_change, delay, boarding, departed, arrived, cancelled, baggage_ready.
• Valores de status: scheduled, check_in, boarding, departed, delayed, arrived, cancelled, diverted, unknown. Un estado de AeroDataBox que Pushwoosh no reconoce se informa como unknown.
• delay_minutes: presente en cada evento, no solo en los de tipo delay. 0 significa que el vuelo va a tiempo, y un valor negativo significa que va adelantado. Un evento delay se envía cuando el retraso alcanza los 5 minutos.
• Atributos de hora: todos ellos, incluidos los arrival_* y los _local, son de tipo Cadena, no Fecha. Así, una hora vacía no se elimina del evento, y una hora local conserva el desfase UTC del aeropuerto. Para filtrar por fecha, use flight_date y event_time.