Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Pedidos agendados (Scheduled orders)

Permita que clientes agendem entrega para otimizar operações durante picos de demanda e melhorar experiência.

O que é um pedido agendado

Pedido agendado é quando o cliente escolhe o horário exato para receber ou retirar seu pedido, ao invés de entrega/retirada imediata. Funciona com:

DELIVERY: Entrega no horário agendado
TAKEOUT: Retirada no horário agendado
DINE_IN: Consumo no local em horário reservado

Respeite o horário do cliente. Nunca antecipe preparação ou entrega.

Identificar pedido agendado

Verifique orderTiming e objeto scheduled:

{
  "orderTiming": "SCHEDULED",
  "scheduled": {
    "deliveryDateTimeStart": "2024-04-25T19:00:00Z",
    "deliveryDateTimeEnd": "2024-04-25T19:30:00Z",
    "preparationStartDateTime": "2024-04-25T18:45:00Z"
  },
  "orderType": "DELIVERY"
}

Campo	Significado
`orderTiming = "SCHEDULED"`	Pedido é agendado
`deliveryDateTimeStart`	Início da janela de entrega/retirada
`deliveryDateTimeEnd`	Fim da janela de entrega/retirada
`preparationStartDateTime`	Quando você deve começar a preparar

Fluxo passo a passo

1. Confirmar pedido

Confirme o recebimento em 8 minutos a partir de preparationStartDateTime. Veja prazo de confirmação.

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/confirm" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Resposta: 202 Accepted

2. Verificar recomendação de preparação

Se tiver "Preparação Inteligente" habilitada, o sistema calcula o melhor momento:

{
  "RECOMMENDED_PREPARATION_START": "2024-04-25T18:45:00Z"
}

Use como referência, mas respeite preparationStartDateTime se for mais restritivo.

3. Iniciar preparação

Comece a preparar no horário correto:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/startPreparation" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Timing:

Nunca antes de preparationStartDateTime
Comece próximo ao horário calculado
Termine próximo a deliveryDateTimeStart

Resposta: 202 Accepted

4. Notificar pronto

Quando terminar:Para DELIVERY:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/dispatch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Para TAKEOUT/DINE_IN:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/readyToPickup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Resposta: 202 Accepted

Cálculo crítico de prazos

A chave para pedidos agendados é entender preparationStartDateTime:

Fórmula

preparationStartDateTime = deliveryDateTimeStart − deliveryTime

Onde deliveryTime é a duração média de preparação da loja (em minutos).

Exemplo prático

Cenário: Cliente agenda entrega para 20:00, sua loja tem 40 minutos de tempo de preparo

Entrega agendada: 20:00
Tempo de preparo: 40 minutos
─────────────────────────
Começar prep em: 19:20
Prazo SLA: 19:28 (8 min após 19:20)

Timeline esperada:

16:00 → Cliente agenda para 20:00 na app
16:01 → Você recebe CONFIRMED
16:02 → Confirma pedido (dentro de 8 min após 19:20)
19:00 → Sistema alerta: "começar prep em 20 min"
19:20 → Comanda imprime — comece preparação
19:20 → Chamar /startPreparation
19:28 → Prazo máximo para confirmar passou (não é problema, já confirmou em 16:02)
20:00 → Chamar /dispatch ou /readyToPickup
20:00 → Entregador coleta ou cliente retira

Regras importantes

Não antecipe

Errado: Começar prep antes de preparationStartDateTime

Cliente pode não estar em casa (DELIVERY)
Comida fica fria/morna
Cliente vê ordem saindo mais cedo que agendado

Correto: Começar exatamente em preparationStartDateTime ou logo depois

Respeite a janela

{
  "deliveryDateTimeStart": "2024-04-25T19:00:00Z",
  "deliveryDateTimeEnd": "2024-04-25T19:30:00Z"
}

Sistema aceitará entrega durante toda a janela, mas respeite o início.

Confirmação de pedido (SLA de 8 minutos)

Embora você confirme logo que recebe, o SLA técnico é:

8 minutos após preparationStartDateTime

Isso dá tempo para:

Validar disponibilidade de itens
Alertar cliente se houver atraso

Você já confirmou no início (16:02 no exemplo), então está coberto.

Casos de uso comuns

Caso 1: Delivery agendado no horário

16:00 → Cliente agenda para 20:00
16:01 → Recebe CONFIRMED
16:02 → Confirma via API
19:20 → Recebe alerta "começar prep"
19:20 → Chama /startPreparation
19:50 → Termina prep
20:00 → Chama /dispatch exatamente
20:15 → Entregador chega e coleta
20:40 → Cliente recebe

Caso 2: Takeout agendado com atraso

17:00 → Cliente agenda para 19:30
17:01 → Recebe CONFIRMED
17:02 → Confirma
19:00 → Recebe alerta "começar prep em 30 min"
19:30 → Chama /startPreparation (15 min antes para estar pronto)
19:45 → Termina prep
19:50 → Chama /readyToPickup
20:00 → Cliente chega, busca no balcão

Caso 3: Janela de 30 minutos

13:00 → Cliente agenda 18:00-18:30
13:01 → Recebe CONFIRMED
13:02 → Confirma
17:20 → Comanda imprime (40 min antes)
17:20 → Chama /startPreparation
18:00 → Termina prep
18:00 → Chama /dispatch
18:15 → Entregador coleta (dentro da janela)
18:40 → Cliente recebe (dentro da janela)

Integração com POS

Mapear estados

Estado	Seu POS	Ação
`PLACED`	Agendado	Mostrar no calendário
`CONFIRMED`	Confirmado	Marcar como confirmado
`PREPARING`	Em preparo	Enviar para cozinha com horário
`READY_TO_PICKUP`	Pronto	Avisar "pronto para X"
`DISPATCHED`	Saiu	Marcar como despachado
`CONCLUDED`	Entregue	Arquivar

Notificar equipe

Imprima na comanda:

═════════════════════════
  PEDIDO AGENDADO
═════════════════════════

ID: #12345
Cliente: João Silva

Agendado para: 20:00
Comece prep em: 19:20
Prazo máximo: 19:28

[ITENS]
- Hamburguesa x1
- Refrigerante x1

═════════════════════════

Validação e testes

Antes de ir para produção

Testar com orderTiming = "SCHEDULED"
Validar cálculo de preparationStartDateTime
Testar com IMMEDIATE também (para não quebrar)
Validar que /startPreparation respeita horário
Testar dispatch/readyToPickup no horário correto
Testar DELIVERY, TAKEOUT e DINE_IN agendados
Validar SLA de 8 minutos

Dicas de debug

Se pedido é cancelado:

Verifique se confirmou dentro de 8 minutos de preparationStartDateTime
Verifique se preparationStartDateTime foi calculado corretamente
Verifique timezone (sempre UTC no API)

Esta página foi útil?

Avalie sua experiência no novo Developer portal: