Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Fundamentos

Tipos de pedido, ciclo de vida e arquitetura de eventos — os conceitos que você precisa saber antes de começar a implementar.

O que é o módulo Order

O módulo Order gerencia todo o ciclo de vida do pedido — desde a recepção até a entrega. É obrigatório para integrar sua loja com a plataforma iFood.Com essa integração você consegue:

Receber pedidos em tempo real
Confirmar ou rejeitar pedidos automaticamente
Acompanhar preparação e entrega
Resolver problemas pós-entrega (cancelamentos, reembolsos)

Importante: Entenda os conceitos desta página antes de prosseguir para o Guia de Implementação.

Tipos de pedido

Cada pedido possui um orderType que define como o cliente receberá seu item:

Tipo	Descrição	Quando usar
`DELIVERY`	Entrega no endereço do cliente	Restaurantes, mercados com serviço de entrega
`TAKEOUT`	Cliente retira no estabelecimento	Retirada no balcão ou área de pickup
`DINE_IN`	Consumo no local	Restaurantes com consumo presencial

Categorias de pedido

O campo category identifica o tipo de estabelecimento:

Categoria	Origem	Características
`FOOD`	Restaurantes	Todos os tipos de entrega (DELIVERY, TAKEOUT, DINE_IN)
`FOOD_SELF_SERVICE`	Totens e quiosques	Pedidos automatizados de autoatendimento
`GROCERY`	Supermercados, farmácias, pet shops	Virtual bag API; picking workflow
`ANOTAI`	Integrações de terceiros	Plataforma de agregadores

Ciclo de vida do pedido

Importante: Cada transição é acionada por eventos, não por polling. Você não pergunta "qual é o estado?", você recebe notificações quando o estado muda.

Momento do pedido

Prazo de confirmação (SLA)

Todo pedido deve ser confirmado em 8 minutos:

Pedidos IMMEDIATE: 8 minutos após createdAt
Pedidos SCHEDULED: 8 minutos após preparationStartDateTime

Falha na confirmação resulta em cancelamento automático e penalidades na conta.Como implementar: Workflow — Confirmar pedidoComo implementar: Veja Workflow — Obter novos pedidos para exemplos práticos.Como implementar: Veja Workflow — Rastrear entregador para exemplos.Como implementar: Veja Workflow — Alterações parciais para como processar.

Arquitetura event-driven

Em vez de perguntarem constantemente ao sistema o estado do pedido, o Order API funciona com eventos — iFood notifica você quando o estado muda.Padrão de comunicação:

iFood publica evento quando algo acontece (novo pedido, cliente cancela, entregador atribuído, etc.)
Você reage ao evento chamando uma ação (confirmar, iniciar preparo, etc.)
Seu sistema fica sempre sincronizado sem fazer requisições desnecessárias

Dois modos de receber eventos:

Polling — Você consulta a cada 30 segundos se há eventos novos (mais simples para começar)
Webhooks — iFood envia eventos para seu endpoint (mais escalável)

Como escolher:

Comece com polling enquanto desenvolve
Migre para webhooks quando processar >1000 pedidos/dia

Como implementar: Veja Workflow — Obter novos pedidos para exemplos práticos.

Eventos principais

Você precisa reconhecer estes eventos:

Evento	Significado	Próximo passo
`CONFIRMED`	Pedido chegou na sua fila	Processar no POS, confirmar via API
`CANCELLATION_REQUEST_FAILED`	Sua confirmação foi rejeitada	Reenviar confirmação ou contatar suporte
`CANCELLED`	Pedido foi cancelado	Remover da fila, liberar recursos
`DELIVERY_GROUP_ASSIGNED`	Entrega agrupada com outro	Atualizar informação de entrega
`ASSIGN_DRIVER`	Entregador designado	Pode rastrear entrega em tempo real
`HANDSHAKE_DISPUTE`	Cliente disputou	Responder antes de `expiresAt`

Leia mais: Catálogo completo de eventos

Rastreamento de entrega

Para pedidos DELIVERY com entregadores iFood:O sistema fornece rastreamento em tempo real após o entregador ser designado:

Evento disparado: ASSIGN_DRIVER (entregador atribuído)
Dados disponíveis: Latitude, longitude, ETA estimada, tempo até coleta e entrega
Limite: Máximo uma requisição a cada 30 segundos

Como implementar: Veja Workflow — Rastrear entregador para exemplos.

Resolução de disputas (Handshake platform)

Quando cliente disputa um pedido após a entrega, o sistema inicia uma negociação entre você e o cliente:

Você recebe HANDSHAKE_DISPUTE com a proposta do cliente
Você pode aceitar, rejeitar ou fazer uma contra-oferta (refund ou tempo adicional)
Você tem até expiresAt para responder
Sem resposta = ação automática (geralmente reembolso)

Importância: Disputas não respondidas geram chargebacks. Responda sempre, mesmo que para rejeitar.

Como implementar: Veja Handshake Platform para referência de API e Handshake Platform Guide para exemplos práticos.

Modificações de pedido

Cliente remove/adiciona itens após confirmação? Você recebe ORDER_PATCHED com detalhes das mudanças.Tipos de mudanças:

Quantidade/unidade modificada
Item removido
Item adicionado
Item substituído

Ação necessária: Atualize seu sistema de billing/faturamento para refletir as mudanças.Como implementar: Veja Workflow — Alterações parciais para como processar.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página