Skip to main content
A integração de PDV ou ERP tem dois objetivos: manter preço e disponibilidade do catálogo online iguais aos do PDV e levar o pedido da Onbeef para o PDV faturar. Você pode implementar só um dos dois ou os dois.

O que a integração faz

O modelo recomendado

A loja opera o pedido na Onbeef e o PDV importa o pedido fechado. É a posição oficial da Onbeef para PDV e ERP.
  1. O cliente pede no catálogo online.
  2. A loja aceita, pesa, ajusta e entrega o pedido pelo painel da Onbeef.
  3. O PDV consulta os eventos no polling a cada 30 segundos, sempre com start_at. O webhook é opcional, para tempo real.
  4. No evento DELIVERED, o PDV busca o pedido em GET /v1/orders/{id}, fatura e confirma o evento.
Nesse modelo o PDV só lê e confirma eventos. Ele não chama confirm, readyForPickup, dispatch nem delivered.

Por que importar o pedido fechado

  • Carne é vendida por peso. O cliente pede 1 kg, a loja pesa 1,080 kg, e o pedido muda depois de criado.
  • Ajuste de item ou peso não gera evento. O PDV só vê o peso novo se consultar o pedido de novo.
  • DELIVERED é o único ponto em que o pedido não muda mais. Antes disso a loja ainda pode ajustar.
  • A API não recebe ajuste vindo do PDV. Mudou item, peso ou valor no PDV: não muda na Onbeef, e os pontos de fidelidade do cliente ficam errados. A loja ajusta na Onbeef, em Ajustar o pedido ou bipando a etiqueta da balança no pedido.
Não fature antes do DELIVERED. No CREATED, quantidade e total são provisórios até a loja confirmar o peso. Caso real: um PDV consultou o pedido 1 minuto depois do Pronto, a loja pesou 14 minutos depois (0,720 kg virou 0,600 kg) e o cupom saiu com o peso errado.
O PDV precisa do pedido antes da entrega, para separação ou expedição? Aceite READY_FOR_PICKUP, DISPATCHED ou DELIVERED como gatilho, o que chegar primeiro, acompanhe o CANCELLED e consulte de novo no DELIVERED antes de faturar. O guia Quando importar o pedido traz a tabela. Prefere que o PDV conduza o status do pedido? Esse é o modelo alternativo: veja Receba pedidos.

O que a integração não faz

  • Criar pedido na Onbeef. A Onbeef é a origem do pedido.
  • Alterar itens, peso ou valor de um pedido. A API recebe só status e cancelamento.
  • Trazer o desconto de Ajustar valor. Para dar desconto num pedido, a loja integrada usa Desconto personalizado, que vem em discounts. Ajustar valor não vem na API.
  • Enviar vendas do balcão ou clientes para a Onbeef.
  • Levar pontos de fidelidade de um sistema para o outro. O ideal é a loja usar o programa de fidelidade da Onbeef, não um programa de pontos do PDV: a Onbeef calcula os pontos sobre o pedido feito nela, com as regras do programa da loja.
  • Levar estoque. A API não envia nem recebe estoque. Produto acabou: marque como indisponível com ITEM_OFFER e status: "UNAVAILABLE".
  • Criar ou marcar promoção. price.originalValue é ignorado. Promoção é manual no painel.
  • Sincronizar cortes, temperos, complementos e horários, ou criar kit. Ficam no painel da Onbeef.
  • Avisar o PDV de mudança de catálogo feita no painel. O catálogo é mão única, do PDV para a Onbeef. A leitura é GET /v1/merchant.
  • Listar pedidos. Só os eventos trazem o id de cada pedido.

Loja que já tem produtos na Onbeef

O vínculo entre o produto do PDV e o da Onbeef é só pelo Código de integração com PDV, em produto e em categoria. Sem o código, a sincronização cria outro produto e outra categoria: a loja fica com item duplicado e categoria vazia. Antes da primeira sincronização de uma loja que já vende, passe os códigos para o lojista preencher. Veja Vincule uma loja que já tem produtos.

Roteiro

1

Faça a primeira chamada

Peça a loja de teste, gere a chave e consulte a loja. Veja o Início rápido.
2

Sincronize o catálogo

Leia Como o catálogo funciona e siga Sincronize o catálogo. O guia traz a tabela “o que aconteceu no PDV, o que enviar”. No envio MERCHANT, leia antes status em GET /v1/merchant e reenvie o mesmo valor em merchantStatus.
3

Receba os pedidos

Leia Como um pedido funciona e ligue o polling: é ele que garante que nenhum pedido se perde. Envie start_at em toda consulta, fixo na data em que a integração começou a valer na loja. O webhook de pedidos é opcional.
4

Importe o pedido no ponto certo

Siga Quando importar o pedido e use Entenda os dados do pedido para mapear itens, totais e pagamento.
5

Passe para produção

Confira o checklist de produção. Não há homologação.
6

Oriente o seu lojista

Quem explica a integração para a loja é você: de onde vêm os códigos, que o pedido só entra no PDV depois de marcado como Entregue (inclusive retirada) e o que ajustar na Onbeef. As páginas Ative a integração e Vincule os produtos ajudam.

Sincronize o catálogo

O que enviar em cada situação, com payload mínimo.

Quando importar o pedido

Quando importar e como lidar com o ajuste de peso.