Skip to main content
GET
Consulte eventos
Consulte este endpoint para receber eventos de pedidos. Depois de processá-los, use Confirmar eventos.

​
Como o polling funciona

GET /v1/events:polling retorna um snapshot do estado atual dos pedidos. Ele não funciona como uma fila nem mantém um histórico completo de eventos. Cada pedido aparece no máximo uma vez na resposta, sempre com seu evento mais recente. O evento continua aparecendo nos pollings seguintes enquanto não for confirmado e continuar sendo o evento atual do pedido. Quando o pedido muda de status, o novo evento substitui o anterior, mesmo que o anterior ainda não tenha sido confirmado.
Exemplo: o polling retorna CREATED, mas o pedido muda para CONFIRMED antes do acknowledgment. A próxima consulta retorna apenas CONFIRMED. O evento CREATED não será retornado novamente.
Trate cada evento como um snapshot do pedido. Faça polling em um intervalo curto o suficiente para sua operação e confirme o processamento rapidamente. A resposta retorna no máximo 1000 eventos por consulta, dos pedidos mais antigos para os mais novos: confirme os eventos para drenar a fila.
Este endpoint não fornece um histórico completo de transições. Estados intermediários podem não aparecer. Se sua integração precisa de um histórico para auditoria, não use as respostas do polling como registro de todas as mudanças.

​
Parâmetros de consulta

​
string[]
Filtra eventos por tipo. Repita o parâmetro para informar vários tipos (?eventType=CREATED&eventType=CONFIRMED). Eventos cujo tipo atual não está no filtro não aparecem nesta resposta. O filtro não confirma esses eventos. Se um pedido mudar de status, o novo evento substituirá o anterior e será avaliado pelos filtros da próxima consulta. Omita este parâmetro para receber todos os tipos de eventos pendentes.Valores aceitos:
  • CREATED: O pedido foi criado.
  • CONFIRMED: O pedido foi confirmado pelo merchant.
  • READY_FOR_PICKUP: O pedido está pronto para retirada pelo entregador ou cliente.
  • DISPATCHED: O pedido saiu da loja para entrega.
  • PICKUP_AREA_ASSIGNED: Uma área de retirada foi designada para o pedido.
  • DELIVERED: O pedido foi entregue ao cliente.
  • CONCLUDED: O ciclo de vida do pedido está concluído.
  • CANCELLATION_REQUESTED: O próprio PDV solicitou o cancelamento com POST /v1/orders/{orderId}/requestCancellation. Este evento não exige resposta.
  • CANCELLATION_REQUEST_DENIED: O Ordering Application negou a solicitação de cancelamento.
  • CANCELLED: O pedido foi efetivamente cancelado.
  • ORDER_CANCELLATION_REQUEST: O cliente solicitou o cancelamento pela plataforma. Responda com acceptCancellation ou denyCancellation.
  • CANCELLED_DENIED: O Software Service negou a solicitação de cancelamento do Ordering Application.
​
string (date)
Filtro de data/hora inicial pela data de criação do pedido (não do evento). Limite inclusivo. Um pedido criado antes da janela não aparece, mesmo que o evento atual dele seja recente.Formatos aceitos:
  • Y-m-d: usa o início do dia, às 00:00:00, no horário local da loja.
  • Y-m-d H:i: o horário é interpretado como UTC (horário universal) e convertido para o horário de Brasília, o que recua a janela em 3 horas. Por exemplo, 2026-07-01 00:00 filtra a partir de 2026-06-30 21:00:00.
​
string (date)
Filtro de data/hora final pela data de criação do pedido (não do evento). Limite inclusivo.Formatos aceitos:
  • Y-m-d: usa o fim do dia, às 23:59:59, no horário local da loja.
  • Y-m-d H:i: o horário é interpretado como UTC (horário universal) e convertido para o horário de Brasília, o que recua a janela em 3 horas. O corte ocorre no segundo 00 do minuto informado, porque o parâmetro não aceita segundos.
Os dois formatos não são equivalentes. Se você quer o dia 3 inteiro, use start_at=2026-08-03&end_at=2026-08-03. Informar 2026-08-03 00:00 e 2026-08-03 23:59 filtra de 2026-08-02 21:00:00 até 2026-08-03 20:59:00: inclui a noite do dia anterior e corta as últimas 3 horas do dia pedido.Para consultar dias completos no horário da loja, use sempre Y-m-d. Use Y-m-d H:i apenas se a sua integração trabalha em UTC e você quer esse recorte.
Os filtros de data são aplicados depois do filtro de eventos não confirmados. Um pedido já confirmado não volta a aparecer por causa do período informado. Para usar esses filtros na consulta de pedidos antigos, veja Histórico de pedidos.

​
Resposta

​
200: Sucesso

Retorna um array com o evento atual ainda não confirmado de cada pedido. Cada pedido aparece no máximo uma vez na resposta. Cada objeto inclui o identificador do tipo de evento, o tipo, o ID do pedido associado e um link para os detalhes do pedido.
​
string (uuid)
Identificador do tipo de evento. Todos os pedidos com o mesmo eventType compartilham esse valor.Um evento de pedido é identificado pelo par orderId e eventId. Use sempre os dois valores ao confirmar ou deduplicar eventos. Nunca deduplique apenas por eventId.
​
string
Tipo do evento (por exemplo, CREATED, CONFIRMED, CANCELLED).
​
string (uuid)
Identificador único do pedido associado a este evento, gerado pela Onbeef.
​
string (url)
URL apontando para o recurso completo com os detalhes do pedido.
​
string (date-time)
Timestamp ISO 8601 de criação do pedido (por exemplo, 2019-08-24T14:15:22.000000Z). O valor não muda quando o evento muda.
​
string (uuid)
Identificador da aplicação que originou este evento.
​
string
Marca virtual associada ao pedido, se aplicável.

​
401: Não autorizado

Retornado quando a requisição não inclui credenciais de autenticação válidas.

​
429: Limite de requisições

A rota aceita até 200 requisições por minuto, num limite compartilhado com as outras rotas de leitura. Acima disso, a API responde { "title": "Too Many Requests", "status": 429 }. Veja Limite de requisições.

​
Exemplo de requisição

​
Exemplo de resposta

Confirme cada evento assim que terminar de processá-lo. Um evento não confirmado pode reaparecer enquanto continuar sendo o evento atual do pedido. Se o status mudar antes do acknowledgment, o novo evento substituirá o anterior, que não será retornado novamente.
Recomendamos fazer polling neste endpoint a cada 30 segundos durante o horário de operação. Use o filtro eventType para limitar a resposta apenas aos tipos que sua integração precisa tratar.