Skip to main content
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.

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

Receba os pedidos

Cadastre o webhook de pedidos 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. A referência está em dispatch e delivered.
4

Passe para produção

Confira o checklist de produção. Em produção, quem gera a chave é o lojista.

Integre as entregas

O passo a passo, do pedido recebido à entrega.

Webhook de pedidos

Receba os eventos no seu servidor em tempo real.