Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Pedidos programados (Scheduled orders)

Permita que clientes elijan horario de entrega para optimizar operaciones durante horas pico y mejorar experiencia.

Qué es un pedido programado

Pedido programado es cuando el cliente elige hora exacta para recibir o retirar su pedido, en lugar de entrega/retiro inmediato. Funciona con:

DELIVERY: Entrega en horario programado
TAKEOUT: Retiro en horario programado
DINE_IN: Consumo en sitio en hora reservada

Crítico: Respete horario del cliente. Nunca prepare ni entregue antes.

Identificar pedido programado

Verifique orderTiming y 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 es programado
`deliveryDateTimeStart`	Inicio ventana entrega/retiro
`deliveryDateTimeEnd`	Fin ventana entrega/retiro
`preparationStartDateTime`	Cuándo debe comenzar preparación

Flujo paso a paso

1. Confirmar pedido

Confirme la recepción en 8 minutos desde preparationStartDateTime. Vea plazo de confirmación.

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"

Respuesta: 202 Accepted

2. Verificar recomendación de preparación

Si "Preparación Inteligente" habilitada, sistema calcula mejor momento:

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

Use como referencia, pero respete preparationStartDateTime si más restrictivo.

3. Iniciar preparación

Comience preparación a hora correcta:

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
Comience cerca hora calculada
Termine cerca de deliveryDateTimeStart

Respuesta: 202 Accepted

4. Notificar listo

Cuando termine: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"

Respuesta: 202 Accepted

Cálculo crítico de plazos

La clave para pedidos programados es entender preparationStartDateTime:

Fórmula

preparationStartDateTime = deliveryDateTimeStart − deliveryTime

Donde deliveryTime es duración promedio preparación (en minutos).

Ejemplo práctico

Escenario: Cliente programa entrega para 20:00, su tienda tarda 40 minutos

Entrega programada: 20:00
Tiempo preparación: 40 minutos
─────────────────────────
Comenzar prep en: 19:20
Plazo SLA: 19:28 (8 min después 19:20)

Timeline esperada:

16:00 → Cliente programa para 20:00 en app
16:01 → Usted recibe CONFIRMED
16:02 → Confirma pedido (dentro 8 min después 19:20)
19:00 → Sistema alerta: "comenzar prep en 20 min"
19:20 → Comprobante imprime — comience preparación
19:20 → Llame /startPreparation
19:28 → Plazo SLA pasó (no problema, ya confirmó 16:02)
20:00 → Llame /dispatch o /readyToPickup
20:00 → Conductor llega o cliente retira

Reglas importantes

Nunca prepare anticipado

Errado: Comience prep antes de preparationStartDateTime

Cliente puede no estar en casa (DELIVERY)
Comida se enfría/calienta
Cliente ve pedido saliendo antes de lo programado

Correcto: Comience exactamente en preparationStartDateTime o poco después

Respete la ventana

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

Sistema permite entrega durante ventana completa, pero respete inicio.

Confirmación de pedido (SLA 8 minutos)

Aunque confirme inmediatamente, SLA técnico es:

8 minutos después preparationStartDateTime

Esto permite tiempo para:

Validar disponibilidad artículos
Alertar cliente si hay atraso

Ya confirmó temprano (16:02 en ejemplo), está cubierto.

Escenarios comunes

Escenario 1: Entrega programada a tiempo

16:00 → Cliente programa para 20:00
16:01 → Recibe CONFIRMED
16:02 → Confirma vía API
19:20 → Obtiene alerta "comenzar prep"
19:20 → Llama /startPreparation
19:50 → Prep lista
20:00 → Llama /dispatch exactamente
20:15 → Conductor llega y recoge
20:40 → Cliente recibe

Escenario 2: Retiro programado con margen

17:00 → Cliente programa para 19:30
17:01 → Recibe CONFIRMED
17:02 → Confirma
19:00 → Obtiene alerta "comenzar prep en 30 min"
19:30 → Llama /startPreparation (15 min antes para estar listo)
19:45 → Prep lista
19:50 → Llama /readyToPickup
20:00 → Cliente llega, retira en mostrador

Escenario 3: Ventana 30 minutos

13:00 → Cliente programa 18:00-18:30
13:01 → Recibe CONFIRMED
13:02 → Confirma
17:20 → Comprobante imprime (40 min antes)
17:20 → Llama /startPreparation
18:00 → Prep lista
18:00 → Llama /dispatch
18:15 → Conductor recoge (dentro ventana)
18:40 → Cliente recibe (dentro ventana)

Integración con POS

Mapear estados

Estado	Su POS	Acción
PLACED	Programado	Mostrar en calendario
CONFIRMED	Confirmado	Marcar confirmado
PREPARING	Preparando	Enviar cocina con hora
READY_TO_PICKUP	Listo	Avisar "listo para X"
DISPATCHED	Salió	Marcar despachado
CONCLUDED	Entregado	Archivar

Notificar equipo

Imprima en comprobante:

═════════════════════════
  PEDIDO PROGRAMADO
═════════════════════════

ID: #12345
Cliente: Juan Silva

Programado para: 20:00
Comience prep en: 19:20
Plazo máximo: 19:28

[ARTÍCULOS]
- Hamburguesa x1
- Bebida x1

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

Validación y pruebas

Antes de ir en vivo

Pruebe con orderTiming = "SCHEDULED"
Valide cálculo preparationStartDateTime
Pruebe IMMEDIATE también (para no romper)
Verifique /startPreparation respeta timing
Pruebe dispatch/readyToPickup hora correcta
Pruebe DELIVERY, TAKEOUT, DINE_IN programados
Valide SLA 8 minutos

Consejos debug

Si pedido se cancela:

Verifique si confirmó dentro 8 minutos preparationStartDateTime
Verifique si preparationStartDateTime calculado correctamente
Verifique timezone (siempre UTC en API)

Próximas lecturas

Retiro programado — Para retirar
Flujo general — Guía implementación
Detalles pedido — Estructura completa
Referencia API — Endpoints
Eventos cronograma — Catálogo eventos

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: