Como funciona
- A loja gera uma chave no painel e envia o ID e a Chave para você.
- 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.
- Você consulta o pedido em
GET /v1/orders/{id}: endereço emdelivery.deliveryAddress, cliente e pagamento. - Você chama o entregador no evento
CONFIRMED(a loja aceitou) ouREADY_FOR_PICKUP(o pedido está pronto). - Antes de o entregador sair, você consulta o pedido de novo: o peso e o valor a cobrar mudam sem evento.
- O entregador saiu: chame
dispatch. O pedido fica Em rota e o cliente recebe a mensagem de WhatsApp de saída. - 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_atem 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 emschedule. Não há evento no dia: o sinal continua sendoCONFIRMEDeREADY_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ó semethodfor 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
confirmnemreadyForPickup. Quem aceita e prepara é a loja. - Só chame
dispatchdepois deREADY_FOR_PICKUP. No mínimo, depois deCONFIRMED. A API aplica odispatchmesmo em pedido que a loja ainda não aceitou. 202não é confirmação. A confirmação é o eventoDISPATCHEDouDELIVERED. Sem ele em cerca de 70 segundos, a mudança não foi aplicada e não há aviso de erro: consulte o pedido.lastEventetypemostram 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 doRetry-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.
