Skip to main content
Cada resposta começa pelo veredito e aponta o guia que detalha.

Começar e credenciais

Peça uma loja de teste para rafael@onbeefapp.com.br e siga o Início rápido. Dúvida técnica vai para o mesmo e-mail, com o endpoint, o payload, o id do pedido e o horário da chamada.
Não. A loja precisa do plano Expert.
Depende do ambiente. No ambiente de teste, você gera na loja de teste. Em produção, o lojista gera no painel dele e passa o ID e a Chave para você: a Onbeef não entrega credencial de loja real.
Não. A chave é por loja: rede com 50 lojas tem 50 chaves. O token vale 12 horas e não há refresh token. Veja Autenticação.
Só o de token (30 por minuto). Os limites de leitura e de escrita são por loja. Guarde um token por loja e reaproveite. Veja Limites.
Não. Toda chave lê e escreve catálogo e pedidos da loja. Peça uma chave por sistema.
O ambiente. Chave, token e pedido de um ambiente não funcionam na URL do outro. Veja Ambiente trocado.
A chave está Inativa. A API responde 403 Integration is not active quando o lojista desliga a chave ou a loja sai do plano Expert. Veja Chave inativa ou apagada.
Não. O 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

Não. A Onbeef é a origem do pedido. Pedido de WhatsApp ou telefone é lançado pela loja em Painel de Vendas > Novo pedido e aparece na API.
Não. A API recebe só status e cancelamento. A loja ajusta na Onbeef, em Ajustar o pedido ou bipando a etiqueta da balança. Veja Quando importar o pedido.
Não. O ideal é a loja usar o programa de fidelidade da Onbeef, não um programa de pontos do PDV. A Onbeef calcula os pontos sobre o pedido feito nela, com as regras do programa da loja.
Não. Produto acabou: envie ITEM_OFFER com status: "UNAVAILABLE". Voltou: envie AVAILABLE.
Não. A API não recebe vendas feitas fora da Onbeef nem cadastro de clientes, e não imprime pedido, calcula carrinho ou aplica cupom. Promoção é manual no painel: price.originalValue é ignorado.
Não. Ficam no painel da Onbeef. Os cortes podem ser lidos em GET /v1/merchant e no pedido.
Não. O catálogo é mão única, do seu sistema para a Onbeef. Para ler o que está na loja, use GET /v1/merchant.
Não. O id de cada pedido chega pelos eventos. Para pedidos antigos, veja Consulte pedidos antigos.
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.
O 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.
Espere até 5 minutos, que é o limite do processamento. Se passar disso em PROCESSING, envie de novo.
Não. Ele mostra o resultado da última sincronização. Loja aberta ou fechada está em status, no GET /v1/merchant.
Vincule antes de sincronizar. O vínculo é só pelo Código de integração com PDV, em produto e em categoria. Veja Vincule uma loja que já tem produtos.
O valor que a loja já tem. O campo é obrigatório no 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.
Marque como indisponível: 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

Os dois. O polling, a cada 30 segundos e sempre com start_at, é obrigatório: é ele que garante que nenhum pedido se perde. O webhook avisa em tempo real.
Não. Ele fica na consulta até ser confirmado ou até o pedido mudar de evento. Confirme só depois de gravar.
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. Exemplo: GET /v1/events:polling?start_at=2026-11-13.
Porque 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.
Confira o caminho. Você cadastra a URL base, e a Onbeef acrescenta /v1/orderUpdate. Sem essa rota, o seu servidor responde 404 e o aviso não é entregue.
Pelo header 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.
No evento 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.
Não. O 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}.
Porque o produto não está vinculado. Sem o Código de integração com PDV, o id do item é um UUID, inclusive em item dentro de kit.
A API não separa os dois casos por completo. 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.
Depende de onde ela aplicou. Desconto personalizado vem em discounts e entra em total.discount. Ajustar valor não vem: o pedido sai com a soma dos itens.
Porque o 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.
Não. Mudança feita pela sua integração chega duas vezes por webhook. Identifique pelo par orderId + eventId e ignore o repetido.
Porque ainda não foi pago. Pedido com PIX online só aparece depois do pagamento, e PIX vencido nunca aparece.
Não. O filtro eventType é aplicado antes do limite de 1000.
Sim, com uma chave só sua. A confirmação vale só para a chave que confirmou.
Com 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

Não. Você recebe os eventos de todos os pedidos da loja: trate só type: DELIVERY e confirme os de retirada. O que cobrar na porta e quando chamar o entregador estão em Integre as entregas.
A API não diz. Combine a regra com a loja antes de ativar.
Não. Avise a loja: quem decide cancelar é ela. O cancelamento pela API estorna o pagamento online do cliente.
Não deve. A API aplica o 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.
Não. 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.
Não, se cada sistema tiver a própria chave, com o próprio webhook e a própria confirmação. As duas dividem o limite de requisições da loja.
Depende de desenvolvimento do lado da Onbeef. Nesse modelo é a Onbeef que chama o seu sistema, e isso é combinado caso a caso por e-mail.

Produção

Não. Terminou de testar, a integração já pode ser ativada em lojas. Confira antes o checklist de produção.
Envie a logo e um texto curto de como a loja ativa a integração do seu lado para rafael@onbeefapp.com.br.
Você. O integrador orienta o lojista sobre a integração, inclusive o que configurar na Onbeef. A Onbeef orienta sobre a Onbeef.
Espere os segundos do header Retry-After e repita. Veja Limites.
Tente de novo com espera crescente, até 3 vezes.
Não. Mudança que pode quebrar integração é avisada antes e entra no changelog.

Comece aqui

O roteiro por tipo de sistema.

Erros e limites

Mensagens literais, limites por minuto e o que fazer.