Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Order

Workflow

Antes de falar um pouco mais sobre o ciclo de vida de um pedido na plataforma, é importante esclarecer alguns conceitos importantes como o tipo e um momento do pedido, pois o fluxo de recepção e entrega do pedido deve variar de acordo com o tipo e o momento.

Definições

Categorias de pedidos

A API de Order do Ifood suporta diferentes categorias de pedidos, cada uma com características e ciclos de vida específicos. Abaixo, você encontrará uma descrição das categorias disponíveis:

category	Descrição
FOOD	Pedidos de restaurantes realizados pelo aplicativo ou site do iFood. Esses pedidos são, na sua maioria, de DELIVERY, mas também incluem pedidos para retirada (TAKEOUT).
FOOD_SELF_SERVICE	Pedidos de restaurantes realizados através de totens de autoatendimento. Pode ser um Totem próprio do restaurante ou Totens multi-lojas em praças de alimentação.
GROCERY	Pedidos de supermercados, pet shops, farmácias e iFood Shop. Essa categoria abrange uma ampla gama de produtos, desde alimentos e bebidas até itens de cuidado pessoal e para pets.
ANOTAI	Pedidos originados do aplicativo Anota AI

Tipos de pedidos

Existem diferentes tipos de pedidos e cada um deles exige um comportamento diferente. Isso requer tratamentos específicos no aplicativo e na operação do negócio.

orderType	Descrição
DELIVERY	Pedidos que devem ser entregues no endereço escolhido pelo cliente.
TAKEOUT	Pedidos que o próprio cliente faz a retirada no estabelecimento. Entenda todos os detalhes de um pedido Pra retirar.
DINE_IN	Pedidos que serão consumidos no próprio estabelecimento. O cliente faz o pedido e consome a refeição no local.

Momento do pedido

Nem todos os pedidos devem ser preparados e enviados imediatamente. Em alguns casos o cliente pode agendar uma data ou horário de entrega.

orderTiming	Descrição
IMMEDIATE	Pedidos que devem ser preparados imediatamente e enviados o mais breve possível. (as soon as possible)
SCHEDULED	Pedidos que não devem ser preparados imediatamente. Deve-se respeitar o horário agendado para a entrega. Entenda todos os detalhes de um pedido agendado nessa seção.

Ciclo de vida do pedido

O ciclo de vida de um pedido pode variar de acordo com a categorya do pedido. Segue um diagrama com os possíveis status de um pedido para cada categoria.

FOOD

FOOD_SELF_SERVICE

ANOTAI

Além desses status, existem vários outros eventos vinculados a um pedido que não afetam o status dele. Nessa seção você tem mais detalhes de todos esses eventos possíveis.

Fluxo de integração

Recepção de pedidos

Obter novos pedidos

Para receber novos pedidos, você deve utilizar o módulo de Events da API que pode ser através de requests no endpoint de polling regularmente a cada 30 segundos ou registrar um webhook para receber eventos

Utilizando o polling para receber eventos de pedidos

Veja em detalhes sobre como utilizar o endpoint de polling para receber eventos de pedidos

Utilizando o webhook para receber eventos de pedidos

Veja em detalhes sobre como utilizar o webhook para receber eventos de pedidos

Detalhes do pedido

Antes de confirmar ou cancelar um pedido, é necessário obter os detalhes do mesmo para que o usuário do seu aplicativo possa verificar se conseguirá preparar e entregar esse pedido, como por exemplo verificar se tem todos os itens necessários e se tem disponibilidade para efetuar a entrega no endereço informado.Através do endpoint GET /orders/{id} você pode obter todos os detalhes de um pedido.Esse endpoint retorna o código 200 e o conteúdo do pedido. Caso seja informado um id inválido na request, pedido ainda não está disponível ou o id de um pedido antigo o endpoint retorna 404.

Pedido ainda não disponível Em alguns casos pode acontecer do detalhe do pedido ainda não estar disponível quando o evento PLACED é recebido. Isso acontece porque o sistema de eventos e o sistema de detalhe de pedido funcionam em paralelo, sendo possível que o evento de PLACED seja entregue antes do detalhe de pedido estar disponível. Para mitigar esse problema, recomendamos a implementação de um mecanismo de retry para obter os detalhes do pedido. Se um retorno 404 for recebido, o sistema deve tentar novamente após um intervalo, utilizando uma estratégia de retry como exponential backoff, por até 10 minutos. Não faça retentativas infinitas, para evitar que seu aplicativo seja bloqueado.

Pedidos antigos A API mantém os detalhes dos pedidos por apenas 7 dias a partir da data do pedido. Caso seja consultado um pedido com mais de 7 dias ele não será encontrado. Cuidado para não consultar repetidamente pedidos antigos para evitar ser bloqueado temporariamente devido ao rate limit.

Nessa seção você encontrará todos os detalhes do payload de um pedido:

Detalhes de um pedido

Veja em detalhes todos os campos que um pedido pode trazer

Preparar pedido

As atualizações que um pedido recebe ao longo do seu ciclo de vida também vão variar de acordo com a categoria do pedido. Segue um diagrama das etapas de um pedido de FOOD.

Confirmar pedido

Após obter os detalhes do pedido, o usuário do aplicativo deve tomar uma decisão: confirmar ou cancelar esse pedido. Para confirmar um pedido você deve utilizar o endpoint: POST /confirmEm caso de sucesso na solicitação, você receberá o código de resposta 202 (accepted). O processamento dessa requisição é assíncrono e o resultado será retornado no próximo polling. É possível que uma request de confirmação seja descartada por alguns motivos, dentre eles, por exemplo, se o pedido já havia sido cancelado anteriormente.

Prazo para confirmação Existe um tempo máximo para confirmação dos pedidos. Caso ultrapasse esse período, o pedido é cancelado automaticamente.Limites

Pedidos IMMEDIATE: até 8 minutos após a data do pedido (createdAt)
Pedidos SCHEDULED: até 8 minutos após o horário de início do preparo (preparationStartDateTime)

Penalidades A loja pode ser fechada temporariamente se não confirmar pedidos dentro do prazo.

Imprimir pedido

Veja o template de comanda para imprimir o pedido nessa seção.

Início de preparo

Para informar o início de preparo do pedido, você deve utilizar a requisição /startPreparation.Esse evento deve ser gerado somente depois da confirmação e antes de despachar o pedido. Caso a requisição seja feita antes ou depois, ela será ignorada.Essa requisição é opcional mas o seu uso é recomendado para oferecer uma melhor experiência para o usuário, principalmente nos casos de pedidos agendados e quando você utiliza o evento RECOMENDED_START_PREPARATION para otimizar a sua operação e preparar o pedido no horário recomendado de acordo com a previsão de chegada do entregador.

Preparo inteligente O evento RECOMENDED_START_PREPARATION é gerado pelo iFood somente para pedidos com entrega feita pelos nossos entregadores parceiros e somente para as lojas que habilitaram o Preparo Inteligente. Em todos os outros cenários, deve-se observar o campo preparationStartDateTime que é disponibilizado nos detalhes do pedido. Para mais detalhes sobre o Preparo inteligente, acesse esse material.

Pedido pronto

Pedidos que não são entregues no endereço do cliente, como "Pra Retirar" não devem ser despachados. Nesse caso, o aplicativo deve enviar a request /readyToPickup para notificar o cliente que o pedido está pronto e pode ser retirado.Para pedidos "delivery", é possível enviar o /readyToPickup mas o cliente não recebe nenhuma notificação no aplicativo. Para entregadores parceiros iFood: o entregador pode receber a notificação de que o pedido está pronto para ser retirado com o envio do /readyToPickup. Neste caso, não é necessário enviar a request /dispatch, pois ela é gerada automaticamente quando o pedido é coletado pelo entregador parceiro.Para entrega própria: é necessário enviar a request /dispatch que gera uma notificação para o usuário informando que o pedido dele saiu para entrega.

Entrega de pedidos

Confirmação de coleta

Quando habilitada a validação do código de coleta, a pessoa entregadora precisará informar ao merchant um código de verificação. O operador do merchant deve então comparar o código informado com o código que ele tem acesso via o atributo pickupCode disponível nos detalhes do pedido, seja impresso na nota ou disponível numa tela no sistema. Será possível também visualizar o código através do evento DELIVERY_PICKUP_CODE_REQUESTED que será gerado para o pedido. Isso evita a entrega de pedidos errados à pessoa entregadora e consequentemente ao cliente. O aplicativo poderá realizar a request /validatePickupCode para realizar a validação do código de coleta. A validação do código de coleta está habilitado para todos os pedidos de entrega Ifood ("deliveredBy"="IFOOD"), pedidos de entrega própria ("deliveredBy"="MERCHANT") não há validação de código de coleta.

Confirmação de entrega

Quando a entrega do pedido é feita por uma pessoa entregadora parceira do iFood ("deliveredBy"="IFOOD") a pessoa entregadora faz a confirmação da entrega através de um aplicativo disponibilizado pelo iFood. Quando a entrega do pedido é feita pelo merchant ("deliveredBy"="MERCHANT") o merchant pode compartilhar com seus entregadores um site que permite que eles façam a confirmação da entrega. Para isso a pessoa entregadora deve acessar https://confirmacao-entrega-propria.ifood.com.br/ e informar o código localizador do pedido. O localizador pode ser encontrado no campo phone.localizer e deve ser impresso na comanda que acompanha o pedido para facilitar a digitação por parte do entregador. O aplicativo poderá também realizar a request /verifyDeliveryCode para realizar a validação do código de entrega. Nos casos de pedidos Para Retirada pelo cliente, também é possível utilizar o mesmo processo de validação de Confirmação de Entrega.

Rastrear entregador

Informações do entregador

Os detalhes do entregador são entregues através do evento ASSIGN_DRIVER.

Rastreio do pedido

É possível rastrear a entrega do pedido através do endpoint /tracking. Além da posição, retorna também o pickupEtaStart e deliveryEtaEnd. Com essas informações o usuário do seu aplicativo, além de ter mais transparência conseguirá, por exemplo, automatizar o início do preparo do pedido e otimizar sua operação.

Campo	Descrição
latitude	Latitude do entregador no momento da consulta. Pode ser `null` quando ainda não recebemos a posição do entregador.
longitude	Longitude do entregador no momento da consulta. Pode ser `null` quando ainda não recebemos a posição do entregador.
expectedDelivery	Data/hora estimada para entrega do pedido. Pode ser `null` quando ainda não recebemos a posição do entregador.
pickupEtaStart	Tempo estimado em segundos até a origem (coleta do pedido). Pode ser `0` ou `null` quando o entregador chega ao local de coleta ou negativo quando a coleta está atrasada.
deliveryEtaEnd	Tempo estimado em segundos para entrega do pedido. Pode ser `0` ou `null` quando o entregador chega ao local de entrega.
trackDate	Data/hora da consulta. Pode ser `null` quando ainda não recebemos a posição do entregador.

O rastreamento só está disponível para pedidos entregues pela logística iFood.

Disponibilidade dos dados e intervalo de consulta Deve ser utilizado somente depois que o evento ASSIGN_DRIVER é gerado e pode ser consultado de 30 em 30 segundos. O endpoint poderá retornar 404 até que todas as informações sobre a entrega estejam disponíveis. Nesse caso você deve fazer uma nova consulta depois de 30 segundos.Rate Limit Em caso de mau uso, o aplicativo poderá ser bloqueado pelas políticas de rate limit e throttling.

Agrupamento de entrega

É possível que algumas entregas realizadas por parceiros iFood sejam agrupadas. Isso acontece quando os nossos algoritmos de otimização identificam 2 pedidos com rotas de entrega parecidas ou complementares. Quando isso acontecer a API disponibilizará um evento de DELIVERY_GROUP_ASSIGNED.Eventualmente um entregador parceiro pode ter algum problema para realizar a entrega de pedidos agrupados. Quando isso acontecer a API disponibilizará um evento de DELIVERY_GROUP_DISMISSED.A partir do dia 12 de setembro de 2025, será realizada a migração dos eventos e passarão a seguir o novo comportamento descrito abaixo:Quando um pedido for associado um grupo de entrega, ou seja, a uma rota com múltiplos pedidos, será publicado o seguinte evento: DELIVERY_GROUP_ASSOCIATED. O metadata do evento traz a lista completa de orderIds agrupados. Quando um pedido for desassociado de um grupo de entrega, será publicado o seguinte evento: DELIVERY_GROUP_DISSOCIATED. Quando houver uma alteração no grupo de entrega (associando e desassociando um pedido ao grupo de entrega), será emitido o evento DELIVERY_GROUP_UPDATED apenas para os pedidos que já faziam parte do grupo e permanecem no grupo após a alteração. Os pedidos que estão sendo adicionados ao grupo receberão DELIVERY_GROUP_ASSOCIATED, e os pedidos que estão sendo removidos receberão DELIVERY_GROUP_DISSOCIATED.

Atenção Os eventos DELIVERY_GROUP_ASSOCIATED, DELIVERY_GROUP_DISSOCIATED e DELIVERY_GROUP_UPDATED serão publicados no dia 12 de setembro de 2025 e vão substituir os eventos anteriores.Os eventos DELIVERY_GROUP_ASSIGNED e DELIVERY_GROUP_DISMISSED serão descontinuados no dia 13 de outubro de 2025.

Conclusão do pedido

Não é possível concluir um pedido através da API. O evento de CONCLUDED é gerado somente pelo próprio iFood.

Quando o iFood conclui o pedido?RESTAURANT, PHARMACY, PET

Pedidos Imediatos:
- Entrega iFood (Fullservice): No momento da entrega do pedido ou 6 hrs + deliveryTimeInSeconds após o CONFIRMED
- Entrega Merchant (Marketplace): 4 hrs + deliveryTimeInSeconds após o CONFIRMED
Pedidos Agendados:
- Entrega iFood (Fullservice): No momento da entrega do pedido ou IDP: 6 hrs + deliveryTimeInSeconds após o scheduling.to
- Entrega Merchant (Marketplace): 4 hrs + deliveryTimeInSeconds após o scheduling.to

MARKET, HIPERMARKET

Pedidos Imediatos:
- 13 hrs + deliveryTimeInSeconds após o CONFIRMED
Pedidos Agendados:
- 13 hrs + deliveryTimeInSeconds após o scheduling.to

*deliveryTimeInSeconds é uma configuração do merchant

Cancelamento de pedido

Um pedido pode ser cancelado por vários motivos e a iniciativa de cancelar um pedido pode partir da loja, do cliente ou do iFood. Pode acontecer também do Entregador solicitar o cancelamento em alguns cenários, como por exemplo quando não encontra o cliente no endereço de entrega.

Regras de cancelamento Conheça todas as condições e regras para cancelamento de um pedido: https://portal.ifood.com.br/cases/faq/jornada-do-cancelamento#

Cancelado pela Loja

As regras de cancelamento podem variar de acordo com o momento do pedido (antes ou depois da confirmação). Neste sentido, para executar a solicitação de cancelamento através do endpoint /requestCancellation é necessário informar um código de cancelamento válido. A lista de códigos de cancelamento válidos para um pedido pode ser obtida através do endpoint /cancellationReasons.Seguem alguns exemplos de código de cancelamento e seus motivos na tabela abaixo:

Código	Motivo
501	PROBLEMAS DE SISTEMA
502	PEDIDO EM DUPLICIDADE
503	ITEM INDISPONÍVEL
504	RESTAURANTE SEM MOTOBOY
505	CARDÁPIO DESATUALIZADO
506	PEDIDO FORA DA ÁREA DE ENTREGA
507	CLIENTE GOLPISTA / TROTE
508	FORA DO HORÁRIO DO DELIVERY
509	DIFICULDADES INTERNAS DO RESTAURANTE
511	ÁREA DE RISCO
512	RESTAURANTE ABRIRÁ MAIS TARDE

Outros códigos
Existem outros códigos de cancelamento de uso exclusivo do iFood. Por isso é importante que você trate o campo motivo como string no seu aplicativo.

Penalidades Evite cancelar pedidos! O excesso de cancelamentos pode resultar em algumas penalidades como por exemplo ter a loja fechada temporariamente na plataforma.

Validação do cancelamento A solicitação de cancelamento não garante que o pedido está cancelado. Ao enviar uma request /requestCancelation , você receberá como resposta o código 202 (accepted). Isso não significa ainda que o pedido foi cancelado. Significa que a requisição foi aceita e será processada pelo serviço de cancelamento. Como resultado dessa solicitação, você poderá receber no próximo polling um dos seguintes eventos:

CANCELLATION_REQUEST_FAILED
CANCELLED

O pedido só é cancelado quando é gerado o evento de CANCELLED..

Respostas

1 - Pedido inválido

HTTP Status	Descrição
400 Bad Request	Parâmetro inválido enviado na requisição.

Body

{
  "code": "InvalidParameter",
  "message": "A descrição detalhada do erro será exibida aqui."
}

2 - Prazo de cancelamento excedido

HTTP Status	Descrição
400 Bad Request	O prazo para cancelamento foi excedido.

Body

{
  "code": "OrderExceededCancellationDeadline",
  "message": "Order has exceeded the time to be cancelled."
}

3 - Cancelamento em andamento

HTTP Status	Descrição
400 Bad Request	Já existe um cancelamento em andamento para o pedido.

Body

{
  "code": "OrderHasACancellationInProgress",
  "message": "Order {orderId} has a cancellation in progress. Please try again later."
}

4 - Pedido não encontrado

HTTP Status	Descrição
404 Not Found	O pedido solicitado não foi encontrado.

Body

{
  "code": "OrderNotFound",
  "message": "The requested order does not seem to exist."
}

5 - Nenhuma política encontrada

HTTP Status	Descrição
204 No Content	Nenhuma política foi encontrada.

Body(Sem corpo de resposta)6 - Pedido já cancelado

HTTP Status	Descrição
400 Bad Request	O pedido já foi cancelado antes.

Body

{
  "code": "400 BAD_REQUEST",
  "message": "Order {} is already cancelled."
}

Cancelado pelo cliente

O cliente também pode solicitar o cancelamento de um pedido. Isso só é permitido em alguns momentos como antes da confirmação, durante o preparo e após conclusão.Para certos cenários de solicitação de cancelamento, pode ser oferecida a oportunidade para o parceiro negociar o cancelamento com o cliente. Essa negociação é conduzida por meio da Plataforma de Negociação para Pedidos.

A Plataforma de Negociação para Pedidos é uma ferramenta destinada a facilitar, gerenciar e agilizar negociações entre duas partes, com o propósito de resolver questões relacionadas a PEDIDOS. Ela atua como intermediária e possibilita uma comunicação eficaz entre as partes envolvidas, permitindo a troca de propostas e facilitando a busca por acordos de forma eficaz.Para maiores detalhes:

Plataforma de Negociação para Pedidos

Cancelado pelo iFood

Existe um terceiro cenário em que a iniciativa do cancelamento pode partir do iFood. Isso pode acontecer de maneira automática (pedidos não confirmados dentro do prazo) ou de maneira manual através do nosso time de atendimento. Nesses casos o evento de cancelamento (CAN) será disponibilizado através do endpoint events:polling. No conteúdo do evento tem as informações do motivo do cancelamento.

Cancelamento parcial de pedido

Caso o cliente tenha algum problema com o seu pedido, como a falta de um item, é possível que ocorra um cancelamento parcial desses itens que não foram entregues. Quando isso acontecer será disponibilizado um evento de ORDER_PATCHED através do endpoint de polling, indicando que houve alguma alteração nesse pedido.Um pedido poderá ser cancelado parcialmente nos seguintes cenários:

Se o pedido foi entregue incompleto
Se o item estava inapropriado para consumo
Se o item estava errado
Se o item estava revirado

Nesses cenários, podemos ter 2 tipos de ORDER_PATCHED:

Alteração de item (CHANGE_ITEMS)

Quando há alguma alteração na quantidade ou unidade de medida (g, kg, ml, L) de algum item do pedido.

Exclusão de item (DELETE_ITEMS)

Quando um item é removido do pedido. Isso pode acontecer quando o pedido é entregue faltando algum item. Exemplo: quando a loja esquece de enviar o refrigerante. Nesse cenário, o cliente pode entrar em contato com o time de atendimento do iFood que pode então registrar a exclusão do item.

Tratamento do evento de ORDER_PATCHEDAs alterações podem gerar impactos no faturamento (valores a receber do iFood) e também nos relatórios de vendas/conciliação.O tratamento desse novo evento vai garantir que não haverá divergências tanto na conciliação como nos valores dos repasses a serem recebidos do iFood.

Outros tipos de ORDER_PATCHED Existem outros tipos de eventos de ORDER_PATCHED que podem ser gerados em outros cenários de ruptura e atualmente só estão disponíveis para mercados:

"changeType": "ADD_ITEMS"
"changeType": "REPLACE_ITEMS"

Rota devolução

A Rota de devolução retorna pedidos cancelados à loja parceira após o despacho.Como funciona

Início da devolução: O sistema cancela um pedido após o despacho e direciona o entregador para retornar à loja.

Evento gerado: DELIVERY_RETURNING_TO_ORIGIN

Solicitação do código: O entregador chega na loja e solicita o Código de Devolução.

Evento gerado: DELIVERY_RETURN_CODE_REQUESTED

Validação: O entregador valida o Código de Devolução.

Evento gerado: DELIVERY_RETURNED_TO_ORIGIN

Requisito importanteSeu sistema deve exibir o Código de Devolução quando o evento DELIVERY_RETURN_CODE_REQUESTED for recebido. O entregador precisa deste código para completar a devolução. Se a loja utiliza o App Separador (Picking iFood), o código de devolução aparecerá diretamente no appComo habilitar a Rota de devoluçãoA loja deverá entrar em contato com o suporte via Portal do Parceiro para obter mais detalhes de como habilitar esta funcionalidade.

Mais detalhes aqui

Plataforma de negociação

A Plataforma de negociação para pedidos é uma ferramenta destinada a facilitar, gerenciar e agilizar negociações entre duas partes, com o propósito de resolver questões relacionadas a PEDIDOS. Ela atua como intermediária e possibilita uma comunicação eficaz entre as partes envolvidas,permitindo a troca de propostas e facilitando a busca por acordos de forma eficaz.

Plataforma de negociaçãoEntidades, Eventos e API.

Casos de uso - ExemplosEstrutura e exemplos de eventos.

Testes

O iFood oferece duas formas de gerar pedidos de teste:

Automática — via Developer Portal: gera pedidos com dados padrão para validar integrações e fluxos básicos.
Manual — geração customizada: use quando precisar controlar itens, endereço, cupons ou outros parâmetros para testar cenários específicos.

Para instruções passo a passo, veja a página sobre como gerar pedidos de teste: Gerar pedidos de teste.

Esta página foi útil?

Avalie sua experiência no novo Developer portal: