Visão geral
Critérios de homologação
- Fazer requests no endpoint de GET /events:polling regularmente a cada 30 segundos para não perder nenhum pedido. Isso garante que o merchant fique aberto na plataforma; Utilize o header x-polling-merchants sempre que precisar filtrar eventos de um ou mais merchants. Também é possível filtrar os eventos que deseja receber por tipo e por grupo.
- Enviar POST /events/acknowledgment para todos os eventos recebidos (com status code 200) imediatamente após a request de polling.
Somente para aplicativos de Integradora Logistica, é obrigatório enviar o parâmetro excludeHeartbeat=true, ao realizar uma requisição no endpoint /events/v1.0/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 mal uso do módulo. Leia nosso artigo sobre Status de Conexão dos Parceiros no iFood.
Consultar novos pedidos
Para receber novos pedidos, você deve fazer requests no endpoint de polling regularmente a cada 30 segundos ou registrar um webhook para receber eventos. Sempre que houver um novo evento você receberá o código de resposta 200 com a lista de eventos. Caso não existam novos eventos, você receberá o código de resposta 204.
Por quanto tempo que os pedidos e eventos são disponibilizados? A API de polling mantém os pedidos e eventos até 8 horas após a data de entrega de um pedido. Depois desse período os eventos não são mais retornados. Importante ressaltar que dentro deste período, somente os eventos que não tiveram ACK enviado serão retornados, por isso é importante que o aplicativo envie o ACK de um evento somente após garantir que esse evento foi persistido no aplicativo.
Ordenação dos eventos
Os eventos não são entregues necessariamente de maneira ordenada. Caso seja necessário, após receber todos os eventos você pode ordenar pelo createdAt.
Filtros
É possível filtrar os pedidos que você deseja receber no polling.
Filtrar por tipo de Categoria É possível filtrar os pedidos pelo tipo de Categoria utilizando os seguintes parâmetros na query: categories. O comportamento padrão será o consumo de eventos dos pedidos atuais (FOOD e GROCERY). Mais detalhes sobre os tipos de categorias de pedido.
/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)Filtrar por tipo de evento É possível filtrar os eventos pelo grupo ou pelo tipo utilizando os seguintes parâmetros na query: types e groups.
Ex:
/events:polling?groups=STATUS,DELIVERY,TAKEOUT
/events:polling?types=COL,CFM,CAN,AAO
/events:polling?groups=ORDER_STATUS&types=AAO,AADAuto-acknowledgment de eventos não filtrados Ao utilizar filtros, os eventos disponíveis não filtrados recebem acknowledgment automaticamente. Portanto, numa próxima request, se o filtro for alterado, esses eventos que receberam auto-acknowledgment não serão retornados. Se sua aplicação precisa de eventos de um tipo em um fluxo e eventos de outro tipo em outro fluxo, é necessário que sua aplicação consuma todos os eventos pelo mesmo fluxo e depois redirecione conforme a necessidade.
Duplicidade de filtros
Os groups já incluem os types. Ex: o group ORDER_STATUS já inclui os eventos PLC, CFM, RTP, DSP, CON, CAN.
Portanto, não utilize filtros duplicados como por exemplo: ?groups=ORDER_STATUS&types=PLC,CFM...
Grupo outros
Não é possível filtrar eventos do grupo OUTROS. Caso queira receber todos os eventos, não utilize filtros.
Filtrar por merchants (lojas)
Por padrão, esse endpoint retorna todos os eventos de todos os merchants aos quais o token da request têm acesso limitado a 500 merchants. É possível informar na request de quais merchants você deseja receber eventos.
Ex:
--header 'x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001,0a0000aa-0aa0-00aa-aa00-0000aa000002,0a0000aa-0aa0-00aa-aa00-0000aa000003'Filtro x-polling-merchants e Aplicativos Centralizados e Distribuídos Se você utiliza aplicativo distribuído ou centralizado e tem permissão em mais de um merchant no mesmo token, é necessário utilizar esse filtro nas requests de polling para receber eventos somente do merchant desejado, caso contrário receberá eventos de todos os merchants cujo token tem permissão.
No caso do aplicativo centralizado em que o token utilizado tem acesso a um volume elevado de merchants, também é preciso filtrar os eventos por merchant através do parâmetro x-polling-merchants no header da request (ou então pode ser o erro Bad request. Too many polling merchants). Deve-se passar a lista de ids dos merchants desejados. O limite desse header é de 100 ids. Caso o seu aplicativo tenha acesso a até 500 merchants e você não utilize o header para filtrar, o aplicativo receberá os eventos de todos os merchants. Caso o aplicativo tenha acesso a mais de 500 merchants, é necessário usar o header para filtrar e dividir em requests de 100 em 100 merchants.
Para esses casos de aplicações centralizadas com acesso a muitos merchants (>500), recomendamos utilizar o webhook para receber eventos ao invés do polling. Além do ganho de entrega em tempo real de eventos, reduz a chance de problemas no uso do x-polling-merchants.
403 - Forbidden
Ao fazer uma request de polling sem utilizar o filtro x-polling-merchants a API retornará os eventos de todos os merchants cujo token enviado na request tenha acesso.
Ao utilizar o filtro x-polling-merchants a API validará se o token tem permissão em todos os merchants informados no filtro. Caso o token não tenha permissão em algum merchant, você receberá um erro 403 e no corpo da resposta no campo unauthorizedMerchants serão informados os merchants que seu token não tem permissão.
Como contornar esse problema
Ao receber esse erro você pode imediatamente remover os merchants sem permissão do x-polling-merchants e fazer uma nova request de polling para receber os eventos dos demais merchants que você já tem acesso.
Como identificar a causa raiz do problema
- Verifique se o merchant não revogou o acesso do seu aplicativo. Nesse caso entre em contato com o responsável pelo merchant e solicite autorização novamente.
- Caso o merchant tenha aprovado o acesso recentemente, pode ser que o token utilizado foi gerado antes dessa aprovação. Nesse caso, gere um novo token para que esse novo token tenha permissão no merchant recém aprovado.
Múltiplos devices/aplicativos É possível que mais de um aplicativo esteja consumindo eventos de uma mesma loja. Para cada um desses aplicativos é gerado um identificador único com base nas credenciais utilizadas e o controle de acknowledgment é feito por esse identificador, a que chamamos de "device". Portanto é possível que um outro aplicativo receba eventos de PLACED e confirme um pedido antes que seu aplicativo o faça. Se isso acontecer, você receberá esse evento de confirmação gerado por esse outro device. Nesse caso é importante que você registre esse pedido e atualize o status com base em todos os eventos recebidos, mesmo que eles tenham sido gerados por outro device. Esse mecanismo permite por exemplo que a loja utilize seu aplicativo e o Gestor de Pedidos simultaneamente.
Rate Limit Cada cliente da API deve fazer 1 request a cada 30 segundos (para um mesmo token). Caso exceda o limite de requisições, o cliente pode ser bloqueado temporariamente. Nesses casos receberá como resposta o código 429.
Eventos de pedidos
Nessa seção você encontra todos os detalhes e exemplos de eventos:
Descrição dos eventos de pedidos
Veja em detalhes os eventos que o iFood trata em relação aos pedidos
Eventos duplicados e data do pedido Eventualmente a API pode retornar um mesmo evento mais de uma vez, como por exemplo o evento de PLACED incluindo pedidos antigos. Por esse motivo é importante que o seu aplicativo trate a unicidade dos pedidos e eventos através dos "id"s.
Portanto, ao receber um evento, deve-se verificar o id do evento e validar se esse evento (id) já não foi processado anteriormente. Caso esse evento já tenha sido recebido anteriormente, ele deve ser descartado.
Independente do motivo de um mesmo evento ter sido retornado novamente, é essencial que o acknowledgement desse evento seja feito, mesmo que já tenha sido feito anteriormente. Em suma: sempre faça a request de acknowledgment com todos os eventos que recebeu e processou.
Atenção: caso sua aplicação receba novamente um evento de PLACED já recebido anteriormente, descarte o evento repetido e não gere um novo pedido no seu sistema!
Acknowledgment de eventos
Ao receber novos eventos, você sempre deve enviar /acknowledgment para que a API não te envie esse mesmo evento novamente;
No corpo da request, você pode enviar um array contendo apenas os ids dos eventos ou se preferir pode enviar todo o conteúdo do evento recebido no polling. Nesse último caso, todos os outros campos serão ignorados, pois a API utiliza somente o id do evento para registrar o acknowledgment. Cada request aceita uma lista de no máximo 2000 ids de eventos.
Orientações importantes:
- Faça uma request de acknowledgment para cada request de polling com resultados.
- Caso receba eventos que não sejam utilizados pelo seu aplicativo, envie o acknowledgment desses eventos mesmo assim para que não fique recebendo-os a cada polling novamente. É fundamental que esse seja o tratamento padrão para todo evento ainda não mapeado no seu aplicativo.
- Só é preciso enviar acknowledgment do evento uma única vez.
Outros conteúdos que podem ser do seu interesse: