> ## 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.

# Integre um PDV ou ERP

> Mantenha o catálogo online igual ao do PDV e importe o pedido fechado para faturar. Veja o modelo recomendado e o roteiro.

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.

Integre meu PDV com a Onbeef Connect API seguindo [https://docs.onbeef.app/desenvolvedores/pdv.md](https://docs.onbeef.app/desenvolvedores/pdv.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md)

## O que a integração faz

| | Direção | Resultado para a loja |
| - | - | - |
| **Catálogo** | PDV → Onbeef | Preço mudou ou produto acabou no PDV: o catálogo online acompanha. Produto novo no PDV entra na Onbeef. |
| **Pedidos** | Onbeef → PDV | O pedido feito na Onbeef entra no PDV com itens, pesos, totais, pagamento e cliente, pronto para faturar. |

## 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.

> [!WARNING]
>
> 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](https://docs.onbeef.app/guides/order-import.md) traz a tabela.

Prefere que o PDV conduza o status do pedido? Esse é o modelo alternativo: veja [Receba pedidos](https://docs.onbeef.app/guides/order-flow.md).

## 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](https://docs.onbeef.app/guides/catalog-linking.md).

## 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](https://docs.onbeef.app/quickstart.md).

**2. Sincronize o catálogo**

Leia [Como o catálogo funciona](https://docs.onbeef.app/concepts/merchant.md) e siga [Sincronize o catálogo](https://docs.onbeef.app/guides/catalog-sync.md). 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](https://docs.onbeef.app/concepts/orders.md) 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](https://docs.onbeef.app/guides/orders-webhook.md) é opcional.

**4. Importe o pedido no ponto certo**

Siga [Quando importar o pedido](https://docs.onbeef.app/guides/order-import.md) e use [Entenda os dados do pedido](https://docs.onbeef.app/guides/order-data.md) para mapear itens, totais e pagamento.

**5. Passe para produção**

Confira o [checklist de produção](https://docs.onbeef.app/environments/production.md#checklist). 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](https://docs.onbeef.app/lojistas/ativar.md) e [Vincule os produtos](https://docs.onbeef.app/lojistas/vincular-produtos.md) ajudam.

Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente

> [card] [Sincronize o catálogo](https://docs.onbeef.app/guides/catalog-sync.md)
>
> O que enviar em cada situação, com payload mínimo.

> [card] [Quando importar o pedido](https://docs.onbeef.app/guides/order-import.md)
>
> Quando importar e como lidar com o ajuste de peso.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.