Eventos de pedido

A API é orientada a eventos. Um pedido pode ter vários eventos associados, como criação, atualização de status ou finalização.

O que são eventos

Eventos representam ações ou mudanças relevantes em um sistema, como a criação ou atualização de um pedido. Na arquitetura orientada a eventos, os sistemas publicam e consomem eventos sem acoplamento direto. Isso aumenta a escalabilidade, a flexibilidade e a resiliência da solução.

Métodos de entrega de eventos

Os métodos de entrega determinam como o iFood envia eventos para as integrações. Cada mecanismo define a forma como os sistemas recebem notificações sobre mudanças, como a criação ou atualização de pedidos.Atualmente, o módulo de eventos de pedidos oferece dois métodos de entrega para integradoras:

Polling

A integração consulta periodicamente a API do iFood para buscar novos eventos.

Más información

Webhook

O iFood envia eventos automaticamente para um endpoint configurado pela integração assim que eles ocorrem.

Más información

Estrutura do evento

Nome	Descrição
`id`	Id único do evento
`code`	Código do evento
`fullCode`	Código completo do evento (nome)
`orderId`	Pedido ao qual esse evento está vinculado
`merchantId`	Id do merchant do pedido
`createdAt`	Data de criação do evento
`salesChannel`	Canal de vendas pelo qual o pedido entra na plataforma (novos canais podem ser adicionados). Possíveis valores: IFOOD, DIGITAL_CATALOG, POS, ECONOMIC, TOTEM, IFOOD_SHOP, IFOOD_APP, IFOOD_SITE, WAITER, PDV, QR_CODE, IFOOD_SHOP_APP, IFOOD_SHOP_SITE, GROCERY_WHITELABEL_SITE
metadata	informações adicionais do evento

Exemplo

{
  "id": "b03392c5-61dd-47c4-a503-bce3109c96c8",
  "code": "CFM",
  "fullCode": "CONFIRMED",
  "orderId": "93ba4bf4-f4ae-4de8-8017-35d7c7de9bf1",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-17T19:36:55.295Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "CLIENT_ID": "3c587f8f-fb22-46a7-88f8-781246a3ea3f"
  }
}

Grupos de eventos

Os eventos de um pedido podem ser classificados por grupo:

Grupo	Descrição
`ORDER_STATUS`	Eventos que representam uma mudança no status do pedido
`CANCELLATION_REQUEST`	Eventos relacionados ao cancelamento de um pedido
`ORDER_TAKEOUT`	Eventos relacionados à retirada de pedidos
`DELIVERY`	Eventos relacionados à entrega de um pedido
`DELIVERY_ADDRESS`	Eventos relacionados à mudanças no endereço de entrega de um pedido
`DELIVERY_GROUP`	Eventos relacionados a agrupamento de entrega de pedidos
`DELIVERY_ONDEMAND`	Eventos relacionados à solicitação do serviço de entrega iFood sob demanda (modelo híbrido ou marketplace)
`DELIVERY_COMPLEMENT`	Eventos relacionados à entrega complementar (quando o pedido entregue está incompleto)
`ORDER_MODIFIER`	Eventos relacionados à edição de pedidos
`ORDER_HANDSHAKE`	Eventos relacionados à plataforma de negociação

Alguns eventos são opcionais. Você não precisa implementá-los no seu aplicativo. Mesmo ao ignorar esses eventos, envie o acknowledgment para evitar que eles sejam reenviados em futuras requisições de polling.

Eventos por Grupo

ORDER_STATUS

Nome	Código	Descrição
`PLACED`	PLC	Novo pedido na plataforma
`CONFIRMED`	CFM	Pedido foi confirmado e será preparado
`SEPARATION_STARTED`	SPS	Indica o início do processo de separação dos itens do pedido (Exclusivo para pedidos de Mercado)
`SEPARATION_ENDED`	SPE	Indica a conclusão da sepração dos itens do pedido (Exclusivo para pedidos de Mercado)
`READY_TO_PICKUP`	RTP	Indica que o pedido está pronto para ser retirado (pelo cliente ou pelo entregador)
`DISPATCHED`	DSP	Indica que o pedido saiu para entrega (Delivery)
`CONCLUDED`	CON	Pedido foi concluído
`CANCELLED`	CAN	Pedido foi cancelado

O iFood gera o evento CONCLUDED automaticamente. O tempo de geração pode variar entre o momento da entrega e até duas horas depois.

Exemplos

{
  "id": "58c3f8fc-fb2a-49a3-b99c-09ecf2cd590d",
  "code": "PLC",
  "fullCode": "PLACED",
  "orderId": "8ee1ba27-b3be-4164-8f5c-285236a20ecc",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-17T15:07:20.04Z",
  "salesChannel": "IFOOD"
}

CANCELLATION_REQUEST

Nome	Código	Descrição
`CANCELLATION_REQUESTED`	CAR	Solicitação de cancelamento feita pelo Merchant (loja) ou pelo iFood de maneira automática (pedidos não confirmados dentro do prazo) ou de maneira manual através do nosso time de atendimento
`CANCELLATION_REQUEST_FAILED`	CARF	Solicitação de cancelamento negada
`CONSUMER_CANCELLATION_REQUESTED`	CCR	Solicitação de cancelamento feita pelo cliente
`CONSUMER_CANCELLATION_ACCEPTED`	CCA	A solicitação de cancelamento feita pelo cliente foi aprovada pelo Merchant (loja)
`CONSUMER_CANCELLATION_DENIED`	CCD	A solicitação de cancelamento feita pelo cliente foi negada pelo Merchant (loja)

Sempre que uma solicitação de cancelamento é aprovada, também é gerado um evento de CANCELLED (CAN).

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "CAR",
  "fullCode": "CANCELLATION_REQUESTED",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "reason_code": "504",
    "details": "MANUAL(RESTAURANT_WITHOUT_DELIVERY_MAN) - Restaurante sem entregador",
    "ORIGIN": "ORDER_MANAGER",
    "CLIENT_ID": "iconnect_v3_homologation"
  }
}

HANDSHAKE_PLATFORM

Nome	Código	Descrição
`HANDSHAKE_DISPUTE`	HSD	O evento indica que uma negociação foi iniciada e que obrigatoriamente deve ser respondida
`HANDSHAKE_SETTLEMENT`	HSS	O evento sinaliza e formaliza que uma negociação foi respondida

Exemplos

{
  "id": "6d34f8be-7fa6-40f1-877f-8ac564db2a7c",
  "orderId": "23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "code": "HSD",
  "fullcode": "HANDSHAKE_DISPUTE",
  "merchantId": "23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "createdAt": "2023-06-23T13:09:06.287636Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "disputeId": "5166ded9-bdee-4440-8c73-b5488e8b1f83",
    "action": "CANCELLATION",
    "timeoutAction": "REJECT_CANCELLATION",
    "handshakeType": "AFTER_DELIVERY",
    "handshakeGroup": "CUSTOMER_ORDER_SUPPORT",
    "message": "Pedido veio errado",
    "expiresAt": "2023-06-23T13:15:06.287636Z",
    "alternatives": [
      {
        "id": "2d35d0b9-67ae-46d2-8261-f0a40e5d07fd",
        "type": "REFUND",
        "metadata": {
          "maxAmount": {
            "value": "6000",
            "currency": "BRL"
          }
        }
      }
    ],
    "metadata": {
      "evidences": [
        {
          "url": "https://merchant-api.ifood.com.br/notification/v1.0/orders/{orderId}/assets/{imageId}",
          "contentType": "image/jpg"
        }
      ],
      "items": [
        {
          "id": "296b1757-4edf-4a4a-9f03-dfc10d4e907a",
          "uniqueId": "fe3620ad-c475-4f01-93b9-1ed95907a9ab",
          "integrationId": "73",
          "index": 1,
          "quantity": 1,
          "amount": {
            "value": "3890",
            "currency": "BRL"
          },
          "reason": "Não veio a batata, apenas as esfihas"
        }
      ],
      "garnishItems": [
        {
          "id": "ffa2e2f0-361e-4076-8781-e7c8073326e1",
          "parentUniqueId": "efe73d06-ccfd-4605-a2a5-1b5b64284b47",
          "integrationId": "MAI-9601273-601273",
          "quantity": 1,
          "index": 2,
          "amount": {
            "value": "2650",
            "currency": "BRL"
          },
          "reason": "Revirado e faltando o queijo"
        }
      ]
    },
    "createdAt": "2023-06-23T13:06:50.448434Z"
  },
  "receivedAt": "2023-06-23T13:06:50.628451Z"
}

DELIVERY

Nome	Código	Descrição
`ASSIGN_DRIVER`	ADR	Um entregador foi alocado para realizar a entrega
`GOING_TO_ORIGIN`	GTO	Entregador está a caminho da origem para retirar o pedido
`ARRIVED_AT_ORIGIN`	AAO	Entregador chegou na origem para retirar o pedido
`DELIVERY_DRIVER_DEALLOCATED`	DDD	Entregador foi desalocado da rota de entrega
`COLLECTED`	CLT	Entregador coletou o pedido
`ARRIVED_AT_DESTINATION`	AAD	Entregador chegou no endereço de destino
`DELIVERY_RETURNING_TO_ORIGIN`	DRGO	Entregador está retornando ao local de origem(coleta) do pedido
`DELIVERY_RETURNED_TO_ORIGIN`	DRDO	Entregador já retornou ao local de origem(coleta) do pedido
`DELIVERY_CANCELLATION_REQUESTED`	DCR	Solicitação de cancelamento de entregador
`DELIVERY_DROP_CODE_REQUESTED`	DDCR	Informa o código de confirmação de entrega do pedido
`DELIVERY_DROP_CODE_VALIDATION_SUCCESS`	DDCS	O código de confirmação de entrega foi validado com sucesso
`DELIVERY_RETURN_CODE_REQUESTED`	DRCR	Informa a decisão e o código de confirmação da devolução
`DELIVERY_PICKUP_CODE_REQUESTED`	DPCR	Informa o código de confirmação de coleta do pedido
`DELIVERY_PICKUP_CODE_VALIDATION_SUCCESS`	DPCS	O código de confirmação de coleta foi validado com sucesso

Pedidos de entrega parceira

Pedidos de entrega parceira (deliveryBy: "IFOOD") podem ter múltiplas entregas. Isso ocorre, por exemplo, se faltar um item do pedido e for necessária uma segunda entrega, ou quando um pedido grande é dividido entre vários entregadores.Os eventos trazem três campos no metadata para identificar o tipo de entrega:

deliveryId: identifica cada entrega de forma única e permite rastrear todas as etapas, mesmo em pedidos com múltiplas entregas ou eventos logísticos repetidos.
deliveryType: indica se a entrega é MAIN (principal) ou COMPLEMENT (complementar).
deliveryComplementType: detalha o tipo de entrega complementar — HUGE_ORDER para pedidos grandes divididos entre entregas ou MISSING_ITEM para itens faltantes. Entregas complementares são exclusivas de pedidos feitos pelo iFood.

Em pedidos Sob Demanda (salesChannel: "POS"), os eventos DELIVERY_DROP_CODE incluem o campo `code` no metadata. Em pedidos Full-Service (salesChannel: "IFOOD"), esses eventos não incluem o campo `code`.

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "ADR",
  "fullCode": "ASSIGN_DRIVER",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "deliveryId": "b0954b6b-f99c-44b6-ba1e-987f32b2b22a",
    "deliveryType": "MAIN",
    "workerVehicleType": "CAR",
    "workerName": "Fulano da Silva",
    "workerExternalUuid": "99d1d32e-7001-4b94-b969-17366d40159b",
    "workerPhotoUrl": "https://nv-production-logistics-driver-account.s3.amazonaws.com/static/drivers/photo/99d1d32e-7001-4b94-b969-17366d401999.jpg"
  }
}

DELIVERY_ADDRESS

Os eventos de DELIVERY_ADDRESS são exclusivos para pedidos do Sob Demanda (salesChannel:"POS").

Nome	Código	Descrição
`DELIVERY_ADDRESS_CHANGE_REQUESTED`	DAR	Cliente solicitou alteração do endereço de entrega do pedido
`DELIVERY_ADDRESS_CHANGE_USER_CONFIRMED`	DAU	Cliente confirmou o endereço de entrega
`DELIVERY_ADDRESS_CHANGE_ACCEPTED`	DAA	A alteração do endereço de entrega foi aprovada pelo parceiro
`DELIVERY_ADDRESS_CHANGE_DENIED`	DAD	A alteração do endereço de entrega foi negada pelo parceiro

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "DAR",
  "fullCode": "DELIVERY_ADDRESS_CHANGE_REQUESTED",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "address": {
      "streetName": "Rua de teste",
      "streetNumber": "1",
      "complement": "Teste",
      "reference": "Teste",
      "neighborhood": "Centro",
      "city": "Bairro de Teste",
      "state": "AC",
      "country": "BR",
      "coordinates": {
        "latitude": -9.11,
        "longitude": -67.22
      }
    }
  }
}

DELIVERY_GROUP

Quando ocorre o agrupamento de pedidos para entrega, o evento DELIVERY_GROUP_ASSIGNED é gerado. O metadata do evento traz a lista completa de orderIds agrupados. Para evitar duplicidade, o evento é enviado apenas para o primeiro pedido da lista. Para consultar informações de outro pedido do grupo, use o evento do pedido principal.

Nome	Código	Descrição
DELIVERY_GROUP_ASSIGNED	DGA	Indica que 2 ou mais pedidos foram agrupados em uma mesma rota de entrega
DELIVERY_GROUP_DISMISSED	DGD	Indica que a rota de entrega de pedidos agrupadas foi destituída

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "DGA",
  "fullCode": "DELIVERY_GROUP_ASSIGNED",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "deliveryGroupId": "4d063d88-32f6-4b89-b68b-48890b098c71",
    "orderIds": ["dd2796df-1c09-446b-a3b4-81f28849c459", "dd2796df-1c09-446b-a3b4-81f28849c888"]
  }
}

DELIVERY_ONDEMAND

Nome	Código	Descrição
`REQUEST_DRIVER`	RDR	Indica que foi feita uma requisição do serviço de entrega sob demanda
`REQUEST_DRIVER_SUCCESS`	RDS	Requisição de entrega aprovada
`REQUEST_DRIVER_FAILED`	RDF	Requisição de entrega negada Valores possíveis: SAFE_MODE_ON, OFF_WORKING_SHIFT_POST, CLOSED_REGION, SATURATED_REGION
`DELIVERY_CANCELLATION_REQUEST_ACCEPTED`	DCRA	A solicitação de cancelamento de entregador foi realizada com sucesso
`DELIVERY_CANCELLATION_REQUEST_REJECTED`	DCRR	A solicitação de cancelamento de entregador não foi realizada

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "RDR",
  "fullCode": "REQUEST_DRIVER",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "ORIGIN": "ORDER_MANAGER",
    "CLIENT_ID": "iconnect_v3_homologation"
  }
}

DELIVERY_COMPLEMENT

Nome	Código	Descrição
`RETURN_TO_STORE`	RTS	Solicitação de retorno para buscar itens do pedido que faltaram (complementar o pedido entregue incompleto)

Exemplo

{
  "id": "05dec672-5fd7-46ce-bdd2-fda515d33eb8",
  "code": "RTS",
  "fullCode": "RETURN_TO_STORE",
  "orderId": "96eebd06-50a5-4e87-908d-d93bbb1ef17b",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-23T15:28:13.084Z",
  "salesChannel": "IFOOD"
}

ORDER_MODIFIER

Nome	Código	Descrição
`PATCH_REQUESTED`	PRQ	Requisição de alteração de um pedido
`PATCH_REQUEST_CANCELLED`	PRQC	Requisição de alteração de pedido cancelada
`PATCH_COMMITTED`	PCO	Pedido alterado
`PATCH_COMMITTED_FAILED`	PCOF	Falha na alteração do pedido

Exemplos

{
  "id": "59835381-33cf-48e3-a697-bfaff0c7a9b4",
  "code": "PRQ",
  "fullCode": "PATCH_REQUESTED",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c999",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-26T14:31:38.391Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "patchRequestId": "48f89d40-e48c-4f7d-890a-ae84861b712f",
    "agent": "MERCHANT",
    "changeLevel": "PATCH_ITEMS",
    "customerId": "2834daad-9c2b-4e14-a9b1-c52bc143fb99",
    "storeName": "Nome da Loja",
    "notificationType": "APPROVAL",
    "approvalTimeout": "2021-02-26T14:42:38.315284Z"
  }
}

OUTROS

Não é possível filtrar eventos do grupo OUTROS.

Nome	Código	Descrição
`ORDER_PATCHED`	OPA	Indica que houve uma alteração no pedido
`RECOMMENDED_PREPARATION_START`	RPS	Recomendação de início do preparo do pedido para otimizar a retirada e entrega. Gerado somente para pedidos com entrega iFood e quando nossos algoritmos identificam uma oportunidade de otimizar o início de preparo.
`PREPARATION_STARTED`	PRS	Pedido começou a ser preparado
`CONSUMER_PREPARATION_TIME_REQUESTED`	CPR	Cliente solicita informações sobre o tempo de preparo do pedido
`CHANGE_PREPARATION_TIME`	CPT	Informa ao cliente que houve uma mudança no tempo de preparo do pedido
`BOX_ASSIGNED`	BOA	Pedido elegível para ser deixado no iFood Box

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "OPA",
  "fullCode": "ORDER_PATCHED",
  "createdAt": "2021-02-23T11:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "changes": [
      {
        "changeType": "EDIT_ITEMS",
        "items": [
          {
            "id": "3dc09021-be6b-4be6-92a1-15a07b464141",
            "uniqueId": "3dc09021-be6b-4be6-92a1-15a07b464141",
            "externalCode": "123",
            "changes": {
              "optionsChanges": [
                {
                  "changeType": "ADD_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f99999",
                      "externalCode": "1234567",
                      "quantity": 1,
                      "unitPrice": 2
                    }
                  ]
                },
                {
                  "changeType": "EDIT_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f98799",
                      "quantity": {
                        "from": 2,
                        "to": 1
                      },
                      "unitPrice": 7
                    }
                  ]
                },
                {
                  "changeType": "DELETE_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f98789"
                    }
                  ]
                }
              ],
              "quantity": {
                "from": "1",
                "to": "800"
              },
              "unit": {
                "from": "KG",
                "to": "g"
              }
            },
            "unitPrice": 20,
            "optionsPrice": {
              "from": 8.5,
              "to": 2
            },
            "totalPrice": {
              "from": 28.5,
              "to": 22
            }
          }
        ]
      }
    ],
    "total": {
      "subtotal": {
        "from": 28.5,
        "to": 22
      }
    },
    "payments": {
      "methods": [
        {
          "value": 22,
          "currency": "BRL",
          "type": "ONLINE",
          "method": "CREDIT / DEBIT / MEAL_VOUCHER / FOOD_VOUCHER",
          "card": {
            "brand": "Nome da Bandeira"
          }
        }
      ]
    }
  }
}

Veja também

Recepção de pedidosFluxo de recepção e confirmação pedidos

Más información

Detalhes de pedidosEstrutura e exemplos de pedidos

Más información