> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onbeef.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Consulte o histórico de pedidos
> Use o polling com filtro de datas para carregar pedidos antigos, sem confirmar os eventos.
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.
```bash Sandbox theme={null}
curl --request GET \
--url "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-07-01&end_at=2026-07-31" \
--header "Authorization: Bearer "
```
```bash Produção theme={null}
curl --request GET \
--url "https://api.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-07-01&end_at=2026-07-31" \
--header "Authorization: Bearer "
```
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.
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.
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](/api-reference/errors#limite-de-requisi%C3%A7%C3%B5es).
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:
| Objetivo | Acknowledgment | Resultado |
| -------------------------------------- | ------------------------------------- | ----------------------------------------------------- |
| Operar os pedidos (PDV) | Confirme cada evento após processá-lo | O conjunto de eventos pendentes se mantém enxuto |
| Consultar o histórico (BI, relatórios) | Não confirme nenhum evento | Os pedidos continuam disponíveis para novas consultas |
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.
Veja os estados, os eventos e o papel do acknowledgment na operação.