Catálogo de eventos

Os seis eventos do padrão e as extensões MeuPedido, quando cada um dispara, e o que vem em metadata e delivery.

Um evento é o aviso de que algo aconteceu com um pedido. Ele chega pelo polling ou por webhook, sempre no mesmo envelope, e nunca traz o pedido: o conteúdo está em orderURL.

O envelope

{
  "eventId": "e1b9c0d2-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "eventType": "CANCELLED",
  "orderId": "3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d",
  "orderURL": "https://api.meupedido.io/open-delivery/v1/orders/3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d",
  "createdAt": "2026-09-19T14:03:40Z",
  "metadata": {
    "reason": "Cliente desistiu do pedido.",
    "code": "CONSUMER_CANCELLATION_REQUESTED"
  }
}

Campo	Tipo	Presença	Descrição
`eventId`	GUID	sempre	Identificador único do evento. É o que você confirma e a sua chave de deduplicação.
`eventType`	string	sempre	Um dos tipos da tabela abaixo.
`orderId`	GUID	sempre	O pedido a que o evento se refere.
`orderURL`	string	sempre	URL absoluta de `GET /v1/orders/{orderId}`.
`createdAt`	data	sempre	Instante em que o evento foi gerado, ISO 8601 em UTC com `Z`.
`sourceAppId`	string	quando existe	Identificador da aplicação de origem, quando o pedido veio por um canal integrado.
`metadata`	objeto	por tipo	`CANCELLED` traz `reason` e `code`. `CONFIRMED` traz um objeto vazio `{}`. Os demais não trazem o campo.
`delivery`	objeto	só `COURIER_*`	Dados da rota e do entregador. Veja O bloco delivery.

Campos opcionais são omitidos quando não têm valor, e não enviados como null. Desserialize com tolerância a campos ausentes e a campos novos.

Tipos de evento

Evento	Quando dispara	Origem	Extras
`CREATED`	O pedido entrou em `PENDING`: foi criado, ou o PIX foi confirmado.	Open Delivery
`CONFIRMED`	A loja aceitou (`ACCEPTED`).	Open Delivery	`metadata: {}`
`PREPARING`	A cozinha começou (`PREPARING`).	Extensão MeuPedido
`READY_FOR_PICKUP`	O pedido está pronto (`READY`). Em `TAKEOUT` e `INDOOR`, também quando entra em `DELIVERY`.	Open Delivery
`DISPATCHED`	Saiu para entrega (`DELIVERY`) em pedido do tipo `DELIVERY`.	Open Delivery
`CONCLUDED`	Entregue ou retirado (`DONE`).	Open Delivery
`CANCELLED`	O pedido foi cancelado, por qualquer caminho: API, painel ou cliente.	Open Delivery	`metadata.reason`, `metadata.code`
`MODIFIED`	O conteúdo do pedido foi editado (itens, valores, endereço). Busque o pedido de novo em `orderURL`.	Extensão MeuPedido
`COURIER_ASSIGNED`	Um entregador foi atribuído ao pedido (rota criada).	Extensão MeuPedido	`delivery`
`COURIER_ROUTE_STARTED`	O entregador iniciou a rota.	Extensão MeuPedido	`delivery`
`COURIER_PICKED_UP`	O entregador retirou o pedido na loja.	Extensão MeuPedido	`delivery`
`COURIER_ARRIVED`	O entregador chegou ao endereço do cliente.	Extensão MeuPedido	`delivery`
`COURIER_DELIVERED`	O entregador registrou a entrega.	Extensão MeuPedido	`delivery`
`COURIER_DELIVERY_FAILED`	A tentativa de entrega falhou.	Extensão MeuPedido	`delivery.failureReason`
`COURIER_UNASSIGNED`	O entregador foi desatribuído; o pedido volta a aguardar rota.	Extensão MeuPedido	`delivery`
`COURIER_ROUTE_COMPLETED`	A rota do entregador terminou.	Extensão MeuPedido	`delivery`

Alguns tipos previstos no padrão Open Delivery 1.4.0 nunca aparecem no feed do MeuPedido: PICKUP_AREA_ASSIGNED, DELIVERED, CANCELLATION_REQUESTED e CANCELLATION_REQUEST_DENIED. A entrega é sinalizada por CONCLUDED; o cancelamento é imediato, então não existe pedido de cancelamento pendente ou negado. Detalhes em Compatibilidade.

Também não existe evento para PENDING e PENDING_PAYMENT: o pedido nasce para a sua integração no CREATED. Retrocessos de situação (por exemplo, confirm em um pedido PREPARING) não geram evento.

Eventos por tipo de pedido

Situação	Pedido `DELIVERY`	Pedido `TAKEOUT` ou `INDOOR`
`PENDING`	`CREATED`	`CREATED`
`ACCEPTED`	`CONFIRMED`	`CONFIRMED`
`PREPARING`	`PREPARING`	`PREPARING`
`READY`	`READY_FOR_PICKUP`	`READY_FOR_PICKUP`
`DELIVERY`	`DISPATCHED`	`READY_FOR_PICKUP`
`DONE`	`CONCLUDED`	`CONCLUDED`
`CANCELLED`	`CANCELLED`	`CANCELLED`

metadata

CANCELLED

"metadata": {
  "reason": "Produto em falta.",
  "code": "OTHER_CANCELLATION_REASON"
}

Campo	Valores	Descrição
`reason`	texto	O motivo registrado por quem cancelou. Pela API, é o `reason` enviado em `requestCancellation` (ou o padrão).
`code`	`CONSUMER_CANCELLATION_REQUESTED`, `OTHER_CANCELLATION_REASON`	`CONSUMER_CANCELLATION_REQUESTED` quando o cliente cancelou; `OTHER_CANCELLATION_REASON` para loja, painel e API. O `code` enviado em `requestCancellation` não influencia este valor.

CONFIRMED

metadata vem como {}. O campo existe porque o padrão o exige presente para este tipo; não há nada dentro.

O bloco delivery

Presente apenas nos eventos COURIER_*. Descreve a rota e a parada do pedido dentro dela.

{
  "eventId": "7a2d9f4b-1e6c-4d3a-b8f0-5c2e9d1a4b7f",
  "eventType": "COURIER_ARRIVED",
  "orderId": "3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d",
  "orderURL": "https://api.meupedido.io/open-delivery/v1/orders/3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d",
  "createdAt": "2026-09-19T14:41:07Z",
  "delivery": {
    "routeId": "b4c1d2e3-f4a5-4b6c-8d7e-9f0a1b2c3d4e",
    "routeCode": "R-0217",
    "courierId": "c9d8e7f6-a5b4-4c3d-9e2f-1a0b9c8d7e6f",
    "courierName": "Carlos Andrade",
    "stopStatus": "ARRIVED",
    "sequence": 2,
    "failureReason": null,
    "etaAt": "2026-09-19T14:45:00Z",
    "claimSource": "MERCHANT_DISPATCH"
  }
}

Campo	Tipo	Descrição
`routeId`	GUID	Identificador da rota. Uma rota pode ter vários pedidos.
`routeCode`	string	Código curto da rota, o mesmo que o lojista vê no painel.
`courierId`	GUID	Identificador do entregador.
`courierName`	string	Nome do entregador.
`stopStatus`	string	Situação da parada deste pedido na rota: `PENDING`, `EN_ROUTE`, `ARRIVED`, `DELIVERED`, `FAILED` ou `UNASSIGNED`.
`sequence`	inteiro	Posição da parada na rota, a partir de 1.
`failureReason`	string	Motivo da falha, em `COURIER_DELIVERY_FAILED`.
`etaAt`	data	Previsão de chegada, UTC com `Z`, quando calculada.
`claimSource`	string	Como o entregador assumiu a rota (por exemplo, `MERCHANT_DISPATCH` quando a loja despachou).

Os campos de delivery podem vir como null quando não se aplicam ao evento. Trate sequence, etaAt e failureReason como opcionais.

Como reagir a cada evento

Evento	O que fazer
`CREATED`	Buscar o pedido em `orderURL`, gravar, exibir. Depois, `confirm`.
`MODIFIED`	Buscar o pedido de novo e substituir a cópia local.
`CONFIRMED`, `PREPARING`, `READY_FOR_PICKUP`, `DISPATCHED`, `CONCLUDED`	Atualizar a situação local. Se a ação partiu do seu sistema, o evento confirma o que você já sabe.
`CANCELLED`	Marcar como cancelado com `metadata.reason`; parar preparo e entrega.
`COURIER_*`	Opcional. Exibir o entregador e a previsão para a loja ou para o cliente.

Em todos os casos, confirme o eventId em acknowledgment depois de processar.

Próximos passos

Polling: consumir e confirmar eventos.
Estrutura do pedido: o que vem em orderURL.
Ciclo de vida do pedido: as transições por trás de cada evento.