Visão geral

Polling é um método simples para receber atualizações de uma API. Seu sistema envia requisições regulares, a cada 30 segundos, para o endpoint GET /events:polling e verifica se há novos eventos. A API retorna as informações novas desde a última requisição.Quando houver eventos, a API retorna o código 200 com a lista. Se não houver eventos, retorna 204.O polling é fácil de implementar, mas pode aumentar o tráfego e causar atrasos em comparação com webhooks.

Retenção de eventos

A API mantém pedidos e eventos por até 8 horas após a entrega. Após esse prazo, a API não retorna os eventos. A API só retorna eventos sem ACK. Envie o ACK apenas depois de garantir que armazenou o evento.

Ordenação de eventos

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

Filtros

Você pode filtrar os pedidos recebidos no polling.

Filtro por categoria

Use o parâmetro categories na query para filtrar pedidos por categoria. Por padrão, a API retorna eventos para as categorias FOOD e GROCERY. Consulte as categorias de pedido para mais detalhes.

/events:polling?categories=FOOD,GROCERY,ANOTAI,FOOD_SELF_SERVICE 
/events:polling?categories=ALL (Serão retornadas todas as categorias, inclusive novas categorias que serão criadas com o tempo)

Pedidos da categoria ANOTAI só aparecem se o restaurante usa o pagamento Pagamento Online iFood no Anota AI. Caso contrário, esses pedidos não são exibidos.

Filtro por tipo de evento

Use os parâmetros types e groups para filtrar eventos pelo tipo ou grupo.Exemplos:

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

Eventos não filtrados recebem acknowledgment automático (auto-acknowlegment). Se você alterar o filtro, eventos já confirmados não serão retornados. Consuma todos os eventos em um único fluxo e repasse conforme sua lógica.Os groups já incluem os types. Evite filtros duplicados, como ?groups=ORDER_STATUS&types=PLC,CFM....Não é possível filtrar eventos do grupo OUTROS. Para receber todos os eventos, não use filtros.

Filtro por merchants

O endpoint retorna eventos de até 500 lojas que seu token acessa. Use o header x-polling-merchants para especificar lojas.Exemplo:

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

Filtro x-pooling-merchants e aplicativos centralizados e distribuídos

Se o seu aplicativo (centralizado ou distribuído) utiliza um token com permissão para vários merchants, adicione o filtro x-polling-merchants nas requests de polling. Assim, você recebe eventos apenas do merchant especificado. Sem esse filtro, o sistema envia eventos de todos os merchants vinculados ao token.Em aplicativos centralizados com tokens que acessam muitos merchants, sempre use o header x-polling-merchants para filtrar eventos por merchant. Caso contrário, pode ocorrer o erro "Bad request. Too many polling merchants". No header, envie uma lista de IDs dos merchants desejados. O limite é 100 IDs por header.Se seu aplicativo acessa até 500 merchants e você não usa o header, ele receberá eventos de todos os merchants. Para acessos acima de 500 merchants, é obrigatório usar o header e dividir as requests em lotes de até 100 merchants cada.

Para aplicativos centralizados com mais de 500 merchants, recomendamos o uso de webhooks. Webhooks entregam eventos em tempo real e reduzem problemas com o uso do filtro x-polling-merchants.

403 - Forbidden

Se você não usar o filtro x-polling-merchants ao fazer uma solicitação de polling, a API retornará eventos de todos os merchants que o token acessa.Quando você usa o filtro x-polling-merchants, a API verifica se o token tem permissão para todos os merchants informados. Se o token não tiver permissão para algum merchant, a API retorna erro 403. O corpo da resposta, no campo unauthorizedMerchants, lista os merchants sem permissão.Como resolverRemova os merchants sem permissão do filtro x-polling-merchants e envie uma nova solicitação de polling para receber eventos dos merchants autorizados.Como identificar a causaVerifique se o merchant revogou o acesso do seu aplicativo. Se necessário, peça uma nova autorização ao responsável pelo merchant.Se o merchant aprovou o acesso recentemente, o token pode ter sido gerado antes da aprovação. Gere um novo token para acessar o merchant aprovado.

Múltiplos devices ou aplicativos

Mais de um aplicativo pode consumir eventos da mesma loja. A API gera um identificador único para cada aplicativo com base nas credenciais, chamado de "device". O controle de acknowledgment usa esse identificador.Outro aplicativo pode receber e confirmar um evento do tipo PLACED antes do seu. Nessa situação, você receberá o evento de confirmação gerado por outro device. Registre e atualize o status do pedido com base em todos os eventos recebidos, mesmo que venham de outros devices.Esse mecanismo permite que a loja use diferentes aplicativos, como seu app e o Gestor de Pedidos, ao mesmo tempo.

Rate Limit Cada cliente pode fazer uma request a cada 30 segundos por token. Se exceder esse limite, a API pode bloquear o cliente temporariamente e retornar o código 429.

Eventos de pedidos

Veja nesta seção todos os detalhes e exemplos de eventos.

Eventos de pedidos

Veja em detalhes os eventos que o iFood trata em relação aos pedidos.

Know more

Eventos duplicados e data do pedido

A API pode retornar o mesmo evento mais de uma vez, incluindo eventos antigos de PLACED. Sempre verifique o ID do evento e descarte duplicatas. Não processe o mesmo evento mais de uma vez.Realize o acknowledgment para todos os eventos recebidos, mesmo que já tenha processado anteriormente.Se receber um evento de PLACED repetido, descarte-o e não crie um novo pedido.

Acknowledgment de eventos

Sempre envie /acknowledgment ao receber novos eventos para evitar recebê-los novamente. No corpo da request, envie um array com os IDs dos eventos ou o conteúdo completo recebido no polling. A API usa apenas o ID para processar o acknowledgment. Cada request aceita até 2000 IDs.Orientações:

Envie acknowledgment para cada polling com eventos.
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 permanece online enquanto sua integração realiza polling de eventos a cada 30 segundos. Se o polling parar, o merchant perde o status de online.

Saiba mais aqui sobre o conceito de presença no iFood.

Critérios de homologação

Confira abaixo os requisitos e critérios de homologação:

Para realizar a homologação de aplicativo é necessário que o mesmo já esteja pronto. Os testes são feitos no APP como um todo e não apenas nas chamadas de nossas APIs.

Pedidos de homologação com cadastros de conta Pessoal/Estudante (CPF) não serão aceitos. Apenas pedidos com cadastro de conta Profisional (CNPJ).

Enviar requests no endpoint GET /events:polling a cada 30 segundos para não perder pedidos.
Usar o header x-pooling-merchants para filtrar eventos por merchant.
Filtrar eventos também por tipo e grupo, se necessário.
EnviarPOST /events/acknowledgment para todos os eventos recebidos (código 200) imediatamente após a request de pooling.
Para aplicativos de Integradora Logística, é obrigatório enviar o parâmetro excludeHeartbeat=true ao realizar uma requisição no endpoint GET /events:polling. Isso é necessário para evitar que a loja seja aberta, causando cancelamento de pedidos e posteriormente evitando que o merchant seja penalizado na plataforma, por mau uso do módulo. Saiba mais em Status de Conexão dos Parceiros no iFood.