Skip to main content
A loja opera o pedido na Onbeef: aceita, pesa, ajusta e entrega. O PDV ou ERP importa o pedido fechado para faturar. É o modelo que a Onbeef recomenda: o seu sistema só lê e confirma eventos.

Por que o pedido muda

Carne é vendida por peso. O cliente pede 1 kg, a loja pesa 1,080 kg, e quantidade e total mudam depois de criado. A loja ajusta no painel, em Ajustar o pedido, ou bipando a etiqueta da balança no pedido. Ajustar item ou peso não gera evento. O seu sistema só vê a mudança quando consulta GET /v1/orders/{orderId} de novo. DELIVERED é o único ponto em que nenhum pedido muda mais. Depois dele, a loja não cancela pelo painel.

Quando importar

Regras

  • Não fature no CREATED. Quantidade e total são provisórios até a loja confirmar o peso. Importar para a loja ver o pedido, pode.
  • Aceite três eventos como gatilho. O polling só mostra o evento mais recente: se o pedido sair antes da sua consulta, você vê DISPATCHED e nunca READY_FOR_PICKUP.
  • Consulte de novo antes de faturar. O pedido lido no READY_FOR_PICKUP ainda pode mudar. Caso real: um PDV emitiu o cupom no Pronto, com 0,720 kg. A loja pesou 14 minutos depois e ajustou para 0,600 kg, sem evento.
  • Dê um botão à loja. “Atualizar pedido da Onbeef”, no PDV, cobre o ajuste feito depois da importação.
  • Sem Entregue, sem DELIVERED. O evento só existe quando a loja marca Entregue, inclusive na retirada. Pedido parado em Pronto nunca chega: avise a loja.
  • Envie start_at em toda consulta, fixo na data em que a integração começou a valer na loja. Sem ele, a consulta devolve primeiro os pedidos mais antigos da loja.
  • Ignore salesChannel: "IMPORT_CUSTOMER". É histórico de cliente importado: vem DELIVERED, sem itens. Confirme o evento e não fature.
  • Não chame as ações de status. Ficam com a loja, no painel.
  • A API só recebe status e cancelamento. Item, peso ou valor alterado no PDV não muda o pedido na Onbeef, e os pontos de fidelidade do cliente ficam errados. Oriente a loja a ajustar na Onbeef.

Passo a passo

1

Consulte os pedidos entregues e os cancelados

Ambiente de teste
O limite de 1000 itens vale depois do filtro.
2

Consulte o pedido

Ambiente de teste
Pesos e total já são finais: veja Entenda os dados do pedido.
3

Fature e confirme o evento

Depois de gravar e faturar, confirme o evento. Confirme também o CANCELLED, sem faturar.
Para importar antes, troque o filtro:

Pedido agendado na virada

O filtro é pela data de criação. Pedido feito antes da data do start_at e entregue depois não aparece: no dia da virada, recue o start_at 7 dias e ignore o pedido que já estava entregue antes da virada.
  • Entrega. Ignore o pedido com delivery.deliveryDateTime anterior à data da virada.
  • Retirada. A data em que o cliente retirou não vem na API: combine com a loja.
Exemplo: a integração começa no dia 13. A encomenda feita no dia 11 para o dia 14 aparece com start_at=2026-11-06. Um start_at que anda com o dia perde toda encomenda feita com antecedência.

Cancelado depois de faturado

  • A loja cancelou depois da importação. Chega CANCELLED: cancele a pré-venda ou o documento emitido.
  • Devolução e estorno de pedido entregue. Ficam fora da API: trate no PDV.
  • O suporte da Onbeef cancelou um pedido entregue. Chega CANCELLED depois do DELIVERED já confirmado: cancele o documento fiscal. Por isso o filtro inclui CANCELLED.

Desconto dado pela loja

Os itens somam R$ 100,00 e a loja usa Ajustar valor para cobrar R$ 90,00: a API devolve R$ 100,00 em total.orderAmount, e nenhum campo avisa. Oriente a loja integrada: para dar desconto, Desconto personalizado; para corrigir peso ou quantidade, Ajustar o pedido; Ajustar valor, nunca.

Teste

No ambiente de teste (sandbox), crie um pedido com produto por quilo em Painel de Vendas > Novo pedido. Consulte, ajuste o peso em Ajustar o pedido e consulte de novo: quantity e total mudam, sem evento novo. Marque Entregue e confira o DELIVERED.

Entenda os dados do pedido

Itens, totais e pagamento.

Receba pedidos

Polling e confirmação.