logo
logo

Docs / Order

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

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

orderTypeDescrição
DELIVERYPedidos que devem ser entregues no endereço escolhido pelo cliente.
TAKEOUTPedidos que o próprio cliente faz a retirada no estabelecimento. Entenda todos os detalhes de um pedido Pra retirar.
INDOORPedidos cujo cliente faz o consumo no estabelecimento. Pode ser retirado no balcão ou entregue na mesa. Entenda todos os detalhes de um pedido Na Mesa.

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

orderTimingDescrição
IMMEDIATEPedidos que devem ser preparados imediatamente e enviados o mais breve possível (as soon as possible.
SCHEDULEDPedidos 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.

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.

Ciclo de Vida do 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

Etapas da recepção de um pedido.

ClientAPI1- Get new ordersGET /events:pollingEvents (without ACK)2- Received eventsAcknowledgmentPOST /events/acknowledgment3- Get order detailsGET /orders/{id}order details4- Confirm orderPOST /confirmGet result of confirm requestGET /events:pollingCONFIRMED (CFM)5- Order is ready to delivery or takeoutPOST /dispatch or readyToPickupClientAPI

Para receber novos pedidos, você deve fazer requests no endpoint de polling regularmente a cada 30 segundos. 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 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.

Filtros

É possível filtrar os tipos de eventos que você deseja receber.

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,AAD

Auto-acknowledgement de eventos não filtrados Ao utilizar filtros, os eventos disponíveis não filtrados recebem acknowledgement automaticamente. Portanto, numa próxima request, se o filtro for alterado, esses eventos que receberam auto-acknowledgement não serão retornados.

Filtrar por Merchants (lojas)

Por padrão, esse endpoint retorna todos os eventos de todos os merchants aos quais o token da request tem acesso. Em um cenário em que o token utilizado tem acesso a um volume elevado de merchants, é possível filtrar os eventos por merchant através do parâmetro x-polling-merchants no header da request. Deve-se passar a lista de ids dos merchants desejados. O limite desse header é de 100 ids.

Ex:

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

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

Nessa seção você encontra todos os detalhes e exemplos de eventos.

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 do "id" e a data através do "createdAt".

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.

Atenção: só se deve gerar um novo pedido ou atualizar o status de um pedido depois de validar se o evento já não foi processado anteriormente.

Ao receber novos eventos, você sempre deve enviar acknowledgement para que a API não te envie esse mesmo evento novamente;

No corpo da request, envie um array contendo apenas os ids dos eventos. Cada request aceita uma lista de no máximo 2000 ids de eventos.

Recomendações importantes:

  • Faça uma request de acknowledgment para cada request de polling com resultados.
  • Caso receba eventos que não utilizados pelo seu aplicativo, envie o acknowledgment desses eventos mesmo assim para que não fique recebendo-os a cada polling novamente. Recomendamos 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.

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 (superior a 8 horas) o endpoint retorna 404.

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

É obrigatório consultar detalhes do pedido Não é permitido confirmar um pedido sem antes consultar os detalhes do mesmo. Se o aplicativo tentar confirmar um pedido sem ter obtido os detalhes, a requisição de confirmação pode retornar 202 mas depois será descartada internamente.

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 /orders/{id}/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.

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.

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

Pedidos que não são entregues no endereço do cliente, como "Na Mesa" e "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", quando 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 iFood não é preciso enviar essa request, pois ela é gerada automaticamente quando o pedido é coletado pelo entregador parceiro.

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? Os pedidos entregues por entregadores parceiros do iFood (fullservice) são concluídos logo após a entrega do pedido no destino. Já os pedidos de lojas com entrega própria (marketplace) serão concluídos 4 horas depois da hora prevista para entrega. Até esse período, é possível que o cliente entre em contato com o atendimento ao cliente do iFood e alguma ocorrência seja registrada, como por exemplo uma reclamação de um item faltante. Passadas as 4 horas, caso o pedido não tenha nenhuma ocorrência ele será concluído automaticamente por um serviço interno. Exemplo: Um pedido feito às 13:00 hs com entrega prevista para às 13:40 hs será concluído automaticamente até as 17:40 hs.

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#

Caso a loja queira cancelar um pedido, deve fazer a solicitação através do endpoint: /orders/{id}/requestCancellation

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 /orders/{id}/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.

As regras de cancelamento podem variar de acordo com o momento do pedido (antes ou depois da confirmação). Em algumas situações é possível que o serviço de cancelamento consulte o cliente se ele aceita ou não o cancelamento do pedido.

ClientAPIService CancellationPOST /orders/{id}/requestCancellationAccepted (202)/requestCancellationRules validationCAN or CARFGET /events:pollingCAN or CARFClientAPIService Cancellation

É obrigatório informar o código de cancelamento de acordo com a tabela abaixo: O campo reason é obrigatório para o código 501.

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

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.

O cliente também pode solicitar o cancelamento de um pedido. Isso só é permitido em alguns momentos como antes da confirmação.

Handshake de Cancelamento Essa opção do cliente solicitar o cancelamento pode não estar habilitada para todos as lojas.

Quando isso ocorre a loja receberá um evento de CONSUMER_CANCELLATION_REQUESTED no polling e deve se manifestar através dos seguintes endpoints:

Essa request será processada pelo serviço de cancelamento (de maneira assíncrona) e a loja receberá no próximo polling o(s) seguinte(s) evento(s):

  • CONSUMER_CANCELLATION_DENIED, ou
  • CONSUMER_CANCELLATION_ACCEPTED e CANCELLED
ConsumerService CancellationAPIClientcancell my orderCCRGET /events:pollingCCRThe store make a decisionPOST accept or denyaccept or denyCCA or CCDConsumerService CancellationAPIClient

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.

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

É possível rastrear a entrega do pedido através do endpoint de tracking do módulo de API de Logística. 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.

CampoDescrição
deliveryEtaEndTempo Estimado para Entrega do Pedido
expectedDeliveryData/hora estimada para entrega do pedido
latitudeLatitude do entregador no momento da consulta
longitudeLongitude do entregador no momento da consulta
pickupEtaStartTempo Estimado até a Origem (Coleta do Pedido)
trackDateData/hora da consulta (em segundos)

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

Testes

Para gerar um pedido de teste, é preciso simular uma compra normal pelo aplicativo ou site do iFood.

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.

Perfil Modo Teste

Alguns usuários possuem o perfil "Somente Teste" mas alguns outros perfis podem fazer pedidos também em modo de produção. Se esse for o seu caso, e se nenhuma loja de teste aparece nos resultados de pesquisa, verifique se o modo de teste está habilitado.

Para habilitar o "Modo Teste", clique em "Perfil", depois em "Editar Dados" e em seguida clique no ícone para habilitar.

Caso não apareça nenhuma loja de teste e você não tem a opção de habilitar o modo teste, abra um chamado para que nosso time de atendimento possa te ajudar.

Verifique se o seu aplicativo está fazendo polling regularmente Caso a sua loja de teste apareça como fechada, certifique-se de que o seu aplicativo esteja fazendo polling e as outras condições de abertura.

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.

Para testar o Na mesa, é preciso primeiro gerar um QR Code. Para isso, acesse o portal do parceiro e no menu "Serviços" clique em "Na Mesa".

Se a loja ainda não fez a adesão, clique em "Quero saber mais" e depois em continuar para ter acesso à geração do QR Code.

Escolha o tipo de QR Code (se optar pela opção em cada mesa, informe a quantidade de mesas) e clique em continuar. Informe o tempo de preparo e clique em "Finalizar configuração".

Agora faça o download dos QR Codes e use o seu smartphone para escanear o QR Code e fazer um pedido de teste.

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

Cupomtargetsponsorship
VOUCHER_IFOODCARTIFOOD
VOUCHER_RESTCARTMERCHANT
VOUCHER_ENTGRATISDELIVERY_FEEIFOOD

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

Vouchers do tipo ITEM e PROGRESSIVE_DISCOUNT_ITEM Não disponibilizamos vouchers de testes do tipo ITEM pois nesse cenário é necessário criar uma campanha específica para um item do catálogo. Utilize os exemplos abaixo para mapear no seu aplicativo.

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: