> ## 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 uma empresa de entregas

> Receba os eventos dos pedidos da loja com uma chave gerada por ela, chame o entregador e informe a saída e a entrega.

A empresa de entregas usa a mesma API de pedidos do PDV, com uma chave gerada pela loja, sem ativação com a Onbeef. É a parte de pedidos do padrão Open Delivery, não a de logística.

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

## Como funciona

1. A loja gera uma chave no painel e envia o **ID** e a **Chave** para você.
2. Você recebe os eventos de todos os pedidos da loja, por webhook e polling. Um evento é um aviso de que o pedido mudou: chegou, ficou pronto, foi cancelado.
3. Você consulta o pedido em `GET /v1/orders/{id}`: endereço em `delivery.deliveryAddress`, cliente e pagamento.
4. Você chama o entregador no evento `CONFIRMED` (a loja aceitou) ou `READY_FOR_PICKUP` (o pedido está pronto).
5. Antes de o entregador sair, você consulta o pedido de novo: o peso e o valor a cobrar mudam sem evento.
6. O entregador saiu: chame `dispatch`. O pedido fica **Em rota** e o cliente recebe a mensagem de WhatsApp de saída.
7. O entregador entregou: chame `delivered`. O pedido fica **Entregue**.

### Regras

* **Você recebe todos os pedidos, não só os de entrega.** Não há filtro. Trate só `type: "DELIVERY"` e confirme os eventos de retirada (`TAKEOUT`), para saírem do polling.
* **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.
* **Pedido agendado.** Traz `orderTiming: "SCHEDULED"` e a janela em `schedule`. Não há evento no dia: o sinal continua sendo `CONFIRMED` e `READY_FOR_PICKUP`, quando a loja começar a preparar.
* **O que cobrar na porta.** `PREPAID`: já está pago, não cobre. `PENDING`: não está pago. Cobre só se `method` for dinheiro, PIX, cartão ou vale e a loja confirmar que o pedido é para pagar na entrega. `OTHER` (fiado, link de pagamento, boleto) nunca se cobra na porta.
* **A API não diz quais entregas são suas.** Se a loja tem entregador próprio, combine com ela quais pedidos são seus.
* **Não chame `confirm` nem `readyForPickup`.** Quem aceita e prepara é a loja.
* **Só chame `dispatch` depois de `READY_FOR_PICKUP`.** No mínimo, depois de `CONFIRMED`. A API aplica o `dispatch` mesmo em pedido que a loja ainda não aceitou.
* **`202` não é confirmação.** A confirmação é o evento `DISPATCHED` ou `DELIVERED`. Sem ele em cerca de 70 segundos, a mudança não foi aplicada e não há aviso de erro: consulte o pedido. `lastEvent` e `type` mostram o motivo (retirada, já entregue, cancelado, já em rota).
* **Quem marca a saída.** A loja e o PDV integrado também marcam **Em rota** e **Entregue**. Vale a primeira chamada: a segunda é ignorada. Combine com a loja quem conduz.
* **Código de confirmação de entrega.** Não existe. A entrega é confirmada só com `delivered`.
* **Loja cancelou: você recebe `CANCELLED`.** Dispense o entregador.
* **Entrega que não deu certo: avise a loja, não cancele.** O cancelamento pela API estorna o pagamento online do cliente.
* **A chave não tem escopo.** Dá o mesmo acesso da chave do PDV: catálogo e pedidos.
* **O limite de requisições é da loja.** São 200 leituras e 60 escritas por minuto, divididas com as outras integrações. A consulta a cada 30 segundos cabe: 2 leituras por minuto, mais uma por pedido novo. Em `429`, repita depois do `Retry-After`.
* **Rastreamento.** Nome do entregador, posição e previsão não aparecem para a loja nem para o cliente. Não há o que enviar: a Onbeef mostra só **Em rota** e **Entregue**.

## Já tem API de logística no padrão Open Delivery?

Nesse modelo é a Onbeef que chama o seu sistema. Ele depende de desenvolvimento do lado da Onbeef, combinado caso a caso: escreva para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br). O caminho desta página não depende disso.

## 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. Receba os pedidos**

Cadastre o [webhook de pedidos](https://docs.onbeef.app/guides/orders-webhook.md) e deixe o polling ligado: é ele que garante que nenhum pedido se perde. Com várias lojas na mesma URL, o header `X-App-MerchantId` diz de qual loja é o aviso.

**3. Informe a saída e a entrega**

Siga o guia [Integre as entregas](https://docs.onbeef.app/guides/delivery-flow.md). A referência está em [`dispatch`](https://docs.onbeef.app/api-reference/orders/dispatch) e [`delivered`](https://docs.onbeef.app/api-reference/orders/delivered).

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

Confira o [checklist de produção](https://docs.onbeef.app/environments/production.md#checklist). Em produção, quem gera a chave é o lojista.

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

> [card] [Integre as entregas](https://docs.onbeef.app/guides/delivery-flow.md)
>
> O passo a passo, do pedido recebido à entrega.

> [card] [Webhook de pedidos](https://docs.onbeef.app/guides/orders-webhook.md)
>
> Receba os eventos no seu servidor em tempo real.


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