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

# Quando importar o pedido

> Deixe a loja operar o pedido na Onbeef e importe o pedido fechado no PDV, quando peso e total não mudam mais.

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.

Implemente a importação de pedidos fechados da Onbeef no meu PDV, seguindo [https://docs.onbeef.app/guides/order-import.md](https://docs.onbeef.app/guides/order-import.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md)

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

| Pedido | Até quando a loja pode ajustar |
| - | - |
| Pago online | Uma vez, antes de sair para entrega. Em retirada, antes de ficar pronto. |
| Pago na entrega | Quantas vezes precisar, até a entrega. |

`DELIVERED` é o único ponto em que nenhum pedido muda mais. Depois dele, a loja não cancela pelo painel.

## Quando importar

| O seu sistema | Importe | Como |
| - | - | - |
| Só fatura ou emite cupom | No `DELIVERED` | Filtre o polling por `DELIVERED` e `CANCELLED`, e consulte o pedido. |
| Precisa do pedido antes (separação, expedição) | A partir de `READY_FOR_PICKUP` | Use `READY_FOR_PICKUP`, `DISPATCHED` ou `DELIVERED` como gatilho. Consulte de novo no `DELIVERED` antes de faturar. |

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

```bash Ambiente de teste theme={null}
curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13" \
  -H "Authorization: Bearer <access_token>"
```

O limite de 1000 itens vale depois do filtro.

**2. Consulte o pedido**

```bash Ambiente de teste theme={null}
curl "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}" \
  -H "Authorization: Bearer <access_token>"
```

Pesos e total já são finais: veja [Entenda os dados do pedido](https://docs.onbeef.app/guides/order-data.md).

**3. Fature e confirme o evento**

Depois de gravar e faturar, [confirme o evento](https://docs.onbeef.app/guides/order-flow.md#passo-a-passo). Confirme também o `CANCELLED`, sem faturar.

Para importar antes, troque o filtro:

```text theme={null}
?eventType=READY_FOR_PICKUP&eventType=DISPATCHED&eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13
```

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

| No painel | Na API |
| - | - |
| **Desconto personalizado**, em **adicionar desconto**, no detalhe do pedido | Vem em `discounts[]` e entra em `total.discount`. |
| **Ajustar valor**: troca o total sem mexer nos itens | Não vem. O pedido sai com a soma dos itens. |

> [!WARNING]
>
> 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`.

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

> [card] [Entenda os dados do pedido](https://docs.onbeef.app/guides/order-data.md)
>
> Itens, totais e pagamento.

> [card] [Receba pedidos](https://docs.onbeef.app/guides/order-flow.md)
>
> Polling e confirmação.


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