Skip to main content
O fluxo combina webhooks, polling de segurança, consulta do pedido e mudanças de estado. Use o webhook como gatilho principal e mantenha um polling de baixa frequência para recuperar eventos que não foram entregues.

​
Acompanhe os eventos

Configure os dois mecanismos para acompanhar os pedidos:

Webhook: gatilho principal

A Onbeef notifica seu servidor quando um pedido é criado ou muda de status. A notificação contém orderId, eventId e eventType.Para ativar o envio, registre ordersWebhookURL com PUT /v1/merchantOnboarding.

Polling: rede de segurança

Consulte GET /v1/events:polling periodicamente, mesmo com o webhook ativo. A Onbeef não reenvia uma notificação quando seu servidor está indisponível ou responde com erro.
Nos dois caminhos, use orderId para consultar o pedido. Para identificar e confirmar um evento, use o par orderId e eventId. O eventId identifica o tipo do evento e se repete entre pedidos. Nunca deduplique eventos usando apenas eventId. O acknowledgment é obrigatório também para eventos recebidos por webhook.
1

Receba ou consulte os eventos

Se você usa webhook, o fluxo começa quando seu servidor recebe uma notificação. Extraia orderId, eventId e eventType do payload.No polling, consulte GET /v1/events:polling com seu token:
Sandbox
Cada evento retornado também informa orderId, eventId e eventType.Nos dois caminhos, continue para o próximo passo com orderId. Guarde o par orderId e eventId para confirmar o processamento. Nunca use apenas eventId como chave de deduplicação.
2

Consulte e armazene o pedido

Use o orderId em GET /v1/orders/{orderId}. Valide itens, valores, cliente, pagamento e entrega.Armazene os dados necessários no seu sistema antes de continuar.
3

Aceite o pedido

Para um evento CREATED, chame POST /v1/orders/{orderId}/confirm. Informe os campos exigidos pela referência do endpoint.Continue somente depois de receber uma resposta de sucesso e persistir o resultado no seu sistema.
4

Confirme o evento por último

Depois de processar e persistir tudo o que precisa, envie o par orderId e eventId para POST /v1/events/acknowledgment.Você pode confirmar vários eventos no mesmo array, desde que todos já tenham sido processados com sucesso.
Trate o acknowledgment como o commit final do processamento. Depois da confirmação, o evento deixa de aparecer no polling permanentemente para esta chave de integração. A API não oferece uma listagem de pedidos para reencontrá-lo.Nunca confirme um evento apenas porque ele foi recebido. Se sua integração confirmar e falhar antes de armazenar ou processar o pedido, ela poderá perder esse pedido.Se você também precisa consultar pedidos antigos, veja Histórico de pedidos.
5

Informe que o pedido está pronto

Chame POST /v1/orders/{orderId}/readyForPickup quando o preparo terminar.
6

Despache o pedido

Chame POST /v1/orders/{orderId}/dispatch quando o entregador retirar o pedido.
7

Conclua a entrega

Valide o código de entrega quando necessário. Depois, chame POST /v1/orders/{orderId}/delivered.

​
Cancelamentos

Cancelar

Cancele um pedido que sua loja não pode cumprir.

Aceitar

Aceite um cancelamento solicitado pelo cliente (ORDER_CANCELLATION_REQUEST).

Negar

Negue a solicitação do cliente e mantenha o pedido ativo.

​
Referências rápidas