Fundamentos

Comprenda los conceptos centrales antes de integrar. Esta guía explica lo que necesita saber para trabajar con pedidos.

Qué es el módulo Order

El módulo Order gestiona el ciclo de vida completo del pedido — desde la recepción hasta la entrega. Es obligatorio para integrar su tienda con la plataforma iFood.Con esta integración puede:

Recibir pedidos en tiempo real
Confirmar o rechazar pedidos automáticamente
Seguimiento de preparación y entrega
Resolver problemas post-entrega (cancelaciones, reembolsos)

Importante: Comprenda los conceptos de esta página antes de continuar con la Guía de Implementación.

Tipos de pedido

Cada pedido tiene un orderType que define cómo el cliente recibirá sus artículos:

Tipo	Descripción	Cuándo usar
`DELIVERY`	Entrega en la dirección del cliente	Restaurantes, mercados con servicio de entrega
`TAKEOUT`	Cliente retira en el establecimiento	Mostrador de recogida o área de pickup
`DINE_IN`	Consumo en el lugar	Restaurantes con servicio de comedor

Categorías de pedido

El campo category identifica el tipo de establecimiento:

Categoría	Origen	Características
`FOOD`	Restaurantes	Todos los tipos de entrega (DELIVERY, TAKEOUT, DINE_IN)
`FOOD_SELF_SERVICE`	Quioscos y autoservicios	Pedidos automatizados de autoservicio
`GROCERY`	Supermercados, farmacias, tiendas de mascotas	API de bolsa virtual; flujo de picking
`ANOTAI`	Integraciones de terceros	Plataforma de agregadores

Ciclo de vida del pedido

Importante: Cada transición se activa por eventos, no por sondeo. No pregunta "¿cuál es el estado?", recibe notificaciones cuando el estado cambia.

Momento del pedido

Plazo de confirmación (SLA)

Todo pedido debe confirmarse en 8 minutos:

Pedidos IMMEDIATE: 8 minutos después de createdAt
Pedidos SCHEDULED: 8 minutos después de preparationStartDateTime

Faltar a la confirmación resulta en cancelación automática y penalizaciones en la cuenta.Cómo implementar: Flujo de trabajo — Confirmar pedido

Arquitectura orientada a eventos

En lugar de preguntarle constantemente al sistema por el estado del pedido, Order API funciona con eventos — iFood le notifica cuando el estado cambia.Patrón de comunicación:

iFood publica un evento cuando algo sucede (nuevo pedido, cliente cancela, conductor asignado, etc.)
Usted reacciona al evento llamando una acción (confirmar, iniciar preparación, etc.)
Su sistema se mantiene sincronizado sin hacer solicitudes innecesarias

Dos formas de recibir eventos:

Polling — Usted verifica cada 30 segundos si hay eventos nuevos (más simple para comenzar)
Webhooks — iFood envía eventos a su endpoint (más escalable)

Cómo elegir:

Comience con polling mientras desarrolla
Migre a webhooks cuando procese >1000 pedidos/día

Cómo implementar: Vea Flujo de trabajo — Obtener nuevos pedidos para ejemplos prácticos.

Eventos principales

Debe reconocer estos eventos:

Evento	Significado	Próximo paso
`CONFIRMED`	El pedido llegó a su cola	Procesar en POS, confirmar vía API
`CANCELLATION_REQUEST_FAILED`	Su confirmación fue rechazada	Reenvíe confirmación o contacte soporte
`CANCELLED`	El pedido fue cancelado	Remover de la cola, liberar recursos
`DELIVERY_GROUP_ASSIGNED`	Entrega agrupada con otra	Actualizar información de entrega
`ASSIGN_DRIVER`	Conductor asignado	Puede rastrear entrega en tiempo real
`HANDSHAKE_DISPUTE`	Cliente disputó	Responda antes de `expiresAt`

Leer más: Catálogo completo de eventos

Rastreo de entrega

Para pedidos DELIVERY con conductores de iFood:El sistema proporciona rastreo en tiempo real después de que se asigna el conductor:

Evento disparado: ASSIGN_DRIVER (conductor asignado)
Datos disponibles: Latitud, longitud, ETA estimado, tiempo hasta recogida y entrega
Límite: Máximo una solicitud cada 30 segundos

Cómo implementar: Vea Flujo de trabajo — Rastrear conductor para ejemplos.

Resolución de disputas (Plataforma Handshake)

Cuando un cliente disputa un pedido después de la entrega, el sistema inicia una negociación entre usted y el cliente:

Recibe HANDSHAKE_DISPUTE con la propuesta del cliente
Puede aceptar, rechazar o hacer una contrapropuesta (reembolso o tiempo adicional)
Tiene hasta expiresAt para responder
Sin respuesta = acción automática (generalmente reembolso)

Importante: Las disputas no respondidas generan contracargos. Siempre responda, incluso para rechazar.

Cómo implementar: Vea Plataforma de Negociación para referencia de API y Guía de Plataforma de Negociación para ejemplos prácticos.

Modificaciones de pedido

¿Cliente elimina/añade artículos después de confirmación? Recibe ORDER_PATCHED con detalles de cambios.Tipos de cambios:

Cantidad/unidad modificada
Artículo removido
Artículo añadido
Artículo reemplazado

Acción necesaria: Actualice su sistema de facturación para reflejar los cambios.Cómo implementar: Vea Flujo de trabajo — Modificaciones parciales para cómo procesar.