Eventos de Pedidos

Esta seção contém informações sobre os endpoints de eventos de pedidos da API OpenDelivery. Através destas rotas, é possível consultar novos eventos relacionados a pedidos e confirmar o processamento desses eventos.

Visão Geral

O módulo de eventos de pedidos implementa um mecanismo de polling para notificar aplicações externas sobre mudanças no estado dos pedidos, como criação de novos pedidos, atualizações de status, cancelamentos, entre outros.

Endpoints Principais

Método	Endpoint	Descrição
GET	/opendelivery/v1/events:polling	Consulta novos eventos relacionados a pedidos
POST	/opendelivery/v1/events/acknowledgment	Confirma o processamento de eventos

Parâmetros de Requisição

Consulta de Eventos (Polling)

Este endpoint não requer parâmetros específicos.

Confirmação de Eventos (Acknowledgment)

O endpoint de confirmação (acknowledgment) aceita um array de eventos a serem confirmados, com limite máximo de 100 itens por requisição. Cada item do array deve conter:

Parâmetro	Localização	Tipo	Descrição
id	body	string	ID do evento a ser confirmado (UUID)
orderId	body	string	ID do pedido relacionado ao evento (UUID)
eventType	body	string	Tipo do evento (ver tabela de Tipos de Eventos abaixo)

Limites de Uso (Rate Limiting)

Os endpoints de eventos possuem as seguintes restrições de uso:

Endpoint	Limite	Janela de Tempo
GET /opendelivery/v1/events:polling	2 requisições	1 minuto
POST /opendelivery/v1/events/acknowledgment	100 requisições	1 minuto

Quando o limite é excedido, a API retorna o código de status HTTP 429 (Too Many Requests).

Tipos de Eventos

Os eventos podem ser de diferentes tipos, incluindo:

Tipo de Evento	Descrição
CREATED	Pedido criado
CONFIRMED	Pedido confirmado pelo estabelecimento
PREPARATION_REQUESTED	Preparação do pedido solicitada
PREPARING	Pedido em preparação
DISPATCHED	Pedido despachado para entrega
READY_FOR_PICKUP	Pedido pronto para retirada
PICKUP_AREA_ASSIGNED	Área de retirada atribuída
PICKED_UP	Pedido retirado pelo entregador
DELIVERED	Pedido entregue ao cliente
CONCLUDED	Pedido concluído
CANCELLATION_REQUESTED	Cancelamento do pedido solicitado
CANCELLATION_REQUEST_DENIED	Solicitação de cancelamento negada
CANCELLED	Pedido cancelado
ORDER_CANCELLATION_REQUEST	Solicitação de cancelamento de pedido
CANCELLED_DENIED	Cancelamento do pedido negado

Estrutura de Eventos

A resposta da consulta de eventos contém um array de eventos:

[
  {
    "eventId": "abb14b1f-f1c8-4706-8016-ad353e15216a",
    "eventType": "CREATED",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:53:54.433Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  },
  {
    "eventId": "d828039b-62ab-4874-bab4-3be6cbfdc4fb",
    "eventType": "CONFIRMED",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:57:58.341Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  },
  {
    "eventId": "634754ba-70ad-48ee-8f6b-7409412bed17",
    "eventType": "PREPARING",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:58:10.040Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  },
  {
    "eventId": "930b4e78-fb6f-469e-a137-13f9e30e08b1",
    "eventType": "DISPATCHED",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:58:18.238Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  },
  {
    "eventId": "b025cf7f-4978-41fd-b189-57d99ce0f7b0",
    "eventType": "DELIVERED",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:58:26.965Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  }
]

Fluxo de Processamento de Eventos

O fluxo de processamento de eventos segue as seguintes etapas:

1. A aplicação externa consulta periodicamente o endpoint de polling para verificar novos eventos
2. Ao receber novos eventos, a aplicação processa cada evento conforme necessário
3. Após processar os eventos, a aplicação confirma o processamento através do endpoint de acknowledgment
4. Os eventos confirmados não serão retornados em consultas futuras

Boas Práticas

• Respeite o limite de polling de 2 requisições a cada 1 minuto
• Implemente um mecanismo de backoff exponencial em caso de erros
• Processe todos os eventos recebidos antes de fazer uma nova consulta
• Confirme o processamento dos eventos assim que forem tratados
• Agrupe múltiplos eventos em uma única requisição de acknowledgment para melhor performance

Exemplo de Requisição e Resposta

Consulta de Eventos

GET /opendelivery/v1/events:polling HTTP/1.1
Host: partner-api.goomer.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Resposta:

[
  {
    "eventId": "abb14b1f-f1c8-4706-8016-ad353e15216a",
    "eventType": "CREATED",
    "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
    "createdAt": "2025-06-24T16:53:54.433Z",
    "orderURL": "https://partner-api.goomer.app/order/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a"
  }
]

Confirmação de Eventos (HTTP)

POST /opendelivery/v1/events/acknowledgment HTTP/1.1
Host: partner-api.goomer.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

[
  {
    "id": "321e4567-e89b-12d3-a456-426614173000",
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "eventType": "CREATED"
  },
  {
    "id": "321e4567-e89b-12d3-a456-426614173001",
    "orderId": "123e4567-e89b-12d3-a456-426614174001",
    "eventType": "PREPARATION_REQUESTED"
  }
]

Códigos de Status

Código	Descrição
200	Sucesso (para consulta de eventos)
202	Evento confirmado com sucesso (para confirmação de eventos)
400	Requisição inválida
401	Não autorizado
429	Limite de requisições excedido

Documentação Completa

Para informações detalhadas sobre parâmetros, payload e exemplos adicionais, consulte a documentação técnica completa.