Integração de Status de Voo

Informe os passageiros sobre mudanças no voo deles assim que acontecem: um novo portão, um atraso, embarque, chegada ou um cancelamento. A integração de Status de Voo conecta o Pushwoosh ao AeroDataBox, um provedor de dados de voos, para que uma jornada do cliente possa monitorar o voo de um passageiro específico e reagir no momento em que seu status mudar.

Necessária a ajuda de um desenvolvedor

Você precisará da sua equipe de desenvolvimento para enviar o evento de reserva com os atributos corretos e para construir o corpo da solicitação da etapa de Webhook. Compartilhe este guia com eles.

Visão geral da integração

Tipo de integração

Fonte: você inscreve uma reserva em seu voo de dentro de uma jornada. O Pushwoosh envia as mudanças de status de volta como um evento que você usa mais tarde na mesma jornada.

Pré-requisitos

Antes de conectar o Status de Voo, certifique-se de que você tem:

• Uma conta Pushwoosh ativa com um aplicativo no data center NUE do Pushwoosh. A integração de Status de Voo ainda não está disponível em outros data centers.
• Uma conta AeroDataBox e uma chave de API. O feed é cobrado em sua própria conta AeroDataBox.
• Um evento de reserva que carrega a companhia aérea, o número, a data e o aeroporto de partida do voo (veja Construir a jornada de status de voo).
• Um token de Acesso à API dedicado para a jornada se autenticar.

Como a integração funciona?

Conectar a integração e monitorar um voo são duas etapas separadas, feitas em momentos diferentes:

1. Conecte sua chave AeroDataBox em Configurações → Integrações de terceiros.
2. Um evento de reserva insere um passageiro em sua jornada.
3. A etapa de Webhook da jornada inscreve essa reserva em seu voo através da API pública do Pushwoosh.
4. O Pushwoosh monitora o voo com o AeroDataBox e detecta mudanças: portão, atraso, embarque, chegada, cancelamento ou uma atribuição de esteira de bagagem.
5. Cada mudança é entregue ao aplicativo como um evento PW_FlightStatusChanged, que os elementos Wait for Trigger e Condition split da jornada direcionam para a mensagem correta.

Cada inscrição de voo termina automaticamente 36 horas após a data local de partida. Ela pode terminar antes: assim que o voo pousa ou é cancelado, ou assim que nada mais o está monitorando. O Pushwoosh então cancela a inscrição correspondente no AeroDataBox, para que ela não continue gerando cobranças em segundo plano.

Essa janela é fixada no momento da inscrição, a partir da data de partida reservada, e não muda se o AeroDataBox relatar um atraso depois. Um atraso que empurra o voo para o dia seguinte pode fazer a inscrição terminar antes da partida real atrasada.

Casos de uso

A integração de Status de Voo cobre quatro tipos de atualizações, cada uma utilizável por si só ou combinada em uma jornada:

• Alertas de mudança de portão: notifique os passageiros no momento em que o portão de embarque mudar.
• Notificações de atraso: alerte os passageiros assim que o atraso de um voo passar de alguns minutos, para que possam ajustar seus planos.
• Atualizações de embarque e chegada: informe os passageiros quando o embarque começar ou quando o voo pousar.
• Retirada de bagagem: envie o número da esteira de bagagem assim que for atribuído.

Configurar a integração

Conectar o Status de Voo ao Pushwoosh

Conecte sua chave AeroDataBox uma vez por aplicativo:

1. Abra seu aplicativo e vá para Configurações → Integrações de terceiros.

2. Em Serviços disponíveis, encontre o cartão Status de Voo e clique em Configurar.

   

3. Cole sua chave AeroDataBox em Chave de API e clique em Conectar.

   

Depois que você clicar em Conectar, o cartão se move para Serviços conectados.

Se a chave for rejeitada

O Pushwoosh verifica a chave em segundo plano. Se algo estiver errado, o cartão mostra uma destas mensagens:

Mensagem	Causa
provider rejected the API key	A chave é inválida ou foi revogada no AeroDataBox
provider account is out of credits	Seu plano AeroDataBox ficou sem créditos
provider rate limit reached	O AeroDataBox está limitando as solicitações, e isso se resolve sozinho
provider is unavailable	Não foi possível contatar o AeroDataBox, devido a um problema de rede ou uma interrupção de qualquer um dos lados
provider refused the request	O AeroDataBox retornou um erro que o Pushwoosh não reconhece de outra forma

Substituir a chave

Reabra o cartão Status de Voo em Serviços conectados, por exemplo depois que a chave for rejeitada:

• Substituir a chave: cole uma nova em Chave de API.
• Manter a chave atual: deixe Chave de API vazio. O campo mostra apenas os últimos caracteres da chave salva.

Desconectar a integração

1. Abra o cartão Status de Voo em Serviços conectados.
2. Remova a chave.

Depois que você desconectar:

• Novas inscrições não são mais criadas.
• Os voos que as jornadas já monitoram mantêm suas inscrições até que terminem por conta própria ou você as exclua da jornada.
• A contagem de inscrições ativas no cartão inclui essas inscrições até que terminem.

Construir a jornada de status de voo

Antes de construir a jornada

Certifique-se de que você tem:

• Um evento de reserva carregando a companhia aérea, o número, a data (YYYY-MM-DD) e o aeroporto de partida do voo, mais um atributo contendo a chave do voo no formato <companhia_aérea><número>/<data>/<aeroporto_de_partida>, por exemplo LH400/2026-09-20/MUC. É isso que a correspondência de sessão usa ao longo da jornada.
• Um token de Acesso à API dedicado. O método de inscrição aceita qualquer token da sua conta, sem permissões a serem concedidas. Crie um especificamente para esta jornada para que você possa revogá-lo mais tarde sem tocar em mais nada.
• O host da API pública do seu data center. Para contas NUE, é rpc-api.svc-nue.pushwoosh.com.
• O Limite de entrada da campanha da jornada, desativado. O limite de entrada da campanha rastreia as entradas apenas por usuário. Ele não sabe sobre o identificador de sessão que você configura abaixo, então bloquearia o segundo voo de um passageiro até que o período limite passasse.

Iniciar a jornada a partir de um evento de reserva

1. Adicione uma Entrada baseada em gatilho (Trigger-based entry) e selecione seu evento de reserva, por exemplo flight_booked.
2. Em Controlar quantas sessões um usuário pode ter ao mesmo tempo, escolha Múltiplas sessões ativas por usuário.
3. Escolha o atributo de chave de voo como o identificador de sessão. Isso permite que o mesmo passageiro rastreie mais de um voo ao mesmo tempo, cada um em sua própria sessão.

Inscrever a reserva com uma etapa de Webhook

Adicione uma etapa de Webhook diretamente após a entrada. O corpo da solicitação extrai os campos do voo do evento de entrada, então a etapa precisa estar logo após a entrada para usá-los.

1. Defina TIPO DE SOLICITAÇÃO como POST.

2. Defina URL como https://rpc-api.svc-nue.pushwoosh.com/api/integrations/flight-status/subscriptions.

3. Em CABEÇALHOS, mantenha Content-Type: application/json.

4. Adicione um cabeçalho Authorization: Token <seu token de API>. O Pushwoosh mascara esse valor depois que você salva, porque qualquer cabeçalho chamado Authorization é tratado como um segredo automaticamente. Veja Marcar um valor de cabeçalho como secreto para saber o que isso significa para edição e histórico de versões.

5. Em DADOS, insira o corpo da solicitação abaixo, digitando seu próprio código de aplicativo diretamente:

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

6. Para cada um dos quatro valores vazios de flight, abra o CONSTRUTOR DE DADOS.

7. Selecione a categoria Evento.

8. Escolha o atributo correspondente do seu evento de reserva (companhia aérea, número do voo, data do voo, aeroporto de partida).

9. Copie a macro que o Pushwoosh gera e cole-a como o valor desse campo. Repita para os três valores restantes.

Você não precisa mapear nada da resposta. Ela retorna flight_key, que já está no seu evento de reserva.

Cuidado

Se a chamada de inscrição falhar, o passageiro sai da jornada nesta etapa, da mesma forma que em qualquer etapa de Webhook. O voo dele não é monitorado, e ele não receberá nenhum dos alertas mais adiante na jornada. Veja O que acontece quando uma solicitação falha.

Aguardar uma atualização de status

Adicione uma etapa de Wait for Trigger após a etapa de Webhook.

1. Adicione um ramo e defina seu evento como PW_FlightStatusChanged.
2. Em correspondência de atributo de múltiplas sessões, selecione o mesmo atributo de chave de voo que você usou na entrada. Isso garante que uma atualização de status só desperte o passageiro cujo voo ela realmente diz respeito.
3. Defina o período de espera para cobrir confortavelmente o voo. 48 horas é suficiente para a maioria dos itinerários.
4. Deixe o ramo Não acionado sem uma próxima etapa ou adicione uma mensagem de fallback. Os passageiros cujo voo não tem nenhuma atualização antes do fim da espera saem da jornada aqui, e isso é esperado.

Ramificar por tipo de evento

Adicione um Condition split após a etapa Wait for Trigger.

1. Selecione Evento como o tipo de condição.
2. Em Evento da Jornada, escolha PW_FlightStatusChanged.
3. Em Atributo, selecione event_type.
4. Defina a condição como é.
5. Adicione um ramo com o valor gate_change.
6. Clique em Salvar. Isso cria dois ramos: o que você nomeou para uma mudança de portão e Todos os outros usuários para todos os outros tipos de evento.

Repita este elemento, ou adicione mais ramos a ele, para os outros valores de event_type sobre os quais você deseja agir: delay, boarding, departed, arrived, cancelled e baggage_ready todos funcionam da mesma maneira.

Notificar o passageiro

Adicione um elemento Push no ramo de mudança de portão.

1. Selecione ou crie uma predefinição de push.
2. Defina o Tipo de mensagem como Mensagem transacional, pois um alerta de status de voo é uma notificação de serviço, não uma promoção. O limite de frequência não se aplica, e ainda alcança passageiros em um grupo de controle.
3. Ative a personalização com atributos de evento.
4. Escolha PW_FlightStatusChanged como o evento de origem.
5. Preencha os espaços reservados da sua predefinição com flight_number e gate_new.

Mostrar um cartão de Live Activity em vez disso

Adicione três elementos Live Activity, no lugar de Push ou além dele:

• Start: logo após a etapa de Webhook, não diretamente após a entrada. A entrada se conecta a apenas uma próxima etapa, então Webhook e Start não podem vir ambos logo após ela.
• Update: no ramo de mudança de portão.
• End: assim que a jornada não precisar mais rastrear o voo, por exemplo após a chegada ou o cancelamento.

No elemento Start, em Card attributes, adicione os seis campos que o tipo ActivityAttributes do cartão precisa. Card attributes é uma lista livre de nomes e valores, e a interface não verifica os nomes, então insira cada um exatamente como listado. Cinco deles já estão no seu evento de reserva:

• carrier
• flight_number
• flight_date
• departure_airport
• flight_key
• arrival_airport: a chamada de inscrição não precisa dele, então adicione-o ao seu evento de reserva somente se você usar Live Activity.

Cuidado

Se algum dos seis Card attributes estiver faltando, a interface não mostra nenhum erro, mas o cartão nunca aparece no dispositivo. Todo Update ou End posterior para esse passageiro então falha com o código de entrega 1031 (“push token not found for the specified Live Activity ID”).

Somente Start define Card attributes, e eles permanecem os mesmos durante toda a vida do cartão. Update e End não os definem. Os campos que mudam, como status, portão e atraso, são Card content e vêm do esquema de widget que você publicar para este aplicativo.

Referência do evento PW_FlightStatusChanged

Toda mudança que a integração detecta é entregue como um evento PW_FlightStatusChanged, com todos os atributos sempre presentes: os vazios são enviados como valores em branco, nunca omitidos.

Atributo	Tipo	Descrição
event_type	String	O que mudou (veja os valores abaixo)
flight_key	String	A mesma chave de voo que você definiu no evento de reserva
flight_number	String	O número do voo
departure_airport	String	Código do aeroporto de partida
arrival_airport	String	Código do aeroporto de chegada
status	String	Status atual do voo (veja os valores abaixo)
gate_old / gate_new	String	Portão de embarque antes e depois da mudança
terminal_old / terminal_new	String	Terminal de embarque antes e depois da mudança
baggage_claim	String	Número da esteira de bagagem, uma vez atribuído
provider	String	O provedor de dados que relatou a mudança (aerodatabox)
delay_minutes	Integer	Minutos de atraso em relação ao horário programado, presente em todos os eventos
scheduled_at / estimated_at / actual_at	String	Horários de partida programados, atualmente estimados e reais, no formato próprio do provedor
arrival_terminal	String	Terminal de chegada, uma vez atribuído
arrival_scheduled_at / arrival_estimated_at / arrival_actual_at	String	Horários de chegada programados, atualmente estimados e reais, no formato próprio do provedor
scheduled_at_local / estimated_at_local / actual_at_local	String	Os três horários de partida acima, no horário local do aeroporto de partida
arrival_scheduled_at_local / arrival_estimated_at_local / arrival_actual_at_local	String	Os três horários de chegada acima, no horário local do aeroporto de chegada
flight_date / event_time	Date	A data do voo e quando a mudança aconteceu

Valores e formatos dos 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. Um status do AeroDataBox que o Pushwoosh não reconhece é relatado como unknown.
• delay_minutes: presente em todos os eventos, não apenas nos de delay. 0 significa que o voo está no horário, e um valor negativo significa que ele está adiantado. Um evento delay é enviado quando o atraso chega a 5 minutos.
• Atributos de horário: todos eles, incluindo os arrival_* e _local, são do tipo String, não Date. Assim, um horário vazio não é removido do evento, e um horário local mantém o deslocamento UTC do aeroporto. Para filtrar por data, use flight_date e event_time.