Skip to main content
Além de acompanhar pedidos novos, o polling permite consultar pedidos antigos cujo evento atual ainda não foi confirmado, inclusive os que já chegaram a um estado final. Com os filtros start_at e end_at, você consulta os pedidos de um período sem precisar de um endpoint separado. Use este caminho quando precisar de dados para relatórios, dashboards ou uma carga inicial ao integrar uma loja que já vende pela Onbeef.

​
Como consultar

Informe o período em GET /v1/events:polling e não confirme os eventos retornados.
Os filtros usam a data de criação do pedido, não a do evento. Os dois limites são inclusivos.
  • Com Y-m-d, a API usa o dia inteiro no horário local da loja: start_at começa às 00:00:00 e end_at termina às 23:59:59.
  • Com 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, start_at=2026-07-01 00:00 filtra a partir de 2026-06-30 21:00:00.
Para relatórios diários, use sempre Y-m-d. Pedir 2026-08-03 00:00 até 2026-08-03 23:59 não retorna o dia 3: a janela vira 2026-08-02 21:00:00 até 2026-08-03 20:59:00, incluindo a noite do dia anterior e cortando as últimas 3 horas do dia.
A resposta traz orderId e orderURL para cada pedido. Use GET /v1/orders/{orderId} para obter itens, valores, cliente, pagamento e entrega de cada um.
1

Defina o período

Consulte o polling com start_at e end_at. Ajuste o tamanho da janela ao volume da loja, para que cada consulta retorne menos de 1000 pedidos.
2

Percorra os pedidos retornados

Para cada item da resposta, consulte GET /v1/orders/{orderId} e armazene os dados no seu sistema.As rotas de leitura aceitam até 200 requisições por minuto, um limite compartilhado entre o polling e a consulta individual de pedidos. Uma resposta cheia gera 1001 requisições, então distribua as consultas ao longo do tempo para não impactar a operação da loja. Veja Limite de requisições.
3

Não envie o acknowledgment

Não chame POST /v1/events/acknowledgment para esses eventos. A confirmação os remove do polling desta chave de integração.

​
O acknowledgment remove o pedido da sua consulta

O acknowledgment é irreversível para o par orderId e eventId. Enquanto esse for o evento atual do pedido, ele não aparece no polling da sua chave de integração, mesmo que você informe start_at e end_at. A API não oferece uma listagem de pedidos para reencontrá-lo.
Os filtros de data são combinados com o filtro de eventos não confirmados. Informar um período não traz de volta um evento que você já confirmou por acknowledgment. Se o pedido mudar de estado depois disso, o novo evento ainda não confirmado poderá fazê-lo aparecer novamente. Não conte com esse comportamento para recuperar dados: um pedido que já está em estado final não muda mais. Por isso, escolha um dos dois modos de uso para cada chave de integração:
Se a sua integração precisa operar pedidos e manter o histórico, use duas chaves de integração distintas: uma que confirma os eventos e outra que apenas consulta.

​
O acknowledgment é isolado por chave de integração

Cada acknowledgment é registrado para a chave de integração que fez a chamada. Ele não afeta as demais. Isso significa que, se o açougue tiver mais de um integrador conectado, o acknowledgment de um não remove os pedidos da sua consulta. Cada integração tem a sua própria visão do polling e drena a própria fila no seu ritmo.
Exemplo: o PDV da loja confirma todos os eventos normalmente. A sua ferramenta de relatórios, com outra chave, continua vendo todos os pedidos do período, porque ela nunca enviou acknowledgment.

​
Cargas incrementais

Os filtros de data usam a data de criação do pedido, não a da última atualização. Consultar apenas os pedidos criados desde a última carga não mostra as mudanças de estado de pedidos criados antes dela.
Um pedido criado hoje e cancelado amanhã não aparece na carga de amanhã, porque a data de criação dele está fora da nova janela. Se a sua carga ignorar pedidos já importados, o dashboard mantém o estado antigo para sempre.
Para manter os dados corretos:
  • Releia as janelas que ainda contêm pedidos não finalizados, em vez de avançar apenas para a janela mais recente.
  • Use orderId como chave de upsert, não de deduplicação. Ao reprocessar um período, atualize o registro existente, porque o estado do pedido pode ter mudado.
  • Continue atualizando cada pedido até ele chegar a CONCLUDED ou CANCELLED. A partir daí o estado não muda mais.

​
Limites e boas práticas

  • A resposta retorna no máximo 1000 pedidos por consulta, dos mais antigos para os mais novos. Não há paginação, cursor nem indicador de truncamento. Se você receber exatamente 1000 itens, trate a resposta como possivelmente truncada e subdivida o período até cada consulta retornar menos de 1000.
  • Como os limites de data são inclusivos, sobreponha as bordas das janelas e faça upsert pelo orderId para não perder pedidos.
  • Cada pedido aparece no máximo uma vez, com o seu evento mais recente. O polling não devolve o histórico de transições de um pedido, então não use a resposta para medir tempos entre estados.
  • Faça as consultas de histórico com baixa frequência, como uma vez por dia. Mantenha o polling operacional em uma chave separada, no intervalo curto recomendado para a operação.

Entenda o ciclo do pedido

Veja os estados, os eventos e o papel do acknowledgment na operação.