Começar e credenciais
Como começo a integrar?
Como começo a integrar?
id do pedido e o horário da chamada.A integração tem custo?
A integração tem custo?
Quem gera a chave?
Quem gera a chave?
Atendo uma rede com várias lojas. Uso uma chave só?
Atendo uma rede com várias lojas. Uso uma chave só?
Atendo várias lojas no mesmo servidor. Elas dividem os limites?
Atendo várias lojas no mesmo servidor. Elas dividem os limites?
Existe chave só de leitura ou só de entregas?
Existe chave só de leitura ou só de entregas?
Recebi 401, 404 ou 500 logo no começo. O que confiro primeiro?
Recebi 401, 404 ou 500 logo no começo. O que confiro primeiro?
O ID do Merchant é o client_id?
O ID do Merchant é o client_id?
client_id é o ID da janela Credenciais Geradas com Sucesso!. O ID do Merchant, do botão Dados de Integrações, não serve para pedir token.O que a API não faz
Dá para criar pedido pela API?
Dá para criar pedido pela API?
Dá para alterar item, peso ou valor de um pedido pela API?
Dá para alterar item, peso ou valor de um pedido pela API?
A integração leva pontos de fidelidade de um sistema para o outro?
A integração leva pontos de fidelidade de um sistema para o outro?
A API controla estoque?
A API controla estoque?
ITEM_OFFER com status: "UNAVAILABLE". Voltou: envie AVAILABLE.Dá para enviar vendas do balcão, clientes ou promoção, ou calcular carrinho?
Dá para enviar vendas do balcão, clientes ou promoção, ou calcular carrinho?
price.originalValue é ignorado.Cortes, temperos, complementos, horários e kits sincronizam?
Cortes, temperos, complementos, horários e kits sincronizam?
GET /v1/merchant e no pedido.A Onbeef avisa o meu sistema quando o lojista muda o catálogo no painel?
A Onbeef avisa o meu sistema quando o lojista muda o catálogo no painel?
GET /v1/merchant.Existe endpoint que lista os pedidos?
Existe endpoint que lista os pedidos?
id de cada pedido chega pelos eventos. Para pedidos antigos, veja Consulte pedidos antigos.Catálogo
Mudou só o preço de um produto. O que envio?
Mudou só o preço de um produto. O que envio?
ITEM_OFFER, com itemId e price.value. O catálogo online muda logo depois do SUCCESS. A tabela de cada situação está em Sincronize o catálogo.Enviei o catálogo, recebi 204 e nada apareceu. O que houve?
Enviei o catálogo, recebi 204 e nada apareceu. O que houve?
204 só confirma o recebimento: o resultado está em GET /v1/merchantStatus. Causas mais vistas: falta itemOfferId na categoria, id na oferta, name no produto ou price.value na oferta. Veja Retornou 204 e nada apareceu.O envio está em PROCESSING há um tempo. Espero ou envio de novo?
O envio está em PROCESSING há um tempo. Espero ou envio de novo?
PROCESSING, envie de novo.O GET /v1/merchantStatus diz se a loja está aberta?
O GET /v1/merchantStatus diz se a loja está aberta?
status, no GET /v1/merchant.A loja já tem produtos na Onbeef. Como evito duplicar?
A loja já tem produtos na Onbeef. Como evito duplicar?
A loja reabriu sozinha depois da sincronização. O que envio em merchantStatus?
A loja reabriu sozinha depois da sincronização. O que envio em merchantStatus?
MERCHANT e é aplicado na hora: AVAILABLE fixo reabre a loja que o lojista fechou. Antes do envio, leia status em GET /v1/merchant (pode estar até 10 minutos atrasado) e reenvie o mesmo valor.Como tiro da Onbeef um produto que saiu do PDV?
Como tiro da Onbeef um produto que saiu do PDV?
ITEM_OFFER com status: "UNAVAILABLE". O lojista exclui pelo painel quando quiser. O envio completo não é o caminho padrão: ele remove o que tem código do PDV e não veio.Pedidos
Uso webhook ou polling?
Uso webhook ou polling?
start_at, é obrigatório: é ele que garante que nenhum pedido se perde. O webhook avisa em tempo real.Evento que não confirmei some depois de um tempo?
Evento que não confirmei some depois de um tempo?
Chave nova em loja antiga: o polling só traz pedido velho. O que faço?
Chave nova em loja antiga: o polling só traz pedido velho. O que faço?
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. Exemplo: GET /v1/events:polling?start_at=2026-11-13.No dia da virada, o pedido agendado não apareceu. Por quê?
No dia da virada, o pedido agendado não apareceu. Por quê?
start_at filtra pela data de criação, não pela da entrega. No dia da virada, recue o start_at 7 dias e ignore o pedido que já estava entregue antes: em entrega, delivery.deliveryDateTime anterior à data. A retirada não traz a data da entrega: combine com a loja.Cadastrei o webhook e nada chega. Por quê?
Cadastrei o webhook e nada chega. Por quê?
/v1/orderUpdate. Sem essa rota, o seu servidor responde 404 e o aviso não é entregue.Recebo o webhook de várias lojas na mesma URL. Como sei de qual loja é?
Recebo o webhook de várias lojas na mesma URL. Como sei de qual loja é?
X-App-MerchantId, que traz o id devolvido por GET /v1/merchant. Use esse id para escolher a Chave que valida a assinatura. Veja Receba pedidos por webhook.Quando importo o pedido para faturar?
Quando importo o pedido para faturar?
DELIVERED, o único ponto em que o pedido não muda mais. Ajuste de item ou peso não gera evento: quem importa antes fatura com o peso errado. Veja Quando importar o pedido.O displayId é o número do pedido que a loja vê?
O displayId é o número do pedido que a loja vê?
displayId é o código do pedido, como 4F15BA00B. O número curto do painel não vem na API. Guarde o id, que entra em GET /v1/orders/{id}.O item veio com um UUID no id em vez do código do PDV. Por quê?
O item veio com um UUID no id em vez do código do PDV. Por quê?
id do item é um UUID, inclusive em item dentro de kit.Como sei se o pedido foi pago online ou é para cobrar na entrega?
Como sei se o pedido foi pago online ou é para cobrar na entrega?
PREPAID: já está pago, não cobre. PENDING: não está pago (inclui cartão online ainda não concluído), e só se cobra na entrega 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.O desconto que a loja dá no pedido vem na API?
O desconto que a loja dá no pedido vem na API?
discounts e entra em total.discount. Ajustar valor não vem: o pedido sai com a soma dos itens.Chamei uma ação de status, recebi 202 e o pedido não mudou. Por quê?
Chamei uma ação de status, recebi 202 e o pedido não mudou. Por quê?
202 é só o recebimento, e a mudança pode ser recusada depois. Exemplo: dispatch em pedido de retirada não é aplicado. Veja os motivos em Deu 202 ou 204 e nada aconteceu.O mesmo evento chegou duas vezes. É erro?
O mesmo evento chegou duas vezes. É erro?
orderId + eventId e ignore o repetido.O pedido pago por PIX não apareceu. Por quê?
O pedido pago por PIX não apareceu. Por quê?
Filtro o polling por eventType. O limite de 1000 corta os meus eventos?
Filtro o polling por eventType. O limite de 1000 corta os meus eventos?
eventType é aplicado antes do limite de 1000.Meu sistema só lê pedidos e a loja já tem um PDV integrado. Posso confirmar eventos?
Meu sistema só lê pedidos e a loja já tem um PDV integrado. Posso confirmar eventos?
Como cancelo um pedido pela API?
Como cancelo um pedido pela API?
requestCancellation. Ele cancela o pedido e estorna o pagamento online. Não peça o cancelamento de um pedido já entregue: ele não é cancelado, nada é estornado e a resposta 202 não avisa da recusa. Confira lastEvent antes.Entregas
Recebo só os pedidos de entrega?
Recebo só os pedidos de entrega?
type: DELIVERY e confirme os de retirada. O que cobrar na porta e quando chamar o entregador estão em Integre as entregas.A loja também tem entregador próprio. Como sei quais entregas são minhas?
A loja também tem entregador próprio. Como sei quais entregas são minhas?
A entrega não pôde ser feita. Cancelo o pedido?
A entrega não pôde ser feita. Cancelo o pedido?
Posso chamar dispatch antes de a loja aceitar o pedido?
Posso chamar dispatch antes de a loja aceitar o pedido?
dispatch mesmo assim, e o pedido vai para Em rota sem a loja ter aceitado. Chame só depois de READY_FOR_PICKUP, ou no mínimo de CONFIRMED.Dá para enviar a posição do entregador?
Dá para enviar a posição do entregador?
A loja usa PDV e empresa de entregas ao mesmo tempo. Dá conflito?
A loja usa PDV e empresa de entregas ao mesmo tempo. Dá conflito?
Meu sistema já tem API de logística no padrão Open Delivery. Posso usar?
Meu sistema já tem API de logística no padrão Open Delivery. Posso usar?
Produção
Tem homologação?
Tem homologação?
Como o meu sistema aparece na tela Integrações?
Como o meu sistema aparece na tela Integrações?
Quem dá suporte ao lojista sobre a integração?
Quem dá suporte ao lojista sobre a integração?
Recebi 429. O que faço?
Recebi 429. O que faço?
Retry-After e repita. Veja Limites.Recebi 503. O que faço?
Recebi 503. O que faço?
A API muda sem aviso?
A API muda sem aviso?
