Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Eventos de pedido

Comprenda todos los eventos que iFood envía durante el ciclo de vida del pedido. Esta referencia muestra estructura, significado y acciones requeridas para cada evento.

Cómo recibir eventos

Elija un método:Polling (consultando periódicamente):

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders:polling" \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhooks (iFood envía a usted): Registre un endpoint HTTPS. iFood enviará POST a: https://su-servidor.com/webhooks/ordersVer guía completa de implementación

Estructura de un evento

Todos los eventos comparten esta estructura base:

{
  "id": "evt_abc123",
  "code": "CONFIRMED",
  "fullCode": "ORDER_CONFIRMED",
  "orderId": "ord_789",
  "createdAt": "2024-04-25T18:00:00Z",
  "metadata": {
    // Contenido específico del evento
  }
}

Campo	Tipo	Descripción
`id`	string	Identificador único del evento
`code`	string	Código corto del evento (ej: `CONFIRMED`)
`fullCode`	string	Código completo (ej: `ORDER_CONFIRMED`)
`orderId`	string	ID del pedido relacionado
`createdAt`	ISO 8601	Timestamp UTC cuando se creó el evento
`metadata`	object	Datos específicos del evento

Nota sobre fechas: Todos los timestamps están en UTC (ISO 8601). Convierta a hora local según sea necesario.

Referencia rápida — Todos los eventos

Use esta tabla para ubicar rápidamente un evento:

Código	Significado	Cuándo ocurre	Acción necesaria
`CONFIRMED`	Pedido confirmado	Nuevo pedido llega	Procesar en POS
`CANCELLED`	Pedido cancelado	Cliente/sistema cancela	Remover de cola
`SEPARATION_STARTED`	Preparación iniciada	Llamó `/startPreparation`	Ninguna
`SEPARATION_ENDED`	Preparación finalizada	Llamó `/readyToPickup`	Ninguna
`READY_TO_PICKUP`	Listo para retirada	Sistema confirma disponibilidad	Notificar cliente
`DISPATCHED`	Despachado	Llamó `/dispatch`	Rastrear entrega
`CONCLUDED`	Concluido	Entrega confirmada/Timeout	Archivar pedido
`CANCELLATION_REQUESTED`	Cancelamiento solicitado	Cliente/usted solicitó	Validar motivo
`CANCELLATION_REQUEST_FAILED`	Cancelamiento rechazado	Sistema rechazó	Reintentar
`ASSIGN_DRIVER`	Conductor asignado	iFood asignó entregador	Compartir rastreo
`GOING_TO_ORIGIN`	Yendo al origen	Conductor en camino	Preparar pedido
`ARRIVED_AT_ORIGIN`	Llegó a tienda	Conductor en puerta	Finalizar
`COLLECTED`	Recogido	Conductor recogió pedido	Ninguna
`ARRIVED_AT_DESTINATION`	Llegó a destino	Conductor en ubicación entrega	Ninguna
`DELIVERY_RETURNING_TO_ORIGIN`	Retornando a tienda	Devolución en progreso	Recibir pedido
`HANDSHAKE_DISPUTE`	Disputa abierta	Cliente disputa post-entrega	Responder antes expiración
`HANDSHAKE_SETTLEMENT`	Disputa resuelta	Sistema resolvió negociación	Archivar
`ORDER_PATCHED`	Pedido modificado	Cliente agregó/removió artículos	Actualizar facturación
`DELIVERY_ADDRESS_CHANGE`	Dirección alterada	Cliente cambió dirección	Actualizar datos
`DELIVERY_PHONE_CHANGE`	Teléfono alterado	Cliente cambió teléfono	Actualizar contacto
`RECOMMENDED_PREPARATION_START`	Preparación recomendada	Sistema calculó mejor hora	Usar si disponible
`PREPARATION_STARTED`	Preparación iniciada	Sistema detectó inicio	Ninguna

Estado del pedido — Eventos principales

Estos eventos marcan transiciones de estado en el pedido:

CONFIRMED

Código: ORDER_CONFIRMEDNuevo pedido llegó en su cola.

{
  "id": "evt_123",
  "code": "CONFIRMED",
  "fullCode": "ORDER_CONFIRMED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:00:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "CONFIRMED",
    "category": "FOOD",
    "orderType": "DELIVERY",
    "items": [
      {
        "id": "item_789",
        "name": "Hamburguesa",
        "quantity": 1,
        "price": 25.50
      }
    ],
    "customer": {
      "id": "cust_123",
      "name": "Juan Silva",
      "phone": "+55 11 99999-8888"
    },
    "deliveryAddress": {
      "address": "Calle Flores 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    },
    "createdAt": "2024-04-25T18:00:00Z"
  }
}

Próximas acciones:

Procesar pedido en su POS/sistema
Imprimir comprobante para cocina
Llamar /confirm dentro de 8 minutos Ver cómo

Plazo crítico: 8 minutos para llamar /confirm, o pedido se cancela automáticamente.

SEPARATION_STARTED

Código: PREPARATION_STARTEDIniciaste la preparación (llamaste /startPreparation).

{
  "id": "evt_124",
  "code": "SEPARATION_STARTED",
  "fullCode": "PREPARATION_STARTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "PREPARING",
    "startedAt": "2024-04-25T18:05:00Z"
  }
}

Próximas acciones:

Ninguna (informativo)
Continúa con preparación

SEPARATION_ENDED

Código: PREPARATION_ENDEDMarcaste como listo (llamaste /readyToPickup).

{
  "id": "evt_125",
  "code": "SEPARATION_ENDED",
  "fullCode": "PREPARATION_ENDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:15:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "READY_TO_PICKUP",
    "readyAt": "2024-04-25T18:15:00Z"
  }
}

Próximas acciones:

Notificar cliente que pedido está listo
Esperar recogida (TAKEOUT) o conductor (DELIVERY)

DISPATCHED

Código: DISPATCHEDPedido fue despachado (conductor salió con pedido o cliente retiró).

{
  "id": "evt_126",
  "code": "DISPATCHED",
  "fullCode": "DISPATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "DISPATCHED",
    "dispatchedAt": "2024-04-25T18:20:00Z",
    "deliveredBy": "MERCHANT" // o "IFOOD"
  }
}

Próximas acciones:

Si entrega propia: rastrear conductor a destino
Si iFood: esperar evento de confirmación entrega

CONCLUDED

Código: CONCLUDEDPedido fue finalizado (entregado o recogido exitosamente).

{
  "id": "evt_127",
  "code": "CONCLUDED",
  "fullCode": "CONCLUDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:45:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "CONCLUDED",
    "concludedAt": "2024-04-25T18:45:00Z",
    "totalPrice": 25.50,
    "totalValue": 25.50
  }
}

Próximas acciones:

Archivar pedido
Sin acciones adicionales

CANCELLED

Código: ORDER_CANCELLEDPedido fue cancelado.

{
  "id": "evt_128",
  "code": "CANCELLED",
  "fullCode": "ORDER_CANCELLED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:50:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "CANCELLED",
    "cancelledAt": "2024-04-25T18:50:00Z",
    "cancelReason": "503",
    "cancelReasonDescription": "Artículo no disponible"
  }
}

Próximas acciones:

Remover pedido de cola
Liberar recursos (artículos reservados, etc.)
Reembolsar cliente

Cancelamiento — Eventos de control

CANCELLATION_REQUESTED

Código: CANCELLATION_REQUESTEDUsted o cliente solicitó cancelamiento.

{
  "id": "evt_129",
  "code": "CANCELLATION_REQUESTED",
  "fullCode": "CANCELLATION_REQUESTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "ord_456",
    "reason": "503",
    "reasonDescription": "Artículo no disponible"
  }
}

Próximas acciones:

Esperar confirmación (CANCELLED) o rechazo (CANCELLATION_REQUEST_FAILED)

CANCELLATION_REQUEST_FAILED

Código: CANCELLATION_REQUEST_FAILEDSistema rechazó su intento de cancelamiento.

{
  "id": "evt_130",
  "code": "CANCELLATION_REQUEST_FAILED",
  "fullCode": "CANCELLATION_REQUEST_FAILED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:30Z",
  "metadata": {
    "id": "ord_456",
    "reason": "Pedido ya estaba en preparación",
    "attemptedReason": "503"
  }
}

Próximas acciones:

Investigar por qué cancelamiento fue rechazado
Reintentar si es motivo transitorio
Contactar soporte si es bloqueo permanente

Entrega — Eventos de rastreo (iFood)

Estos eventos ocurren cuando iFood está entregando el pedido:

ASSIGN_DRIVER

Código: ASSIGN_DRIVERiFood asignó un conductor al pedido.

{
  "id": "evt_131",
  "code": "ASSIGN_DRIVER",
  "fullCode": "ASSIGN_DRIVER",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123",
      "name": "Carlos Conductor",
      "phone": "+55 11 91111-2222",
      "vehicle": "Motocicleta"
    },
    "deliveryDistance": 2.5,
    "estimatedDeliveryTime": 900
  }
}

Próximas acciones:

Compartir datos de rastreo con cliente
Comenzar a llamar /tracking cada 30 segundos si es necesario

Ver cómo rastrear

GOING_TO_ORIGIN

Código: GOING_TO_ORIGINConductor va a su tienda (recogida).

{
  "id": "evt_132",
  "code": "GOING_TO_ORIGIN",
  "fullCode": "GOING_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:30Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "estimatedArrivalTime": 300
  }
}

Próximas acciones:

Preparar pedido para conductor
Tener comprobante impreso
Validar identificación del conductor

ARRIVED_AT_ORIGIN

Código: ARRIVED_AT_ORIGINConductor llegó a su tienda.

{
  "id": "evt_133",
  "code": "ARRIVED_AT_ORIGIN",
  "fullCode": "ARRIVED_AT_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:25:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "arrivedAt": "2024-04-25T18:25:00Z"
  }
}

Próximas acciones:

Entregar pedido al conductor
Pedir que valide código de recogida (si está habilitado)

Ver validación de recogida

COLLECTED

Código: COLLECTEDConductor recogió el pedido en su tienda.

{
  "id": "evt_134",
  "code": "COLLECTED",
  "fullCode": "COLLECTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:25:30Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "collectedAt": "2024-04-25T18:25:30Z"
  }
}

Próximas acciones:

Ninguna (informativo)

ARRIVED_AT_DESTINATION

Código: ARRIVED_AT_DESTINATIONConductor llegó a la dirección del cliente.

{
  "id": "evt_135",
  "code": "ARRIVED_AT_DESTINATION",
  "fullCode": "ARRIVED_AT_DESTINATION",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:40:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "arrivedAt": "2024-04-25T18:40:00Z"
  }
}

Próximas acciones:

Ninguna (cliente recibirá del conductor)

DELIVERY_RETURNING_TO_ORIGIN

Código: DELIVERY_RETURNING_TO_ORIGINConductor está retornando a tienda (devolución en progreso).

{
  "id": "evt_136",
  "code": "DELIVERY_RETURNING_TO_ORIGIN",
  "fullCode": "DELIVERY_RETURNING_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:45:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "returningReason": "Cliente no disponible"
  }
}

Próximas acciones:

Preparar para recibir pedido devuelto
Investigar motivo de devolución

DELIVERY_RETURNED_TO_ORIGIN

Código: DELIVERY_RETURNED_TO_ORIGINPedido fue devuelto a su tienda.

{
  "id": "evt_137",
  "code": "DELIVERY_RETURNED_TO_ORIGIN",
  "fullCode": "DELIVERY_RETURNED_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:50:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "returnedAt": "2024-04-25T18:50:00Z",
    "reason": "Cliente no encontrado"
  }
}

Próximas acciones:

Recibir e inspeccionar pedido
Contactar cliente para segundo intento entrega
Posible disputa de cancelamiento

Disputa — Plataforma Handshake

HANDSHAKE_DISPUTE

Código: HANDSHAKE_DISPUTECliente abrió una disputa (típicamente post-entrega).

{
  "id": "evt_138",
  "code": "HANDSHAKE_DISPUTE",
  "fullCode": "HANDSHAKE_DISPUTE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T19:00:00Z",
  "metadata": {
    "disputable": true,
    "dispute": {
      "id": "dispute_123",
      "orderId": "ord_456",
      "status": "OPEN",
      "reason": "Pedido llegó equivocado",
      "proposalValue": 50.00,
      "expiresAt": "2024-04-26T19:00:00Z",
      "createdAt": "2024-04-25T19:00:00Z"
    }
  }
}

Próximas acciones:

Revisar propuesta del cliente
Responder antes de expiresAt con /accept, /reject, o /alternative
Ver guía plataforma negociación

Advertencia crítica: Sin respuesta = reembolso automático. Siempre responda.

HANDSHAKE_SETTLEMENT

Código: HANDSHAKE_SETTLEMENTDisputa fue resuelta (por aceptación, rechazo o timeout).

{
  "id": "evt_139",
  "code": "HANDSHAKE_SETTLEMENT",
  "fullCode": "HANDSHAKE_SETTLEMENT",
  "orderId": "ord_456",
  "createdAt": "2024-04-26T19:05:00Z",
  "metadata": {
    "dispute": {
      "id": "dispute_123",
      "status": "SETTLED",
      "resolution": "MERCHANT_ACCEPTED",
      "settledAt": "2024-04-26T19:05:00Z"
    }
  }
}

Próximas acciones:

Archivar pedido
Registrar reembolso si fue aceptado

Dirección y contacto — Cambios

DELIVERY_ADDRESS_CHANGE

Código: DELIVERY_ADDRESS_CHANGECliente cambió dirección de entrega.

{
  "id": "evt_140",
  "code": "DELIVERY_ADDRESS_CHANGE",
  "fullCode": "DELIVERY_ADDRESS_CHANGE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:10:00Z",
  "metadata": {
    "id": "ord_456",
    "newAddress": {
      "address": "Calle Nueva 456",
      "city": "São Paulo",
      "zipcode": "01500-000",
      "number": "456",
      "complement": "Apt 200"
    },
    "oldAddress": {
      "address": "Calle Flores 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    }
  }
}

Próximas acciones:

Actualizar dirección en su sistema
Compartir nueva dirección con conductor

DELIVERY_PHONE_CHANGE

Código: DELIVERY_PHONE_CHANGECliente cambió teléfono de contacto entrega.

{
  "id": "evt_141",
  "code": "DELIVERY_PHONE_CHANGE",
  "fullCode": "DELIVERY_PHONE_CHANGE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:10:00Z",
  "metadata": {
    "id": "ord_456",
    "newPhone": "+55 11 98888-7777",
    "oldPhone": "+55 11 99999-8888"
  }
}

Próximas acciones:

Actualizar teléfono en su sistema
Compartir nuevo teléfono con conductor

Modificaciones — Cambios en pedido

ORDER_PATCHED

Código: ORDER_PATCHEDCliente agregó, removió o modificó artículos después de confirmación.Ejemplo 1: Artículo removido

{
  "id": "evt_142",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:08:00Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "DELETE_ITEMS",
    "items": [
      {
        "id": "item_789",
        "name": "Bebida",
        "quantity": 1,
        "price": 5.00
      }
    ],
    "newTotal": 20.50,
    "oldTotal": 25.50
  }
}

Ejemplo 2: Artículo agregado

{
  "id": "evt_143",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:08:30Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "ADD_ITEMS",
    "items": [
      {
        "id": "item_999",
        "name": "Postre",
        "quantity": 1,
        "price": 8.00
      }
    ],
    "newTotal": 28.50,
    "oldTotal": 20.50
  }
}

Ejemplo 3: Cantidad modificada

{
  "id": "evt_144",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:09:00Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "UPDATE_ITEMS",
    "items": [
      {
        "id": "item_789",
        "name": "Hamburguesa",
        "oldQuantity": 1,
        "newQuantity": 2,
        "price": 25.50
      }
    ],
    "newTotal": 51.00,
    "oldTotal": 25.50
  }
}

Próximas acciones:

Actualizar comprobante en cocina
Actualizar sistema facturación
Confirmar lectura vía /acknowledgment
Si en preparación: ajustar tiempo estimado

Preparación — Eventos informativos

RECOMMENDED_PREPARATION_START

Código: RECOMMENDED_PREPARATION_STARTSistema recomienda hora ideal para iniciar preparación (para pedidos programados).

{
  "id": "evt_145",
  "code": "RECOMMENDED_PREPARATION_START",
  "fullCode": "RECOMMENDED_PREPARATION_START",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:00:00Z",
  "metadata": {
    "id": "ord_456",
    "recommendedStartTime": "2024-04-25T18:15:00Z",
    "scheduledDeliveryTime": "2024-04-25T18:45:00Z"
  }
}

Próximas acciones:

Use como referencia para iniciar preparación (opcional)
Respete preparationStartDateTime del pedido si es más restrictivo

Ver cómo usar

PREPARATION_STARTED

Código: PREPARATION_STARTEDSistema detectó que preparación comenzó (puede ser automático en algunos POS).

{
  "id": "evt_146",
  "code": "PREPARATION_STARTED",
  "fullCode": "PREPARATION_STARTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:15:00Z",
  "metadata": {
    "id": "ord_456",
    "startedAt": "2024-04-25T18:15:00Z"
  }
}

Próximas acciones:

Ninguna (informativo)

Grupos de entrega — Eventos consolidación

DELIVERY_GROUP_ASSIGNED

Código: DELIVERY_GROUP_ASSIGNEDSu pedido fue agrupado con otro pedido para entrega conjunta (misma ruta).

{
  "id": "evt_147",
  "code": "DELIVERY_GROUP_ASSIGNED",
  "fullCode": "DELIVERY_GROUP_ASSIGNED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "deliveryGroupId": "group_789",
    "groupedOrders": ["ord_456", "ord_457", "ord_458"],
    "estimatedDeliveryTime": 1200
  }
}