Receber pedidos
Receba avisos de novos pedidos e alterações por webhook ou consulte os eventos por polling. Os dois caminhos entregam eventos enxutos, não o pedido completo.
Do restaurante à sua aplicação
Todo evento nasce no restaurante e passa pela BeeFood. O que muda é quem inicia a comunicação: no webhook a BeeFood empurra o evento; no polling sua aplicação puxa.
- A BeeFood envia o evento em tempo real para sua URL
- Sua aplicação responde 2xx e processa
- Sua aplicação consulta /v1/orders/polling a cada 30 segundos
- A BeeFood responde com os eventos
Webhook: a BeeFood avisa sua aplicação
Quando um evento acontece no restaurante, a BeeFood envia um POST para a URL cadastrada. Sua aplicação recebe o aviso sem precisar perguntar se há novidades.
Cadastre uma URL HTTPS pública em Webhooks, no painel do desenvolvedor, e escolha os eventos que deseja receber. Valide X-Webhook-Secret, guarde o evento e responda 2xx antes do processamento demorado.
Quando escolher: para acompanhar pedidos em tempo real, sem consultas periódicas. Reentregas podem repetir eventos: trate-os sem duplicar as operações no seu sistema.
Polling: sua aplicação consulta a BeeFood
Sua aplicação chama GET /v1/orders/polling em intervalos para consultar os eventos. Uma alteração só chega ao seu sistema quando a próxima consulta é feita.
Use um access token com permissão de leitura de pedidos e processe os eventos retornados. Mesmo sem eventos novos, a consulta conta nos limites da API; ao receber 429, aguarde o Retry-After.
Quando escolher: se sua aplicação não puder expor uma URL pública ou precisar recuperar alterações após uma interrupção. O polling não exige um endereço para receber chamadas da BeeFood.
Webhook ou polling?
| Comparação | Webhook | Polling |
|---|---|---|
| Como chega | A BeeFood envia um POST à sua aplicação | Sua aplicação consulta os eventos por GET |
| Quando usar | Caminho recomendado para receber em tempo real | Alternativa sem URL pública ou para reconciliação |
| Preparação | Cadastrar uma URL HTTPS pública no painel | Usar um token com permissão de leitura de pedidos |
| Requisições à API | O recebimento não exige consultas periódicas | Cada consulta consome o limite da API |
Do evento ao pedido
Por exemplo, order_created avisa que um pedido nasceu; order_delivery_updated avisa uma mudança de status de entrega. O significado do evento é o mesmo nos dois caminhos: muda apenas quem inicia a comunicação.
O evento identifica o pedido por orderId e informa o que mudou. Consulte o detalhe do pedido quando precisar de itens, cliente, endereço ou pagamentos.
Guarde os dados necessários ao receber order_created e aproveite os eventos seguintes para atualizar o status. Evite buscar o pedido completo a cada aviso.
Se o recebimento for interrompido
Você pode combinar os dois: webhook no recebimento do dia a dia e polling para reconciliar uma interrupção. Reaproveite o mesmo tratamento de eventos e evite aplicar uma alteração duas vezes.
O polling permite reconciliar eventos das últimas 8 horas. Para períodos maiores, use a listagem de pedidos com filtro de período.
Guias de recebimento
- Polling de pedidos — Consultas, filtros e recuperação de eventos.
- Receber webhooks — Cadastro, segurança, eventos e entregas.
- Webhook desativado — Diagnóstico e retomada do recebimento.