Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Eventos de pedido

Compreenda todos os eventos que iFood envia durante o ciclo de vida do pedido. Esta referência mostra estrutura, significado e ações necessárias para cada evento.

Como receber eventos

Escolha um método:Polling (consultando periodicamente):

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

Webhooks (iFood envia para você): Registre um endpoint HTTPS. iFood enviará POST para: https://seu-servidor.com/webhooks/ordersVer guia completo de implementação

Estrutura de um evento

Todos os eventos compartilham esta estrutura base:

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

Campo	Tipo	Descrição
`id`	string	Identificador único do evento
`code`	string	Código curto do evento (ex: `CONFIRMED`)
`fullCode`	string	Código completo (ex: `ORDER_CONFIRMED`)
`orderId`	string	ID do pedido relacionado
`createdAt`	ISO 8601	Timestamp UTC quando o evento foi criado
`metadata`	object	Dados específicos do evento

Nota sobre datas: Todos os timestamps estão em UTC (ISO 8601). Converta para horário local conforme necessário.

Referência rápida — Todos os eventos

Use esta tabela para localizar rapidamente um evento:

Código	Significado	Quando ocorre	Ação necessária
`CONFIRMED`	Pedido confirmado	Novo pedido chega	Processar no POS
`CANCELLED`	Pedido cancelado	Cliente/sistema cancela	Remover da fila
`SEPARATION_STARTED`	Preparação iniciada	Você chamou `/startPreparation`	Nenhuma
`SEPARATION_ENDED`	Preparação concluída	Você chamou `/readyToPickup`	Nenhuma
`READY_TO_PICKUP`	Pronto para retirada	Sistema confirma prontidão	Notificar cliente
`DISPATCHED`	Despachado	Você chamou `/dispatch`	Rastrear entrega
`CONCLUDED`	Concluído	Entrega confirmada/Timeout	Arquivar pedido
`CANCELLATION_REQUESTED`	Cancelamento solicitado	Cliente/você solicitou	Validar motivo
`CANCELLATION_REQUEST_FAILED`	Cancelamento rejeitado	Sistema rejeitou	Tentar novamente
`ASSIGN_DRIVER`	Motorista atribuído	iFood atribuiu entregador	Compartilhar rastreamento
`GOING_TO_ORIGIN`	Indo para origem	Motorista em caminho	Preparar pedido
`ARRIVED_AT_ORIGIN`	Chegou na loja	Motorista na porta	Avisar para finalizar
`COLLECTED`	Coletado	Motorista pegou pedido	Nenhuma
`ARRIVED_AT_DESTINATION`	Chegou no destino	Motorista no local entrega	Nenhuma
`DELIVERY_RETURNING_TO_ORIGIN`	Retornando à loja	Devolução em progresso	Receber pedido
`HANDSHAKE_DISPUTE`	Disputa aberta	Cliente disputa pós-entrega	Responder antes de expirar
`HANDSHAKE_SETTLEMENT`	Disputa resolvida	Sistema resolveu negociação	Arquivar
`ORDER_PATCHED`	Pedido modificado	Cliente adicionou/removeu itens	Atualizar faturamento
`DELIVERY_ADDRESS_CHANGE`	Endereço alterado	Cliente mudou endereço	Atualizar dados
`DELIVERY_PHONE_CHANGE`	Telefone alterado	Cliente mudou telefone	Atualizar contato
`RECOMMENDED_PREPARATION_START`	Preparação recomendada	Sistema calculou melhor hora	Usar se disponível
`PREPARATION_STARTED`	Preparação iniciada	Sistema detectou início	Nenhuma

Status do pedido — Eventos principais

Estes eventos marcam transições de estado no pedido:

CONFIRMED

Código: ORDER_CONFIRMEDNovo pedido chegou na sua fila.

{
  "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": "João Silva",
      "phone": "+55 11 99999-8888"
    },
    "deliveryAddress": {
      "address": "Rua das Flores 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    },
    "createdAt": "2024-04-25T18:00:00Z"
  }
}

Próximas ações:

Processar pedido no seu POS/sistema
Imprimir comanda para cozinha
Chamar /confirm em até 8 minutos Ver como

Prazo crítico: 8 minutos para chamar /confirm, ou pedido é cancelado automaticamente.

SEPARATION_STARTED

Código: PREPARATION_STARTEDVocê iniciou a preparação (chamou /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 ações:

Nenhuma (informativo)
Continue com preparação

SEPARATION_ENDED

Código: PREPARATION_ENDEDVocê marcou como pronto (chamou /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 ações:

Notificar cliente que pedido está pronto
Aguardar retirada (TAKEOUT) ou motorista (DELIVERY)

DISPATCHED

Código: DISPATCHEDPedido foi despachado (entregador saiu com pedido ou cliente retirou).

{
  "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" // ou "IFOOD"
  }
}

Próximas ações:

Se entrega própria: rastrear motorista até destino
Se iFood: esperar evento de entrega confirmada

CONCLUDED

Código: CONCLUDEDPedido foi finalizado (entregue ou retirado com sucesso).

{
  "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 ações:

Arquivar pedido
Nenhuma ação necessária

CANCELLED

Código: ORDER_CANCELLEDPedido foi 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": "Item indisponível"
  }
}

Próximas ações:

Remover pedido da fila
Liberar recursos (itens reservados, etc.)
Reembolsar cliente

Cancelamento — Eventos de controle

CANCELLATION_REQUESTED

Código: CANCELLATION_REQUESTEDVocê ou cliente solicitou cancelamento.

{
  "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": "Item indisponível"
  }
}

Próximas ações:

Aguardar confirmação (CANCELLED) ou rejeição (CANCELLATION_REQUEST_FAILED)

CANCELLATION_REQUEST_FAILED

Código: CANCELLATION_REQUEST_FAILEDSistema rejeitou sua tentativa de cancelamento.

{
  "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 já estava em preparação",
    "attemptedReason": "503"
  }
}

Próximas ações:

Investigar por que cancelamento foi rejeitado
Tentar novamente se for motivo transiente
Contatar suporte se for bloqueio permanente

Entrega — Eventos de rastreamento (iFood)

Estes eventos ocorrem quando iFood está entregando o pedido:

ASSIGN_DRIVER

Código: ASSIGN_DRIVERiFood atribuiu um entregador ao 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 Motorista",
      "phone": "+55 11 91111-2222",
      "vehicle": "Moto"
    },
    "deliveryDistance": 2.5,
    "estimatedDeliveryTime": 900
  }
}

Próximas ações:

Compartilhar dados de rastreamento com cliente
Começar a chamar /tracking a cada 30 segundos se necessário

Ver como rastrear

GOING_TO_ORIGIN

Código: GOING_TO_ORIGINEntregador está indo para sua loja (pickup).

{
  "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 ações:

Preparar pedido para entregador
Ter comanda impressa
Validar documento de identidade do entregador

ARRIVED_AT_ORIGIN

Código: ARRIVED_AT_ORIGINEntregador chegou na sua loja.

{
  "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 ações:

Entregar pedido ao entregador
Pedir que valide código de recogida (se ativado)

Ver validação de pickup

COLLECTED

Código: COLLECTEDEntregador pegou o pedido na sua loja.

{
  "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 ações:

Nenhuma (informativo)

ARRIVED_AT_DESTINATION

Código: ARRIVED_AT_DESTINATIONEntregador chegou na casa do 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 ações:

Nenhuma (cliente receberá de entregador)

DELIVERY_RETURNING_TO_ORIGIN

Código: DELIVERY_RETURNING_TO_ORIGINEntregador está retornando à loja (devolução em progresso).

{
  "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 não estava disponível"
  }
}

Próximas ações:

Preparar para receber pedido de volta
Investigar motivo da devolução

DELIVERY_RETURNED_TO_ORIGIN

Código: DELIVERY_RETURNED_TO_ORIGINPedido foi devolvido à sua loja.

{
  "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 não encontrado"
  }
}

Próximas ações:

Receber e inspecionar pedido
Contactar cliente para entrega de segunda tentativa
Possível disputa de cancelamento

Disputa — Plataforma Handshake

HANDSHAKE_DISPUTE

Código: HANDSHAKE_DISPUTECliente abriu uma disputa (normalmente pós-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 chegou errado",
      "proposalValue": 50.00,
      "expiresAt": "2024-04-26T19:00:00Z",
      "createdAt": "2024-04-25T19:00:00Z"
    }
  }
}

Próximas ações:

Revisar proposta do cliente
Responder antes de expiresAt com /accept, /reject, ou /alternative
Ver guia de plataforma de negociação

Aviso crítico: Sem resposta = reembolso automático. Sempre responda.

HANDSHAKE_SETTLEMENT

Código: HANDSHAKE_SETTLEMENTDisputa foi resolvida (por aceitação, rejeição ou 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 ações:

Arquivar pedido
Contabilizar reembolso se aceito

Endereço e contato — Mudanças

DELIVERY_ADDRESS_CHANGE

Código: DELIVERY_ADDRESS_CHANGECliente mudou o endereço 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": "Rua Nova 456",
      "city": "São Paulo",
      "zipcode": "01500-000",
      "number": "456",
      "complement": "Apto 200"
    },
    "oldAddress": {
      "address": "Rua das Flores 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    }
  }
}

Próximas ações:

Atualizar endereço no seu sistema
Compartilhar novo endereço com entregador

DELIVERY_PHONE_CHANGE

Código: DELIVERY_PHONE_CHANGECliente mudou o telefone de contato para 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 ações:

Atualizar telefone no seu sistema
Compartilhar novo telefone com entregador

Modificações — Mudanças no pedido

ORDER_PATCHED

Código: ORDER_PATCHEDCliente adicionou, removeu ou modificou itens após confirmação.Exemplo 1: Item 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
  }
}

Exemplo 2: Item adicionado

{
  "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": "Sobremesa",
        "quantity": 1,
        "price": 8.00
      }
    ],
    "newTotal": 28.50,
    "oldTotal": 20.50
  }
}

Exemplo 3: Quantidade 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 ações:

Atualizar comanda na cozinha
Atualizar sistema de faturamento
Confirmar leitura via /acknowledgment
Se em preparação: ajustar tempo estimado

Preparação — Eventos informativos

RECOMMENDED_PREPARATION_START

Código: RECOMMENDED_PREPARATION_STARTSistema recomenda hora ideal para começar preparação (para pedidos agendados).

{
  "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 ações:

Use como referência para iniciar preparação (opcional)
Respeite preparationStartDateTime do pedido se for mais restritivo

Ver como usar

PREPARATION_STARTED

Código: PREPARATION_STARTEDSistema detectou que preparação começou (pode ser automático em alguns PDVs).

{
  "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 ações:

Nenhuma (informativo)

Grupos de entrega — Eventos de consolidação

DELIVERY_GROUP_ASSIGNED

Código: DELIVERY_GROUP_ASSIGNEDSeu pedido foi agrupado com outro pedido para entrega conjunta (mesma rota).

{
  "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
  }
}