> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onbeef.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntas frequentes

> Veja as respostas para as dúvidas que os integradores mais mandam: credenciais, limites da API, catálogo, pedidos, entregas e produção.

Cada resposta começa pelo veredito e aponta o guia que detalha.

## Começar e credenciais

> [accordion] Como começo a integrar?
>
> Peça uma loja de teste para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br) e siga o [Início rápido](https://docs.onbeef.app/quickstart.md). 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.

> [accordion] A integração tem custo?
>
> Não. A loja precisa do plano Expert.

> [accordion] Quem gera a chave?
>
> 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.

> [accordion] Atendo uma rede com várias lojas. Uso uma chave só?
>
> 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](https://docs.onbeef.app/authentication/overview.md).

> [accordion] Atendo várias lojas no mesmo servidor. Elas dividem os limites?
>
> 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](https://docs.onbeef.app/api-reference/errors.md#limites).

> [accordion] Existe chave só de leitura ou só de entregas?
>
> Não. Toda chave lê e escreve catálogo e pedidos da loja. Peça uma chave por sistema.

> [accordion] Recebi 401, 404 ou 500 logo no começo. O que confiro primeiro?
>
> O ambiente. Chave, token e pedido de um ambiente não funcionam na URL do outro. Veja [Ambiente trocado](https://docs.onbeef.app/environments/sandbox.md#ambiente-trocado).

> [accordion] A chave funcionava ontem e hoje a API recusa. Por quê?
>
> 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](https://docs.onbeef.app/authentication/overview.md#chave-inativa-ou-apagada).

> [accordion] O ID do Merchant é o client\_id?
>
> 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

> [accordion] Dá para criar pedido pela API?
>
> 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.

> [accordion] Dá para alterar item, peso ou valor de um pedido pela 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](https://docs.onbeef.app/guides/order-import.md).

> [accordion] A integração leva pontos de fidelidade de um sistema para o outro?
>
> 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.

> [accordion] A API controla estoque?
>
> Não. Produto acabou: envie `ITEM_OFFER` com `status: "UNAVAILABLE"`. Voltou: envie `AVAILABLE`.

> [accordion] Dá para enviar vendas do balcão, clientes ou promoção, ou calcular carrinho?
>
> 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.

> [accordion] Cortes, temperos, complementos, horários e kits sincronizam?
>
> Não. Ficam no painel da Onbeef. Os cortes podem ser lidos em `GET /v1/merchant` e no pedido.

> [accordion] A Onbeef avisa o meu sistema quando o lojista muda o catálogo no painel?
>
> 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`.

> [accordion] Existe endpoint que lista os pedidos?
>
> Não. O `id` de cada pedido chega pelos eventos. Para pedidos antigos, veja [Consulte pedidos antigos](https://docs.onbeef.app/concepts/orders-history.md).

## Catálogo

> [accordion] 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](https://docs.onbeef.app/guides/catalog-sync.md).

> [accordion] Enviei o catálogo, recebi 204 e nada apareceu. O que houve?
>
> 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](https://docs.onbeef.app/guides/catalog-sync.md#retornou-204-e-nada-apareceu).

> [accordion] O envio está em PROCESSING há um tempo. Espero ou envio de novo?
>
> Espere até 5 minutos, que é o limite do processamento. Se passar disso em `PROCESSING`, envie de novo.

> [accordion] O GET /v1/merchantStatus diz se a loja está aberta?
>
> Não. Ele mostra o resultado da última sincronização. Loja aberta ou fechada está em `status`, no `GET /v1/merchant`.

> [accordion] A loja já tem produtos na Onbeef. Como evito duplicar?
>
> 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](https://docs.onbeef.app/guides/catalog-linking.md).

> [accordion] A loja reabriu sozinha depois da sincronização. O que envio em merchantStatus?
>
> 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.

> [accordion] Como tiro da Onbeef um produto que saiu do PDV?
>
> Marque como indisponível: `ITEM_OFFER` com `status: "UNAVAILABLE"`. O lojista exclui pelo painel quando quiser. O [envio completo](https://docs.onbeef.app/guides/catalog-sync.md#envio-completo) não é o caminho padrão: ele remove o que tem código do PDV e não veio.

## Pedidos

> [accordion] Uso webhook ou polling?
>
> 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](https://docs.onbeef.app/guides/orders-webhook.md) avisa em tempo real.

> [accordion] Evento que não confirmei some depois de um tempo?
>
> Não. Ele fica na consulta até ser confirmado ou até o pedido mudar de evento. Confirme só depois de gravar.

> [accordion] Chave nova em loja antiga: o polling só traz pedido velho. O que faço?
>
> 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`.

> [accordion] No dia da virada, o pedido agendado não apareceu. Por quê?
>
> 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.

> [accordion] Cadastrei o webhook e nada chega. Por quê?
>
> 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.

> [accordion] Recebo o webhook de várias lojas na mesma URL. Como sei de qual loja é?
>
> 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](https://docs.onbeef.app/guides/orders-webhook.md).

> [accordion] Quando importo o pedido para faturar?
>
> 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](https://docs.onbeef.app/guides/order-import.md).

> [accordion] O displayId é o número do pedido que a loja vê?
>
> 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}`.

> [accordion] O item veio com um UUID no id em vez do código do PDV. Por quê?
>
> 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.

> [accordion] Como sei se o pedido foi pago online ou é para cobrar na entrega?
>
> 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.

> [accordion] O desconto que a loja dá no pedido vem na API?
>
> 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.

> [accordion] Chamei uma ação de status, recebi 202 e o pedido não mudou. Por quê?
>
> 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](https://docs.onbeef.app/api-reference/errors.md#deu-202-ou-204-e-nada-aconteceu).

> [accordion] O mesmo evento chegou duas vezes. É erro?
>
> Não. Mudança feita pela sua integração chega duas vezes por webhook. Identifique pelo par `orderId` + `eventId` e ignore o repetido.

> [accordion] O pedido pago por PIX não apareceu. Por quê?
>
> Porque ainda não foi pago. Pedido com PIX online só aparece depois do pagamento, e PIX vencido nunca aparece.

> [accordion] Filtro o polling por eventType. O limite de 1000 corta os meus eventos?
>
> Não. O filtro `eventType` é aplicado antes do limite de 1000.

> [accordion] Meu sistema só lê pedidos e a loja já tem um PDV integrado. Posso confirmar eventos?
>
> Sim, com uma chave só sua. A confirmação vale só para a chave que confirmou.

> [accordion] Como cancelo um pedido pela API?
>
> Com [`requestCancellation`](https://docs.onbeef.app/api-reference/orders/request-cancellation). 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

> [accordion] Recebo só os pedidos de entrega?
>
> 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](https://docs.onbeef.app/guides/delivery-flow.md).

> [accordion] A loja também tem entregador próprio. Como sei quais entregas são minhas?
>
> A API não diz. Combine a regra com a loja antes de ativar.

> [accordion] A entrega não pôde ser feita. Cancelo o pedido?
>
> Não. Avise a loja: quem decide cancelar é ela. O cancelamento pela API estorna o pagamento online do cliente.

> [accordion] Posso chamar dispatch antes de a loja aceitar o pedido?
>
> 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`.

> [accordion] Dá para enviar a posição do entregador?
>
> 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**.

> [accordion] A loja usa PDV e empresa de entregas ao mesmo tempo. Dá conflito?
>
> 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.

> [accordion] Meu sistema já tem API de logística no padrão Open Delivery. Posso usar?
>
> 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

> [accordion] Tem homologação?
>
> Não. Terminou de testar, a integração já pode ser ativada em lojas. Confira antes o [checklist de produção](https://docs.onbeef.app/environments/production.md#checklist).

> [accordion] Como o meu sistema aparece na tela Integrações?
>
> Envie a logo e um texto curto de como a loja ativa a integração do seu lado para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br).

> [accordion] Quem dá suporte ao lojista sobre a integração?
>
> Você. O integrador orienta o lojista sobre a integração, inclusive o que configurar na Onbeef. A Onbeef orienta sobre a Onbeef.

> [accordion] Recebi 429. O que faço?
>
> Espere os segundos do header `Retry-After` e repita. Veja [Limites](https://docs.onbeef.app/api-reference/errors.md#limites).

> [accordion] Recebi 503. O que faço?
>
> Tente de novo com espera crescente, até 3 vezes.

> [accordion] A API muda sem aviso?
>
> Não. Mudança que pode quebrar integração é avisada antes e entra no [changelog](https://docs.onbeef.app/changelog.md).

Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente

> [card] [Comece aqui](https://docs.onbeef.app/desenvolvedores.md)
>
> O roteiro por tipo de sistema.

> [card] [Erros e limites](https://docs.onbeef.app/api-reference/errors.md)
>
> Mensagens literais, limites por minuto e o que fazer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.