New iFood Developer Portal

Access the new version of the iFood developer portal

Activate new version

Visão geral

Polling é um método simples para receber atualizações de uma API. Seu sistema envia requisições regulares ao endpoint GET /events:polling e verifica se há novos eventos. A API retorna as informações novas desde a última requisição.Resposta da API:

200: Retorna lista de eventos
204: Nenhum evento novo disponível

O polling é fácil de implementar, mas pode aumentar o tráfego e causar atrasos em comparação com webhooks.

Intervalo recomendado

Execute polling a cada 30 segundos para manter a loja online e receber eventos sem atrasos.

Rate limit

O limite absoluto é de 6000 requisições por minuto (RPM) por token. Exceder esse limite resulta em erro 429 (Too Many Requests) e possível bloqueio temporário da sua integração.Para evitar problemas, mantenha o intervalo de 30 segundos sempre que possível. Se sua integração gerencia múltiplos merchants, agrupe as requisições sequencialmente dentro do mesmo ciclo de 30 segundos. Evite aproximar-se do limite de 6000 RPM para garantir estabilidade da integração.

Retenção de eventos

A API mantém eventos por até 8 horas após a entrega do pedido. Após esse prazo, os eventos não são mais retornados. A API retorna apenas eventos sem acknowledgment (ACK). Envie o ACK somente após garantir que armazenou o evento com segurança.

Ordenação de eventos

A API pode entregar eventos fora de ordem. Ordene os eventos pelo campo createdAt após recebê-los para garantir a sequência correta.

Filtros

Você pode filtrar os eventos recebidos no polling.

Filtro por categoria

Use o parâmetro categories para filtrar pedidos por categoria. Por padrão, a API retorna eventos das categorias FOOD e GROCERY.Exemplos:

GET /events:polling?categories=FOOD,GROCERY,ANOTAI,FOOD_SELF_SERVICE
GET /events:polling?categories=ALL

categories=ALL retorna todas as categorias, incluindo novas categorias criadas futuramente.

Pedidos da categoria ANOTAI só aparecem se o restaurante usa Pagamento Online iFood no Anota AI.

Consulte todas as categorias de pedido

Filtro por tipo de evento

Use types e groups para filtrar eventos específicos.Exemplos:

GET /events:polling?groups=STATUS,DELIVERY,TAKEOUT
GET /events:polling?types=COL,CFM,CAN,AAO
GET /events:polling?groups=ORDER_STATUS&types=AAO,AAD

Como funciona o filtro

Auto-acknowledgment de eventos não filtrados: Quando você aplica filtros, os eventos que não correspondem aos critérios recebem acknowledgment automático. Isso significa que eventos já confirmados não serão retornados em requisições futuras.Impacto na mudança de filtros: Se você alterar os filtros após já ter recebido eventos, os eventos anteriormente confirmados não serão retornados novamente. Por isso, recomendamos:

Defina seus filtros desde o início
Consuma todos os eventos em um único fluxo
Repasse os eventos conforme sua lógica de negócio

Relação entre groups e types: Os groups já incluem os types correspondentes. Evite usar ambos simultaneamente para os mesmos eventos, como ?groups=ORDER_STATUS&types=PLC,CFM..., pois isso cria filtros duplicados desnecessários.Limitações:

Não é possível filtrar eventos do grupo OUTROS
Para receber todos os eventos sem filtros, não use os parâmetros types ou groups

Para maior flexibilidade, consuma todos os eventos sem filtros e implemente a lógica de seleção no seu sistema.

Filtro por merchants

O endpoint retorna eventos de até 500 merchants por requisição. Use o header x-polling-merchants para especificar quais lojas.Exemplo:

GET /events:polling
--header 'x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001,0a0000aa-0aa0-00aa-aa00-0000aa000002'

Aplicativos centralizados e distribuídos

Cenários de uso:

Merchants no token	Header obrigatório?	Comportamento
Até 500	Opcional	Sem header: retorna eventos de todos os merchants
Mais de 500	Obrigatório	Divida em lotes de até 100 merchants por requisição

Para aplicativos centralizados:

Sempre use x-polling-merchants para filtrar por merchant
Limite: 100 merchant IDs por header
Sem o header em tokens com muitos merchants: erro "Bad request. Too many polling merchants"

Para aplicativos com mais de 500 merchants, considere usar webhooks. Webhooks entregam eventos em tempo real e eliminam a necessidade de gerenciar múltiplas requisições de polling.

Erro 403 - Forbidden

Causa: Token sem permissão para um ou mais merchants especificados no header x-polling-merchants.Resposta da API:

{
  "unauthorizedMerchants": ["merchant-id-1", "merchant-id-2"]
}

Como resolver:

Remova os merchants listados em unauthorizedMerchants do header
Envie nova requisição com apenas merchants autorizados

Como identificar a causa:

Verifique se o merchant revogou o acesso do aplicativo
Se o acesso foi aprovado recentemente, gere um novo token (o token atual pode ter sido criado antes da aprovação)

Múltiplos devices ou aplicativos

Múltiplos aplicativos podem consumir eventos da mesma loja simultaneamente. A API gera um identificador único ("device") para cada aplicativo baseado nas credenciais.Como funciona:

Cada device tem controle independente de acknowledgment
Você pode receber eventos de confirmação gerados por outros devices
Registre e atualize o status do pedido com base em todos os eventos recebidos, independente da origem

Exemplo: A loja pode usar seu aplicativo e o Gestor de Pedidos do iFood ao mesmo tempo.

Eventos de pedidos

Consulte todos os tipos de eventos e exemplos

Eventos duplicados

A API pode retornar o mesmo evento mais de uma vez, incluindo eventos antigos de PLACED.Boas práticas:

Sempre verifique o ID do evento antes de processar
Descarte eventos duplicados
Não processe o mesmo evento mais de uma vez
Envie acknowledgment mesmo para eventos já processados
Se receber PLACED repetido, não crie novo pedido

Acknowledgment de eventos

Envie POST /events/acknowledgment para todos os eventos recebidos. Isso evita receber os mesmos eventos novamente.Formato da requisição:

Envie array com IDs dos eventos ou o payload completo recebido no polling
A API usa apenas o campo id para processar o acknowledgment
Limite: até 2000 IDs por requisição

Regras:

Envie acknowledgment para cada polling que retornar eventos (código 200)
Envie acknowledgment de todos os eventos, mesmo os não utilizados pelo seu sistema
Envie acknowledgment apenas uma vez por evento

Presença no polling

O merchant fica online enquanto sua integração realiza polling a cada 30 segundos. Se o polling parar, o merchant perde o status online.

Saiba mais sobre presença no iFood

Critérios de homologação

Pré-requisitos

Testamos o aplicativo completo, não apenas chamadas individuais da API. Certifique-se de que o aplicativo está totalmente funcional antes de solicitar homologação.

Contas Pessoal/Estudante (CPF) não são aceitas para homologação. Use apenas conta Profissional (CNPJ).

Requisitos obrigatórios

Execute GET /events:polling a cada 30 segundos
Use header x-polling-merchants para filtrar eventos por merchant
Filtre eventos por tipo e grupo conforme necessário
Envie POST /events/acknowledgment imediatamente após receber eventos (código 200)

Integradoras Logísticas: Envie o parâmetro excludeHeartbeat=true no endpoint de polling para evitar abrir a loja indevidamente. Isso previne cancelamento de pedidos e penalização do merchant.Saiba mais sobre Status de Conexão