Buscar na documentação
ctrl+4K
Módulos
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Soluções

Presença

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.
Existem duas formas mutuamente exclusivas de comunicar presença ao iFood:
MétodoFluxoMelhor para
Webhook (Heartbeat)Você responde aos heartbeats enviados pelo iFoodControle granular, sistemas distribuídos, múltiplos merchants com status diferentes
PollingVocê faz requisições regulares ao iFoodSistemas 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.
  • 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
Você pode implementar presença de duas formas diferentes:Como funciona: O iFood envia requisições periódicas (KEEPALIVE) ao seu webhook. Você responde indicando quais merchants estão online.Fluxo:
  1. Webhook habilitado → iFood inicia heartbeats
  2. iFood envia requisição KEEPALIVE a cada 30 segundos
  3. Você responde indicando quais merchants estão online
  4. 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
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:
  1. Sua integração é iniciada
  2. Você faz requisições de polling a cada 30 segundos
  3. Enquanto o polling continua, o merchant fica online
  4. 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
Se você escolher usar webhook, configure um dos dois modos de operação: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:
{
  "code": "KEEPALIVE",
  "fullCode": "KEEPALIVE",
  "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e"
}
Resposta esperada:
HTTP/1.1 202 Accepted
Comportamento:
  • Resposta com 202 Accepted → todos os merchants ficam online
  • Qualquer outro código → todos os merchants ficam offline
  • Response body é ignorado
Exemplo:
curl -X POST 'http://localhost:8080/webhook' \
  -H 'X-IFood-Signature: 6c0a429606266905349388ebc1eb12b8b98524dddd6b4bdc41c4b67591075b4c' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e"
  }'
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:
{
  "code": "KEEPALIVE",
  "fullCode": "KEEPALIVE",
  "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e",
  "merchantIds": [
    "cad65e8f-6fc6-438a-b159-e64a902a6b9a",
    "438a5e8f-6fc6-438a-b159-e64a902a6879"
  ]
}
Resposta esperada:
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "merchantIds": ["cad65e8f-6fc6-438a-b159-e64a902a6b9a"]
}
Comportamento:
  • Retorne apenas os IDs dos merchants online
  • Merchants não inclusos na resposta ficam offline
  • Resposta deve ser 202 Accepted com JSON contendo merchantIds
Exemplo:
curl -X POST 'http://localhost:8080/webhook' \
  -H 'X-IFood-Signature: dc900bca38c8b6f908ea688a24604fa581921d1211da4211e4f5e139732c2ff1' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e",
    "merchantIds": [
      "cad65e8f-6fc6-438a-b159-e64a902a6b9a",
      "438a5e8f-6fc6-438a-b159-e64a902a6879"
    ]
  }'
  1. Navegue até a seção de webhooks
  2. Escolha entre os modos:
    • Por aplicativo (padrão): um heartbeat para todos os merchants
    • Por merchant: heartbeats com lista de merchants, resposta com IDs online
Veja webhook overview para instruções de configuração.Se você usa polling de eventos, a presença é mantida automaticamente:
  • 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.
AspectoWebhookPolling
IniciativaiFood envia heartbeatsVocê consulta status
FrequênciaA cada 30 segundosA cada 30 segundos (recomendado)
LatênciaQuase imediataAté 30 segundos de atraso
ComplexidadeModerada (validar assinatura)Simples (chamadas HTTP regulares)
Controle granularPor aplicativo ou por merchantAutomático (enquanto polling ativo)
Overhead de redeBaixo (iFood inicia)Moderado (você inicia)
Ideal paraMúltiplos merchants com status diferentesPoucos merchants, arquitetura simples
ManutençãoConfigure no Developer PortalConfigure apenas o intervalo
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.Requisições de polling usam autenticação JWT Bearer. Mantenha seu token seguro e não o compartilhe.
Cenário: Seu sistema está sempre disponível e todos os merchants devem ficar online.Implementação:
@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if event['code'] == 'KEEPALIVE':
        # Modo por aplicativo: responda 202 para todos os merchants
        return '', 202

    # ... processar outros eventos
Cenário: Merchants fecham em horários diferentes. Você precisa marcar apenas os abertos como online.Implementação:
@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if 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}), 202
        else:
            # Modo por aplicativo: todos os abertos
            return '', 202

    # ... processar outros eventos
Cenário: Sistema offline por manutenção. Você precisa marcar todos os merchants como offline.Implementação:
@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if event['code'] == 'KEEPALIVE':
        if 'merchantIds' in event:
            # Modo por merchant: responda com lista vazia
            return jsonify({'merchantIds': []}), 202
        else:
            # Modo por aplicativo: responda com erro
            return 'Service Unavailable', 503

    # ... processar outros eventos
Cenário: Você usa polling como único método de integração.Implementação:
import time
from datetime import datetime

def keep_presence_active():
    while True:
        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 mantida
                pass

            # Aguardar 30 segundos antes do próximo polling
            time.sleep(30)

        except Exception as 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 rodando
keep_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
  • Sempre envie ACK após processar eventos
ProblemaCausaSolução
Merchants aparecem como offlineResposta sem 202 AcceptedVerifique status HTTP da resposta
Alguns merchants offlineModo por merchant: IDs não retornadosRetorne todos os IDs dos merchants online
Heartbeats não chegamWebhook não habilitadoHabilite webhook no Developer Portal
Signature inválidaAssinatura não correspondeValide usando a chave correta
Timeouts frequentesWebhook respondendo lentamenteOtimize a resposta para < 5 segundos
ProblemaCausaSolução
Merchants offline apesar de polling ativoPolling não está realmente rodando a cada 30sVerifique logs e intervalos do loop
Polling retorna erro 429Limite de requisições excedido (6000 RPM)Reduza frequência ou divida em lotes
Merchants offline após reinicializaçãoPolling parou durante deployImplemente health checks e recuperação automática
Token expirado durante pollingToken tem validade limitadaImplemente refresh de token antes de expirar
Esta página foi útil?
Avalie sua experiência no novo Developer portal: