Integrações e API¶

📍 Onde fica: Configurações → Integrações 👤 Quem pode: Administrador da DZ 🔗 Pré-requisito: módulo Integrações (API) liberado para a sua DZ pela equipe do Airo.

A API de integração conecta o Airo a outro sistema da DZ — o primeiro uso é o CRM, que passa a receber os saltos duplos sem ninguém digitar nada. O sistema integrado só lê dados: ele não cria, altera nem apaga nada no Airo.

Para isso, você cria uma chave de API e entrega as credenciais a quem cuida do outro sistema (a empresa do CRM, por exemplo). Esta página explica o que fazer no Airo. O passo a passo técnico para quem vai programar a integração está no Guia do integrador.

Módulo opcional¶

As integrações são um módulo opcional: a equipe do Airo libera por DZ. Enquanto o módulo não estiver liberado, a tela mostra "As integrações não estão liberadas para esta DZ." — fale com o suporte do Airo para ativar.

Se o módulo está liberado mas o seu perfil não tem acesso às integrações, a mensagem é outra: "Você não tem permissão para ver as integrações desta DZ." Nesse caso, peça a um administrador da DZ para liberar o acesso. Nas outras telas do Airo vale a mesma diferença: "Este recurso não está liberado para esta DZ." quando falta o módulo, e "Você não tem permissão para esta ação." quando falta a permissão.

A tela Integrações¶

Em Configurações → Integrações você vê o card Chaves de API, com quantas chaves estão ativas (ex.: "2 de 5 chaves ativas") e, para cada chave:

Coluna	O que mostra
Nome	O nome que você deu, para saber onde a chave é usada (ex.: "CRM RD Station")
Chave	O começo da chave (`airo_live_…`), para reconhecê-la — nunca a chave inteira
Escopos	O que a chave pode ler: Saltos duplos, Contato, Cobranças
Criada	Quem criou e quando
Expira em	A data em que a chave para de funcionar
Último uso	Quando o sistema integrado usou a chave pela última vez (ou Nunca usada). Atualiza a cada 5 minutos, no máximo
Status	Ativa, Ativando…, Falha na ativação, Expirada ou Revogada (com o motivo, ex.: "Revogada manualmente", "Criador removido da equipe")

Por padrão, a lista mostra só as chaves em uso (Ativa e Ativando…). Quando existe alguma chave revogada, expirada ou com falha, aparece o botão Mostrar revogadas e com falha: ligue para ver todas. Se nenhuma chave estiver em uso, a tela avisa "Nenhuma chave ativa".

No celular, a lista aparece em cards. O botão Documentação da API abre o guia técnico, para você mandar o link a quem vai fazer a integração.

⏰ Chave perto de vencer. Quando faltam 14 dias ou menos, a chave ganha o selo Expira em X dias e a tela avisa no topo. Crie uma nova chave, troque no sistema integrado e depois revogue a antiga.

Criar uma chave¶

Clique em Nova chave.
Em Nome, escreva onde a chave vai ser usada (ex.: "CRM RD Station").

Em O que esta chave pode ler, marque os escopos:

Escopo	O que libera	Padrão
Saltos duplos	Saltos duplos realizados: data, decolagem, passageiro e status. Também o instrutor, o produto e a reserva ligada	Sempre marcado (obrigatório)
Contato	E-mail e telefone do passageiro e do comprador	Desmarcado
Cobranças	Resumo financeiro do atendimento: cobrado, pago, descontos e saldo	Desmarcado

Se marcar Contato, confirme a caixa "Confirmo que a DZ tem base legal e aviso de privacidade para enviar estes dados ao sistema integrado." — e-mail e telefone são dados pessoais (LGPD), e a DZ é responsável por enviá-los a outro sistema. Sem essa confirmação a chave não é criada.
Em Validade, escolha por quanto tempo a chave vale: 30 dias, 90 dias, 180 dias, 1 ano (365 dias) (padrão) ou 2 anos (730 dias). A tela mostra a data em que ela para de funcionar.
Clique em Criar chave.

Marque só o que o outro sistema precisa. Se o CRM não usa valores, deixe Cobranças desmarcado; se não manda e-mail nem mensagem, deixe Contato desmarcado. Para mudar os escopos depois, crie outra chave e revogue a antiga.

⚠️ A chave depende de quem a criou. Como diz o aviso no formulário: "Se você sair da equipe ou perder a permissão de administrar integrações, as chaves que criou deixam de funcionar." Veja Quando a chave para de funcionar sozinha.

As duas credenciais (mostradas uma única vez)¶

Depois de criar, abre o diálogo Chave criada com duas credenciais. O sistema integrado precisa das duas:

Chave do gateway — vai no cabeçalho x-api-key.
Segredo — começa com airo_live_ e vai no cabeçalho Authorization: Bearer.

Cada uma tem o botão Copiar. Em Teste a conexão há um comando pronto para quem vai programar testar a chave.

🔐 "Esta é a única vez que as credenciais serão exibidas. Guarde-as em local seguro." O Airo não guarda o segredo de um jeito que dê para mostrar de novo. Se perder, crie outra chave e revogue a que se perdeu.

O diálogo só fecha depois de você marcar Já guardei as credenciais e clicar em Fechar. Entregue as credenciais a quem vai fazer a integração por um canal seguro (de preferência um gerenciador de senhas) — nunca por e-mail aberto ou grupo de mensagem.

Na lista, a chave aparece como Ativando… por alguns instantes e depois como Ativa. Se aparecer Falha na ativação ("Não foi possível ativar na AWS. Exclua e crie outra."), exclua a chave e crie outra.

⏳ A chave nova pode levar alguns minutos para funcionar. Mesmo já Ativa na lista, nos primeiros minutos o sistema integrado pode receber erro de acesso. Peça a quem programa para aguardar e testar de novo antes de concluir que há problema.

Limite de 5 chaves¶

Cada DZ pode ter até 5 chaves ativas. Com 5, o botão Nova chave fica desligado e a tela avisa: "A DZ atingiu o limite de 5 chaves ativas. Revogue uma chave que não está em uso para criar outra."

Revogar uma chave¶

Revogue quando o sistema integrado deixar de ser usado, quando trocar de fornecedor ou se achar que a chave vazou.

Na linha da chave, clique em Revogar.
Se quiser, preencha o Motivo (opcional) — ele fica na lista e na auditoria.
Clique em Revogar chave.

O efeito é imediato: o sistema que usa a chave para de receber dados na hora. Não dá para desfazer — para voltar, crie uma nova chave e configure de novo no sistema integrado. Se a chave foi usada nas últimas 24 horas, a tela avisa antes de confirmar.

Excluir uma chave¶

Chaves revogadas, expiradas ou com Falha na ativação podem ser excluídas, para limpar a lista. Uma chave ativa precisa ser revogada antes ("Revogue a chave antes de excluir.").

Se a chave não aparece, ligue Mostrar revogadas e com falha.
Na linha da chave, clique em Excluir.
Confirme em Excluir.

A chave some da lista, mas o histórico continua na trilha de auditoria. Não dá para desfazer. Se a tela disser "A chave ainda está sendo removida da AWS. Tente novamente em alguns minutos.", espere um pouco e tente de novo.

Quando a chave para de funcionar sozinha¶

Situação	O que acontece
A validade venceu	A chave fica Expirada
Quem criou a chave foi removido da equipe	A chave é revogada na hora, com o motivo "Criador removido da equipe"
Quem criou a chave foi desativado	A chave é revogada na hora, com o motivo "Criador inativado"
Quem criou a chave perdeu a permissão de administrar integrações (ex.: deixou de ser Administrador)	A chave para de funcionar na hora
O módulo Integrações (API) foi desligado para a DZ	Todas as chaves ficam suspensas (o sistema integrado recebe erro de acesso). Quando o módulo é religado, voltam a funcionar — nada é apagado

💡 Dica: quando um administrador vai sair da DZ, crie antes as chaves novas com outro administrador, troque no sistema integrado e só então remova a pessoa da equipe. Assim a integração não para.

Limites de uso¶

Para proteger o Airo e a sua DZ, cada chave tem um limite de 1 consulta por segundo (com pequenas rajadas) e 5.000 consultas por dia. É bem mais do que um CRM precisa para atualizar os saltos duplos todos os dias. Se o sistema integrado passar do limite, o Airo responde que é para esperar e tentar de novo depois — nenhum dado se perde.

Boas práticas de segurança¶

Credenciais só no servidor do sistema integrado. Nunca coloque a chave numa página da internet, num aplicativo de celular ou numa planilha compartilhada — quem tiver as credenciais lê os dados da DZ. O Airo recusa chamadas feitas direto do navegador.
Uma chave por sistema. Se o CRM e o BI usam a API, crie uma chave para cada um: assim você revoga uma sem parar a outra e vê na coluna Último uso quem está usando.
Troque a chave de tempos em tempos (e sempre que alguém que conhecia as credenciais sair): crie uma chave nova, troque no sistema integrado e revogue a antiga.
Vazou? Revogue na hora e crie outra. Se não conseguir, fale com o suporte do Airo.
Confira a coluna Último uso. Chave que nunca é usada é chave para revogar.

Toda criação, revogação, exclusão e cada consulta feita com a chave ficam na trilha de auditoria: quando a chave foi usada, de qual endereço e o que foi consultado (sem o conteúdo). As consultas ficam escondidas por padrão na Auditoria: ligue Mostrar consultas da API para vê-las.

O que a equipe do Airo pode fazer¶

A equipe do Airo (admin do sistema) pode criar uma chave para a sua DZ quando você pedir ajuda para configurar uma integração — mesmo sem fazer parte da sua equipe. Isso vale para qualquer DZ com o módulo liberado, com as mesmas regras de limite, validade, escopos e confirmação de LGPD. A chave aparece na sua lista com o nome de quem criou, a criação fica registrada na sua trilha de auditoria e você pode revogá-la quando quiser. Ela funciona enquanto essa pessoa continuar na equipe do Airo; se deixar de ser admin do sistema, a chave para de funcionar na hora.

Em caso de incidente (vazamento ou suspeita de uso indevido), a equipe do Airo pode:

revogar uma chave da DZ ou todas as chaves da DZ de uma vez — sempre com um motivo, que aparece na lista e na auditoria;
desligar o módulo Integrações (API) — as chaves ficam suspensas e voltam a funcionar se o módulo for religado.

✅ Pronto quando¶

[ ] Módulo Integrações (API) liberado para a DZ.
[ ] Chave criada só com os escopos necessários e as duas credenciais entregues por canal seguro.
[ ] Quem programa a integração recebeu o link do Guia do integrador e testou a conexão.
[ ] A coluna Último uso mostra que o sistema integrado está consultando.