A API de Engajamento da Machine permite que ferramentas de CRM e marketing recebam em tempo real tudo o que acontece no app e usem essas informações para agir automaticamente.
Configurar a API requer conhecimento técnico, para garantir que a integração ocorra de forma correta. Consulte o desenvolvedor ou equipe técnica responsável pelo sistema.
O que é possível fazer com essa integração?
O Gestor cadastra um link via API da Machine para receber os eventos e define quais Centrais Associadas terão os eventos enviados para esse endereço. Com a configuração concluída, todo evento relevante gerado no app é automaticamente disparado para a sua ferramenta de engajamento.
Sendo possível criar ações automáticas do sistema com base no comportamento dos passageiros no aplicativo. Por exemplo: quando uma corrida for estimada, solicitada ou cancelada.
Automações comuns de ferramentas de CRM que utilizam os webhooks:
- Enviar notificações push para os Passageiros diretamente pela API Machine
- Exibir mensagens dentro do próprio app para os Passageiros
- Oferecer cupons para passageiros que estimam a corrida mas desistem de pedir
Dados enviados em cada evento
A cada evento disparado, a sua ferramenta recebe automaticamente informações sobre a corrida e o Passageiro envolvido, permitindo identificar o usuário e personalizar a ação com base no contexto.
- Data e hora do evento
- Latitude e longitude do embarque
- Valor da corrida
- Forma de pagamento
- Categoria da corrida
- Status da ordem de serviço
- Motivo de cancelamento (quando aplicável)
Por segurança e conformidade com a LGPD, dados como CPF, cartão de crédito e senhas nunca são enviados pela integração.
Eventos disponíveis
Cada evento pode ser usado como gatilho para uma ação automática na sua ferramenta, como envio de mensagem, criação de cupom ou qualquer outra automação que o seu sistema suporte.
1. Passageiro cadastrado
Disparado quando um novo Passageiro cria uma conta no app.
- Passageiro se cadastrou → Ação de boas-vindas
- Passageiro se cadastrou e não fez uma estimativa → Ação de reengajamento
- Passageiro se cadastrou e não solicitou nenhuma corrida → Ação de reengajamento
2. Corrida estimada
Disparado quando o Passageiro simula o preço de uma corrida.
- Passageiro estimou mas não solicitou a corrida → Ação de recuperação
3. Corrida solicitada
Disparado quando o Passageiro confirma o pedido de corrida.
- Corrida não iniciada após 1 minuto → Ação
- Corrida não iniciada após 2 minutos → Ação
- Corrida não iniciada após 5 minutos → Ação
4. Corrida iniciada
Disparado quando o Condutor inicia a corrida com o Passageiro.
- Corrida iniciada → Ação
5. Corrida finalizada
Disparado quando a corrida é concluída.
- Corrida finalizada → Ação
- Passageiro concluiu a primeira corrida → Ação especial
- Passageiro concluiu 10 corridas → Ação especial
- Passageiro concluiu 50 corridas → Ação especial
6. Corrida cancelada pelo Passageiro
Disparado quando o próprio Passageiro cancela a corrida.
- Passageiro cancelou voluntariamente → Ação de recuperação
7. Corrida cancelada pelo Gestor
Disparado quando o Gestor cancela a corrida.
- Passageiro viu que a corrida foi cancelada → Ação
8. Corrida não atendida
Disparado quando nenhum Condutor aceita a corrida.
- Passageiro viu que a corrida não foi atendida → Ação
- Não havia Condutores disponíveis no momento → Ação
9. Corrida avaliada
Disparado quando o Passageiro dá uma nota para a corrida.
- Nota menor que 2 → Ação de recuperação
- Nota 5 → Ação de reconhecimento
Passo a passo para ativar
1. Liberar as permissões necessárias
Antes de começar, o responsável precisa estar em um cargo com permissão para acessar os endpoints.
Acesse o painel da Central Principal e siga o caminho: Minha equipe > [Selecione o cargo do responsável pela API] > Seção API
Ative as permissões:
- ✅ Engajamento
- ✅ Notificações
2. Conectar sua plataforma de engajamento
Com as permissões liberadas, o time técnico faz a configuração usando a documentação da API da Machine:
Documentação — Recebimento de eventos
3. Ativar o envio de notificações
Para enviar notificações push ou mensagens dentro do app pela sua plataforma:
Documentação — Notificações e mensagens in-app
Mensagens dentro do app exigem a versão 25.2 ou superior do aplicativo. O botão de ação com link personalizado exige a versão 25.4 ou superior.
API de engajamento para Centrais Associadas
Como funciona o cadastro entre Centrais principais e Associadas?
O controle fica com a Central Principal, que é a única com permissão para cadastrar novos webhooks:
- Cadastro centralizado: Apenas a Central Principal cadastra os webhooks.
- Vínculo de Centrais Associadas: Após criar o webhook, a Central Principal indica quais Centrais Associadas farão parte dele e define quais eventos cada uma receberá.
- Regra de prioridade: Se uma Central Associada não tiver webhook configurado, os eventos dela são enviados automaticamente para o webhook da Central Principal.
- URLs distintas: Centrais Principais e Associadas precisam usar links diferentes — o sistema não permite links duplicados.
- Alerta de conflito: Se uma Central Associada já estiver vinculada a outro webhook, o sistema bloqueia a ação e informa onde ela está cadastrada.
- Gerenciamento posterior: É possível editar URLs, alterar permissões ou remover Centrais Associadas de um webhook a qualquer momento.
Como faço para que uma Central Associada receba os eventos separadamente?
A configuração deve ser feita pela Central Principal:
- Criação do webhook: A Central Principal cadastra um webhook com uma URL exclusiva para a Central Associada — cada Central Associada precisa de um link próprio.
- Vínculo da Central Associada: A Central Principal usa o ID do webhook para indicar qual Central Associada receberá os eventos.
- Definição dos eventos: A Central Principal define quais eventos estarão habilitados para aquela Central Associada.
Se o objetivo for apenas monitorar os dados da Central Associada em nível corporativo, sem separar os envios, nenhuma configuração adicional é necessária. Os eventos da Central Associada serão enviados automaticamente para o webhook da Central Principal.