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

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.

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.

Ciclo de vida do pedido

A API é orientada a eventos, sendo assim, um pedido pode ter vários eventos vinculados a ele. Segue um diagrama com os possíveis status de um pedido.

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

Etapas da recepção de um pedido.

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

Obter 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 ou o id de um pedido antigo o endpoint retorna 404.

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

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 /confirm

Em 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.

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.

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 esses casos, quando a entrega é feita por entregadores parceiros iFood, o entregador pode receber a notificação de que o pedido está pronto para ser retirado. Ainda assim, quando o pedido sair para a entrega, é preciso enviar a request /dispatch que gera uma notificação para o usuário informando que o pedido dele saiu para entrega. Quando a entrega é feita pelos entregadores parceiros do iFood não é preciso enviar essa request, pois ela é gerada automaticamente quando o pedido é coletado pelo entregador parceiro.

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. Isso evita a entrega de pedidos errados à pessoa entregadora e consequentemente ao cliente.

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.

Concluir pedido

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

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.

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:

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.

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.

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.

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.

Entrega de pedidos

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.

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

Solicitar Entregador

Mesmo que a loja possua entregadores próprios é possível contratar o serviço de entrega de entregadores parceiros do iFood para um pedido específico o que pode ser útil em situações em que ocorra uma sobrecarga ou falta de entregadores próprios.

Mais detalhes sobre o quote:

Para solicitar o entregador concordando com a cotação retornada, utilize o seguinte endpoint: /requestDriver

Esse endpoint é assíncrono. Quando sua requisição for processada você receberá um evento REQUEST_DRIVER confirmando que a requisição foi feita e em seguida o resultado da solicitação, que pode ser: REQUEST_DRIVER_SUCCESS ou REQUEST_DRIVER_FAILED.

Veja todos os detalhes desses eventos nessa seção.

Cancelamento de Entrega Sob Demanda

Para lojas parceiras que possuem entrega própria e que eventualmente contratam o serviço de Entrega Sob Demanda do iFood, em alguns casos pode ser necessário o cancelamento da solicitação de um entregador iFood. Neste caso, a loja pode cancelar somente a entrega sob demanda sem a necessidade de cancelar o pedido. O cancelamento da entrega sob demanda deve ser realizado através do endpoint POST /orders/{id}/cancelRequestDriver.

O cancelamento só será efetuado se ele for solicitado antes do aceite do entregador, neste caso nenhuma taxa será cobrada da loja. Caso seja necessário realizar o cancelamento após do aceite do entregador, deve seguir as regras estabelecidas em Cancelamento de pedido.

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_CANCELLED.

Testes

Gerar pedidos de teste

Existem duas formas de se gerar pedidos de teste:

• Geração automática de pedidos
• Simulando uma compra normal pelo aplicativo ou site do iFood

Veja a seguir as principais diferenças entre elas:

Geração Automática

Nesta modalidade, é possível gerar um pedido de teste ao clique de um botão. Este pedido será gerado com informações pré-estabelecidas, tais como: endereço de entrega, itens de catálogo e forma/meio de pagamento padrão.

Para geração automática de um pedido de teste , basta seguir o passo a passo informado abaixo:

1- Fazer login no Portal do Desenvolvedor

Faça login com seu email no Portal do Desenvolvedor.

2- Acessar o menu Testes da sua conta

Localize a opção "Testes" clicando sobre seu nome de usuário na parte superior direita ou no menu lateral da esquerda.

3- Pressionar o botão "Gerar pedido de teste"

Localize o botão "Gerar pedido de teste" no canto superior direito. Ao pressioná-lo, um modal de seleção de loja deverá se abrir.

4- Selecionar uma loja de teste

Selecione a loja onde deseja gerar o pedido na lista de lojas disponíveis.

5- Confirme a geração do pedido

Pronto! Seu pedido foi criado com sucesso e agora você poderá consultá-lo pela merchant-api e pelo site/aplicativo do iFood.

Geração Manual

Para gerar um pedido de teste com informações personalizadas (ex: escolher um item de catálogo, meio/forma de pagamento etc), é preciso simular uma compra normal pelo aplicativo ou site do iFood conforme os passos abaixo:

1- Fazer login no site ou aplicativo

Faça login no site ou aplicativo do iFood com o seu email de desenvolvedor. No menu "Testes" do portal do desenvolvedor você encontra o email cadastrado na seção "Usuário de Testes".

2- Configurar endereço de teste

No topo do site, ou aplicativo clique em "Entregar Em" e pesquise pelo endereço "Ramal Bujari, 100" e depois confirme a localização. No campo bairro informe "Bujari" e clique em "Salvar Endereço".

3- Abrir a loja

As lojas de testes, já vem configurados com o funcionamento de 24 horas por dia todos os dias da semana, mas para que ela fique aberta na plataforma é necessário que seu aplicativo esteja conectado. Portanto, é necessário que você faça requests no endpoint /events:polling regularmente para que ela se mantenha aberta.

4- Localizar a loja teste

Agora, na barra de pesquisa, digite o nome da sua loja de teste, procure na listagem e selecione-a.

5- Adicionar itens

Adicione alguns itens do seu catálogo ao pedido até atingir o valor mínimo do pedido.

6- Fechar pedido

Escolha a forma de pagamento e depois clique no botão para finalizar o pedido. Sempre que possível, escolha pagar na entrega e de preferência em dinheiro. Assim você não precisa informar dados de cartão para fazer testes.

Pronto! Seu pedido foi feito com sucesso! Agora você receberá os eventos desse pedido através da API. Para mais detalhes consulte a seção Utilizando a API.

Cupons de desconto

Para que você possa gerar pedidos de testes com cupons de descontos, disponibilizamos alguns cupons para isso. Para utilizá-los basta inserir um dos códigos abaixo antes de fechar o seu pedido clicando no botão "Adicionar Cupom".

Consulte a seção Cupons de Desconto para ter todos os detalhes sobre os tipos de cupons.

Exemplo (target ITEM)

"benefits": [
  {
    "value": 4.99,
    "target": "ITEM",
    "targetId": "1",
    "sponsorshipValues": [
      {
        "name": "IFOOD",
        "value": 4.99
      },
      {
        "name": "MERCHANT",
        "value": 0
      }
    ]
  },
  {
    "value": 4.99,
    "target": "PROGRESSIVE_DISCOUNT_ITEM",
    "targetId": "2",
    "sponsorshipValues": [
      {
        "name": "IFOOD",
        "value": 4.99
      },
      {
        "name": "MERCHANT",
        "value": 0
      }
    ]

Outros conteúdos que podem ser do seu interesse: