Presença indica que sua integração está recebendo e processando eventos. O iFood usa presença para determinar se seus merchants aparecem como online na plataforma.Quando sua integração está online, o iFood marca seus merchants como disponíveis para receber pedidos—desde que atendam a outros critérios como horário de funcionamento e cardápio publicado. Isso reduz cancelamentos por falta de resposta e melhora a experiência do usuário.
Escolha seu método de presença
Existem duas formas mutuamente exclusivas de comunicar presença ao iFood:
Método
Fluxo
Melhor para
Webhook (Heartbeat)
Você responde aos heartbeats enviados pelo iFood
Controle granular, sistemas distribuídos, múltiplos merchants com status diferentes
Polling
Você faz requisições regulares ao iFood
Sistemas centralizados, poucos merchants, arquitetura mais simples
Escolha o método que melhor se adequa à sua arquitetura. Você não pode usar os dois simultaneamente para o mesmo merchant.
Decisão rápida
Você já usa webhooks para receber eventos de pedidos? → Use Webhook
Você usa polling para consultar eventos? → Use Polling (automático)
Primeira integração e sem preferência? → Webhook oferece mais controle
Como funciona
Você pode implementar presença de duas formas diferentes:
Método 1: Presença via Webhook (Heartbeat)
Como funciona: O iFood envia requisições periódicas (KEEPALIVE) ao seu webhook. Você responde indicando quais merchants estão online.Fluxo:
Webhook habilitado → iFood inicia heartbeats
iFood envia requisição KEEPALIVE a cada 30 segundos
Você responde indicando quais merchants estão online
iFood atualiza status de presença para aquele merchant
Resposta esperada:
202 Accepted → merchant(s) ficam online
Qualquer outro código ou timeout → merchant(s) ficam offline
Quando usar:
Você precisa de controle granular por merchant
Merchants têm horários ou disponibilidades diferentes
Sua integração já usa webhooks para outros eventos
Você quer que o iFood inicie as requisições
Método 2: Presença via Polling
Como funciona: Sua integração faz requisições regulares ao iFood consultando eventos. O merchant fica online enquanto o polling continua ativo a cada 30 segundos.Fluxo:
Sua integração é iniciada
Você faz requisições de polling a cada 30 segundos
Enquanto o polling continua, o merchant fica online
Se o polling parar, o merchant fica offline
Resposta esperada:
Requisição bem-sucedida (200 ou 204) → merchant(s) ficam online
Requisições param ou falham → merchant(s) ficam offline
Quando usar:
Você usa polling como único método de integração
Sua arquitetura é centralizada
Você não quer configurar webhooks
Você já faz polling para consultar eventos
Webhook: Modos de operação
Se você escolher usar webhook, configure um dos dois modos de operação:
Modo por aplicativo
Use quando todos os merchants compartilham o mesmo status de presença. Uma resposta 202 Accepted marca todos os merchants como online.Quando usar: Sistema sempre disponível, sem necessidade de controle individualizado.Request do iFood:
Use quando você precisa controlar presença individualmente. O iFood envia lista de merchants e você retorna apenas os que estão online.Quando usar: Merchants com horários diferentes, manutenção de sistemas parciais, ou controle granular de disponibilidade.Request do iFood:
Requisitar a cada 30 segundos → Merchants ficam online
Parar de fazer polling → Merchants ficam offline após timeout
Não é necessário nenhuma configuração adicional. Basta manter o polling ativo e contínuo.
Comparação: Webhook vs Polling
Aspecto
Webhook
Polling
Iniciativa
iFood envia heartbeats
Você consulta status
Frequência
A cada 30 segundos
A cada 30 segundos (recomendado)
Latência
Quase imediata
Até 30 segundos de atraso
Complexidade
Moderada (validar assinatura)
Simples (chamadas HTTP regulares)
Controle granular
Por aplicativo ou por merchant
Automático (enquanto polling ativo)
Overhead de rede
Baixo (iFood inicia)
Moderado (você inicia)
Ideal para
Múltiplos merchants com status diferentes
Poucos merchants, arquitetura simples
Manutenção
Configure no Developer Portal
Configure apenas o intervalo
Segurança
Webhook
Heartbeats incluem o header X-IFood-Signature como qualquer outro evento. Valide a assinatura antes de processar a requisição.Veja validação de assinatura para detalhes.
Polling
Requisições de polling usam autenticação JWT Bearer. Mantenha seu token seguro e não o compartilhe.
Exemplos de implementação
Webhook: Sistema sempre online
Cenário: Seu sistema está sempre disponível e todos os merchants devem ficar online.Implementação:
@app.route('/webhook', methods=['POST'])defwebhook(): event = request.jsonif event['code'] == 'KEEPALIVE':# Modo por aplicativo: responda 202 para todos os merchantsreturn'', 202# ... processar outros eventos
Webhook: Merchants com horários diferentes
Cenário: Merchants fecham em horários diferentes. Você precisa marcar apenas os abertos como online.Implementação:
@app.route('/webhook', methods=['POST'])defwebhook(): event = request.jsonif event['code'] == 'KEEPALIVE':if'merchantIds'in event:# Modo por merchant: filtre por horário online_merchants = [ m for m in event['merchantIds']if is_merchant_open(m) ]return jsonify({'merchantIds': online_merchants}), 202else:# Modo por aplicativo: todos os abertosreturn'', 202# ... processar outros eventos
Webhook: Sistema em manutenção
Cenário: Sistema offline por manutenção. Você precisa marcar todos os merchants como offline.Implementação:
@app.route('/webhook', methods=['POST'])defwebhook(): event = request.jsonif event['code'] == 'KEEPALIVE':if'merchantIds'in event:# Modo por merchant: responda com lista vaziareturn jsonify({'merchantIds': []}), 202else:# Modo por aplicativo: responda com erroreturn'Service Unavailable', 503# ... processar outros eventos
Polling: Mantendo presença ativa
Cenário: Você usa polling como único método de integração.Implementação:
import timefrom datetime import datetimedefkeep_presence_active():whileTrue:try:# Fazer polling a cada 30 segundos response = requests.get('https://merchant-api.ifood.com.br/events/v1.0/events:polling',headers={'Authorization': f'Bearer {your_token}'},headers={'x-polling-merchants': merchant_ids} )if response.status_code == 200: events = response.json() process_events(events)# Enviar ACK para manter polling ativo acknowledge_events(events)elif response.status_code == 204:# Sem eventos, mas presença mantidapass# Aguardar 30 segundos antes do próximo polling time.sleep(30)exceptExceptionas e:print(f"Erro no polling: {e}")# Presença será perdida se polling falhar por muito tempo time.sleep(30)# A presença será mantida enquanto esse loop continuar rodandokeep_presence_active()
Pontos importantes:
Polling a cada 30 segundos é essencial para manter presença
Se o polling parar por mais de alguns minutos, merchants ficarão offline
Use o header x-polling-merchants para filtrar merchants específicos