# Agentes de código Source: https://docs.onbeef.app/agent-ready Use o Claude Code, o Cursor, o Codex ou outro agente de código para implementar a integração com a Onbeef Connect API. Um agente de código escreve uma integração melhor quando lê a documentação oficial em vez de adivinhar. A primeira parte desta página mostra como dar esse contexto a ele. A segunda, o [Roteiro para o agente](#roteiro-para-o-agente), é o que ele segue quando você cola o prompt. Se você é um agente de código, vá direto para ela. ## Deixe o agente implementar Integre meu sistema com a Onbeef: [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) Cole o prompt no agente de código que você já usa. Ele lê esta página, pergunta o que o seu sistema faz e implementa a integração com você, testando cada passo no ambiente de teste. Os guias de implementação têm um prompt próprio, já apontando para a página certa: [catálogo](/guides/catalog-sync), [pedidos](/guides/order-flow), [webhook](/guides/orders-webhook) e [entregas](/guides/delivery-flow). ## Tire dúvidas sobre uma página No fim dos guias, das páginas de lojista e das perguntas frequentes há o bloco **Tire suas dúvidas com a IA**. Ele copia uma pergunta pronta, que manda o assistente ler a página e responder só com o que está escrito ali. Cole no Claude, no ChatGPT ou no assistente que você usa. ## Use a documentação como contexto | Arquivo | O que é | | - | - | | [`/llms.txt`](https://docs.onbeef.app/llms.txt) | Índice de todas as páginas, com as regras que mais causam erro de integração no topo. | | [`/llms-full.txt`](https://docs.onbeef.app/llms-full.txt) | A documentação inteira em um único arquivo. | | Página em Markdown | Acrescente `.md` ao endereço de qualquer página, como `https://docs.onbeef.app/guides/order-import.md`. | Peça para o agente ler a documentação antes de escrever código e diga o que o seu sistema faz: ```text theme={null} Leia https://docs.onbeef.app/llms.txt e implemente no meu PDV a importação de pedidos da Onbeef: polling a cada 30 segundos, consulta do pedido no evento DELIVERED e confirmação do evento depois de gravar. ``` > [!WARNING] > > Nunca cole a **Chave** (`client_secret`) no chat de um agente. Guarde as credenciais em variáveis de ambiente. ## Roteiro para o agente Daqui em diante, o texto é para o agente de código. ### Sua tarefa Integre o sistema do usuário com a Onbeef Connect API: REST, JSON em UTF-8, padrão Open Delivery, de uma plataforma de vendas online para açougues. Trabalhe em passos pequenos e teste cada um no ambiente de teste. O que não estiver nesta documentação, diga que não está documentado. ### 1. Pergunte antes de começar Uma pergunta de cada vez: 1. O sistema é PDV ou ERP, empresa de entregas ou só lê (CRM, atendimento)? 2. PDV ou ERP: catálogo, pedidos ou os dois? 3. Pedidos: o PDV precisa do pedido só para faturar, ou antes, para separação? 4. Catálogo: a loja já tem produtos na Onbeef? 5. Onde fica o código e qual é a stack? 6. Já tem loja de teste? Se não, o usuário pede para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br). ### 2. Credenciais e ambientes * Teste: `https://api.dev.connect.onbeefapp.com.br` (painel `https://lojista.dev.onbeefapp.com.br`). * Produção: `https://api.connect.onbeefapp.com.br` (painel `https://lojista.onbeefapp.com.br`). * A chave é gerada no painel da loja, em **Configurações** > **Canais e Integrações** > **Integrações** > **Nova chave API**. O **ID** é o `client_id` e a **Chave** é o `client_secret`. Aparecem uma única vez. * Uma chave por loja. A chave de um ambiente não funciona no outro: causa mais comum de `401`, `404` e `500` no começo. * Credenciais em variáveis de ambiente. Nunca peça a Chave no chat nem grave no código. ### 3. Autenticação (todos os sistemas) 1. `POST /oauth/token` com `grant_type=client_credentials`, `client_id` e `client_secret`, em `application/x-www-form-urlencoded` ou JSON. 2. Reaproveite o `access_token` até perto de `expires_in` (12 horas). Não existe refresh token: peça outro. O limite de 30 pedidos de token por minuto é o único dividido entre as lojas do servidor: guarde um token por loja, inclusive entre reinícios. 3. Envie `Authorization: Bearer ` em toda chamada de `/v1`. Teste com `GET /v1/merchant`. Detalhes: [https://docs.onbeef.app/authentication/overview.md](https://docs.onbeef.app/authentication/overview.md) ### 4. PDV ou ERP: pedidos Leia antes [https://docs.onbeef.app/guides/order-import.md](https://docs.onbeef.app/guides/order-import.md), [https://docs.onbeef.app/guides/order-flow.md](https://docs.onbeef.app/guides/order-flow.md) e [https://docs.onbeef.app/guides/order-data.md](https://docs.onbeef.app/guides/order-data.md) Modelo recomendado: **a loja conduz o pedido no painel da Onbeef e o PDV importa o pedido fechado para faturar.** O PDV só lê. 1. Escolha o gatilho pela pergunta 3: * Só fatura: importe no `DELIVERED`. Filtre com `eventType=DELIVERED&eventType=CANCELLED` e confirme o `CANCELLED` sem faturar. * Precisa antes: aceite `READY_FOR_PICKUP`, `DISPATCHED` ou `DELIVERED`, o que chegar primeiro. Filtre com `eventType=READY_FOR_PICKUP&eventType=DISPATCHED&eventType=DELIVERED&eventType=CANCELLED` e consulte o pedido de novo no `DELIVERED`, antes de faturar. 2. Polling a cada 30 segundos, obrigatório mesmo com webhook, com `start_at`: `GET /v1/events:polling?eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13`. 3. Opcional, para tempo real: webhook ([https://docs.onbeef.app/guides/orders-webhook.md](https://docs.onbeef.app/guides/orders-webhook.md)). Cadastre a URL base com `PUT /v1/merchantOnboarding`: a Onbeef chama `POST {URL base}/v1/orderUpdate`. Com várias lojas na mesma URL, escolha a Chave pelo header `X-App-MerchantId`, o `id` devolvido por `GET /v1/merchant`. 4. Para cada evento do gatilho, consulte `GET /v1/orders/{orderId}`, grave o pedido e só então confirme com `POST /v1/events/acknowledgment`, vários eventos em uma chamada. 5. Ofereça um botão "atualizar pedido da Onbeef", que consulta o pedido de novo. PDV que conduz o status (`confirm`, `readyForPickup`, `dispatch`, `delivered`): siga essa seção do guia `order-flow`. ### 5. PDV ou ERP: catálogo Leia antes [https://docs.onbeef.app/guides/catalog-sync.md](https://docs.onbeef.app/guides/catalog-sync.md) e [https://docs.onbeef.app/guides/catalog-linking.md](https://docs.onbeef.app/guides/catalog-linking.md) 1. Loja que já tem produtos: o lojista preenche o **Código de integração com PDV** em cada produto e categoria antes do primeiro envio. Sem isso o catálogo duplica. 2. Envie `PUT /v1/merchantUpdate` conforme a situação (payload de cada caso no guia): * Preço: `ITEM_OFFER` com `itemId` e `price.value`. Sem `status`, só o preço muda. * Produto acabou, voltou ou saiu de linha: o mesmo `ITEM_OFFER`, com `status` `UNAVAILABLE` ou `AVAILABLE`. * Nome, descrição, foto ou código de balança: `ITEM` com `id` e `name`. * Produto ou categoria nova: `MERCHANT` com `onlyAddProducts: true`. 3. O envio completo (`MERCHANT` sem `onlyAddProducts: true`) não é o caminho padrão: apaga todo produto e categoria com código do PDV que não veio, e produto criado no painel, sem código, fica. Envie `itemOfferId` em toda categoria: sem a chave, nada é removido e o envio termina em `FAIL`. Só quando o PDV é a única fonte do catálogo, e avise o usuário antes. 4. Todo `MERCHANT` leva em `updatedObjects[0].id` o código da loja no PDV, como `"LOJA-01"` (pergunte ao usuário). Ele volta em `merchant.id` de cada pedido. Sem ele, o envio termina em `FAIL`. 5. Todo `MERCHANT` exige `merchantStatus`, aplicado na hora: `AVAILABLE` fixo reabre a loja que o lojista fechou. Leia `status` em `GET /v1/merchant` e reenvie o mesmo valor. A leitura pode estar até 10 minutos atrasada: evite `MERCHANT` logo depois de a loja abrir ou fechar. 6. Uma sincronização por vez, com vários produtos em `updatedObjects`. Consulte `GET /v1/merchantStatus` até sair de `PROCESSING`: só `SUCCESS` é bom (o catálogo online muda em seguida), e em `FAIL` mostre o `moreInfo`. Passou de 5 minutos em `PROCESSING`: envie de novo. ### 6. Empresa de entregas Leia antes [https://docs.onbeef.app/guides/delivery-flow.md](https://docs.onbeef.app/guides/delivery-flow.md) 1. Autenticação, polling com `start_at` e confirmação como na seção 4. Sem `start_at`, um pedido antigo parado em **Pronto** aciona um entregador. 2. Chegam os eventos de todos os pedidos da loja: trate só `type: DELIVERY` e confirme os de retirada sem processar. 3. Chame o entregador no `CONFIRMED` ou no `READY_FOR_PICKUP`. Pedido agendado: use a janela em `schedule`. 4. Antes de o entregador sair, consulte o pedido de novo (peso e valor a cobrar mudam sem evento) e aplique a regra de pagamento da seção 7. 5. Chame `dispatch` na saída, só depois do `READY_FOR_PICKUP` ou no mínimo do `CONFIRMED`, e `delivered` na entrega. Não chame `confirm` nem `readyForPickup`. 6. No `CANCELLED`, dispense o entregador. Entrega que não pôde ser feita: avise a loja e não chame `requestCancellation`, que estorna o cliente. 7. A API não diz quais entregas são da empresa quando a loja tem entregador próprio (combine com a loja) e não recebe nome do entregador, posição nem previsão. ### 7. Regras que não podem falhar * **Erro.** Sempre `{ "title": "...", "status": 400 }`. Decida pelo `status`. Validação é `400`. `401`: peça outro token e repita uma vez; se falhar, pare. `403`: pare e avise o usuário. `503`: tente de novo com espera crescente, até 3 vezes. * **Limites por minuto.** Leitura 200 e escrita 60, por loja, somando as chaves dela. `429`: guarde a chamada e repita depois de `Retry-After`. * **`202` e `204` só confirmam o recebimento.** No catálogo, o resultado está em `GET /v1/merchantStatus`. No pedido, a mudança vale quando chega o evento novo: sem ele em cerca de 70 segundos, não foi aplicada, e nenhum erro é enviado. * **O polling é uma foto, não uma fila.** Um evento por pedido, o mais recente, até 1000 pedidos, dos mais antigos para os mais novos. O `eventType` é aplicado antes desse limite. Evento não confirmado não expira: fica na consulta até ser confirmado ou até o pedido mudar de evento. * **`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. O filtro é pela criação: no dia da virada, recue o `start_at` 7 dias e ignore o pedido já entregue antes (em entrega, `delivery.deliveryDateTime` anterior à data; a retirada não traz a data da entrega: combine com a loja). * **Eventos.** `CREATED`, `CONFIRMED`, `READY_FOR_PICKUP`, `DISPATCHED` (só entrega), `DELIVERED`, `CANCELLED`, `CANCELLATION_REQUESTED` e `CANCELLATION_REQUEST_DENIED` (só por webhook, sem confirmação: a Onbeef não conseguiu cancelar). 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. * **`eventId` identifica o tipo do evento.** Deduplique pelo par `orderId` + `eventId`: o mesmo evento chega mais de uma vez, inclusive duas pelo webhook quando a mudança partiu da sua integração. A confirmação é um array de `{ "id": , "orderId", "eventType" }`. * **Editar o pedido não gera evento.** A loja ajusta peso e itens depois de criado, só no painel da Onbeef. Não fature no `CREATED`. * **Não existe endpoint** para criar, listar ou alterar pedidos, nem para enviar clientes, estoque ou pontos de fidelidade. * **Desconto da loja.** **Desconto personalizado** vem em `discounts` e entra em `total.discount`. **Ajustar valor** não vem: o total sai com a soma dos itens. * **Pagamento.** `PREPAID`: já está pago, não cobre. `PENDING`: não está pago, e inclui cartão online ainda não concluído. Cobre na entrega só se `method` for `CASH`, `PIX`, `CREDIT`, `DEBIT`, `FOOD_VOUCHER` ou `MEAL_VOUCHER` e a loja confirmar que o pedido é para pagar na entrega. `OTHER` (fiado, link de pagamento, boleto) nunca se cobra na porta. * **Pedido agendado.** `orderTiming: "SCHEDULED"` e janela em `schedule`; em retirada, `takeout.takeoutDateTime`. * **`id` do item é o código do PDV**, no catálogo e no pedido. `externalCode` é o código de balança. `id` em UUID no pedido: produto não vinculado. * **`unit` aceita só `"KG"` ou `"UN"`, em maiúsculas.** Com `KG`, o preço é por quilo e a quantidade vem em quilos. * **Datas em ISO 8601 UTC. Dinheiro em reais com duas casas:** `{ "value": 78.84, "currency": "BRL" }`. * **Assinatura do webhook.** `X-App-Signature` é o HMAC-SHA256 hexadecimal do corpo cru com o `client_secret`. Calcule antes de desserializar e compare em tempo constante. ### 8. Antes de dizer que terminou * Rode no ambiente de teste e mostre o resultado ao usuário. Pedidos de teste: **Painel de Vendas** > **Novo pedido** ou o catálogo online da loja de teste. * Pedidos: entrega, retirada, item por quilo ajustado depois e cancelamento. Entregas: também um pedido agendado. Catálogo: preço, produto indisponível e produto novo, com `SUCCESS` em cada um. * Passe pelo checklist de [https://docs.onbeef.app/environments/production.md](https://docs.onbeef.app/environments/production.md) * Não há homologação. Para aparecer na tela **Integrações**, o usuário envia a logo e um texto curto de como a loja ativa a integração. ### Referência * Índice: [https://docs.onbeef.app/llms.txt](https://docs.onbeef.app/llms.txt) * Tudo em um arquivo: [https://docs.onbeef.app/llms-full.txt](https://docs.onbeef.app/llms-full.txt) * Erros e limites: [https://docs.onbeef.app/api-reference/errors.md](https://docs.onbeef.app/api-reference/errors.md) # Obtenha um token de acesso Source: https://docs.onbeef.app/api-reference/auth/token POST /oauth/token Troque o ID e a Chave da loja por um token OAuth 2.0 válido por 12 horas. Troca o **ID** e a **Chave** de uma chave da loja por um token de acesso. Envie o token no header `Authorization: Bearer ` das outras chamadas. > [card] [Entenda o fluxo](/authentication/overview) > > Como a chave nasce, as regras do token e o que fazer com 401 e 403. ## Corpo da requisição O endpoint aceita `application/x-www-form-urlencoded`, o formato do padrão Open Delivery, e `application/json`. Os campos são os mesmos nos dois. **grant_type** `string` *required* Envie sempre `client_credentials`. **client_id** `string` *required* O valor **ID** que o painel mostra ao criar a chave. Não é o **ID do Merchant** do botão **Dados de Integrações**. **client_secret** `string` *required* O valor **Chave** que o painel mostra ao criar a chave. Guarde só no servidor. ## Resposta **token_type** `string` Sempre `Bearer`. **expires_in** `integer` Validade do token em segundos. O token vale 12 horas: o valor vem `43200` ou `43199`. Use o valor recebido. **access_token** `string` O token. Envie em `Authorization: Bearer `. ### Regras * **Reaproveite o token.** Guarde o token no servidor e use até perto do fim da validade. * **Não há refresh token.** Venceu, peça outro com a mesma chave. * **Limite de 30 pedidos de token por minuto.** Um servidor que atende várias lojas divide esse limite entre todas. Guarde o token de cada loja entre reinícios do servidor. ## Exemplos ```bash Formulário theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=" \ -d "client_secret=" ``` ```bash JSON theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "", "client_secret": "" }' ``` ```json 200 theme={null} { "token_type": "Bearer", "expires_in": 43200, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." } ``` ```json 401 theme={null} { "title": "The client credentials were incorrect.", "status": 401 } ``` ```json 403 theme={null} { "title": "Integration is not active", "status": 403 } ``` ```json 429 theme={null} { "title": "Too Many Requests", "status": 429 } ``` Os exemplos usam o ambiente de teste. Em produção, troque a URL base por `https://api.connect.onbeefapp.com.br` e use a chave gerada pelo lojista. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `401` | `The client credentials were incorrect.` | **ID** ou **Chave** errados, chave apagada no painel, chave de outro ambiente, `grant_type` ausente ou diferente de `client_credentials`, ou corpo vazio. Todos esses casos respondem a mesma mensagem. | Confira os três campos e a URL base. | | `403` | `Integration is not active` | A chave está **Inativa**: o lojista desligou, ou a loja saiu do plano Expert. | Peça ao lojista para ativar a chave. Não gere outra. | | `403` | `Integration not allowed` | A chave não tem vínculo válido com a loja. | Peça à loja para gerar outra chave. | | `429` | `Too Many Requests` | Mais de 30 pedidos de token em um minuto. | Espere os segundos do header `Retry-After` e reaproveite o token. | | `500` | `Internal Server Error` | Erro interno. No começo da integração, confira primeiro se a chave é do mesmo ambiente da URL. | Confira o ambiente e tente de novo. Se continuar, escreva para a Onbeef. | Os demais códigos estão em [Erros e limites](/api-reference/errors). # Erros e limites Source: https://docs.onbeef.app/api-reference/errors Veja a mensagem literal de cada erro, o motivo e o que fazer. Inclui os limites por minuto e o caso do 202 ou 204 sem efeito. Todo erro responde no mesmo formato, com a mensagem em inglês. ## Formato ```json theme={null} { "title": "Order not found", "status": 404 } ``` * **Decida pelo `status`, não pelo texto.** Em `401`, peça outro token e repita uma vez. Se o pedido de token também falhar, ou em `403`, pare e avise o lojista. * **Validação é `400`.** Não existe `422`. O `title` traz a primeira regra que falhou. ## Erros por status | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | A regra de validação que falhou, como `The ordersWebhookURL field is required.` | Campo ausente ou inválido. | Corrija o campo. Não repita a mesma chamada. | | `400` | `Order has already same event type` | Pedido já cancelado. | Não reenvie. | | `401` | `The client credentials were incorrect.` | No pedido de token: **ID** ou **Chave** errados, chave apagada ou de outro ambiente, ou `grant_type` errado. | Confira os valores e a URL base. | | `401` | `Token not provided` | Faltou o header `Authorization: Bearer `. | Envie o header. | | `401` | `Invalid token`, `Invalid token format`, `Token validation failed` ou `Token has expired` | O token não é deste ambiente, ou passou das 12 horas. | Peça outro token no mesmo ambiente e repita uma vez. | | `401` ou `403` | `Client not found` (`401`) ou `Integration not allowed` (`403`) | A chave foi apagada, ou não tem vínculo válido com a loja. | A loja gera outra chave. | | `403` | `Integration is not active` | A chave está **Inativa**: o lojista desligou, ou a loja saiu do plano Expert. | Avise o lojista: a mesma chave volta quando ele ativar. Não repita em laço. | | `404` | `Order not found` ou `Route not found` | O pedido não existe, é de outra loja ou de outro ambiente. Ou o caminho não existe. | Confira o `id`, a URL base e o prefixo `/v1/`. | | `405` | `The POST method is not supported for route v1/merchantUpdate. Supported methods: PUT.` | Método errado. | Use `PUT` em `merchantUpdate` e `merchantOnboarding`. | | `429` | `Too Many Requests` | Passou do [limite](#limites) por minuto. | Espere os segundos de `Retry-After`. | | `500` | `Internal Server Error` | Erro interno. Já apareceu com chave de produção na URL de teste. | Confira o ambiente e tente de novo em 1, 2 e 4 segundos. | | `503` | Varia. | Falha temporária. | Tente de novo com espera crescente, até 3 vezes. | [Ambiente trocado](/environments/sandbox#ambiente-trocado) é a causa número 1 de `401`, `404` e `500` no começo: chave, token e pedido de um ambiente não existem no outro. ## Limites Por minuto: * **Token: 30,** em `POST /oauth/token`. É o único compartilhado entre lojas: um servidor com várias lojas divide os 30 entre todas. Guarde um token por loja, inclusive entre reinícios, e reaproveite. * **Leitura: 200 por loja,** em `GET /v1/merchant`, `GET /v1/merchantStatus`, `GET /v1/events:polling` e `GET /v1/orders/{id}`. * **Escrita: 60 por loja,** em `PUT /v1/merchantUpdate`, `PUT /v1/merchantOnboarding`, `POST /v1/events/acknowledgment` e todas as ações de pedido. * **Leitura e escrita são da loja, não da chave.** PDV e empresa de entregas dividem os mesmos 200 e 60: envie em lote. ```http theme={null} HTTP/1.1 429 Too Many Requests Retry-After: 37 X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1794496860 {"title":"Too Many Requests","status":429} ``` Vale também em `dispatch` e `delivered`: guarde a chamada e envie depois. ## Deu 202 ou 204 e nada aconteceu `202` e `204` dizem só que a API recebeu a chamada. O erro de regra não volta em nenhum aviso. ### Catálogo: 204 em `PUT /v1/merchantUpdate` O resultado está em [`GET /v1/merchantStatus`](/api-reference/merchant/get-status): consulte até sair de `PROCESSING`. Se passar de 5 minutos em `PROCESSING`, envie de novo. ```json theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "FAIL", "moreInfo": "Itens não encontrados: 1001, 1002" } ``` `FAIL` com `Without Data`: a loja nunca recebeu uma sincronização. As causas de `204` sem produto no catálogo estão em [Retornou 204 e nada apareceu](/guides/catalog-sync#retornou-204-e-nada-apareceu). ### Pedido: 202 em `confirm`, `readyForPickup`, `dispatch` ou `delivered` A confirmação é o evento novo do pedido. Se ele não chegar em cerca de 70 segundos, a mudança não foi aplicada. Motivos: * **`dispatch` em pedido de retirada.** Use `readyForPickup` e depois `delivered`. * **Pedido já entregue, cancelado ou já nesse status.** Nenhum evento novo é gerado. * **Status anterior ao atual.** Dá para pular etapa para frente, não para voltar. * **Peso não confirmado.** Pedido pago online com item por peso exige que a loja confirme o peso no painel. Vale para `dispatch` e `delivered` em entrega, e para `readyForPickup` e `delivered` em retirada. * **Validação de segurança do pagamento pendente,** em cartão online. Vale para as mesmas ações do peso. Consulte `GET /v1/orders/{id}`, leia `lastEvent` (o evento atual), corrija a causa e chame de novo: depois desses 70 segundos, a Onbeef não tenta mais. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Autenticação](/authentication/overview) > > Chave e token. > [card] [Perguntas frequentes](/desenvolvedores/faq) > > As dúvidas mais comuns. # Confirme o código de entrega Source: https://docs.onbeef.app/api-reference/logistics/delivery-confirmation-code POST /v1/logistics/confirmationCode Confere um código de entrega para operador de logística cadastrado pela Onbeef. Hoje a resposta é sempre 400. Compara o código enviado com o código de entrega do pedido. Hoje este endpoint responde sempre `400` `Invalid code provided`: os pedidos da Onbeef não têm código de entrega, então nenhum código confere. Ele só atende operador de logística cadastrado pela Onbeef, e a chave gerada pela loja não vale aqui. Empresa de entregas integra pela API de pedidos e confirma a entrega com [Marcar como entregue](/api-reference/orders/delivered): siga [Integre as entregas](/guides/delivery-flow). ## Autenticação Os mesmos três headers de [Enviar evento de entrega](/api-reference/logistics/order-event-notification): `X-App-Id`, `X-App-MerchantId` e `X-App-Signature`. ## Corpo da requisição **orderId** `string (uuid)` *required* O pedido na Onbeef. **deliveryCode** `string` *required* O código informado pelo cliente. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/logistics/confirmationCode" \ --header "X-App-Id: " \ --header "X-App-MerchantId: " \ --header "X-App-Signature: " \ --header "Content-Type: application/json" \ --data '{ "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "deliveryCode": "1234" }' ``` ## Resposta ```json 400 theme={null} { "title": "Invalid code provided", "status": 400 } ``` A chamada não muda o status do pedido e não gera evento. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `Invalid code provided` | O pedido não tem código de entrega. | Não chame. Confirme a entrega com [Marcar como entregue](/api-reference/orders/delivered). | | `400` | `Missing required header: X-App-Id` | Faltou um dos três headers, como em chamada feita só com o Bearer token. | Use a API de pedidos: [Integre as entregas](/guides/delivery-flow). | | `401` | `Invalid X-App-Id` | O operador não está cadastrado na Onbeef. | Use a API de pedidos. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId`. | | `429` | `Too Many Requests` | Passou de 120 chamadas por minuto no mesmo IP. | Espere o tempo do header `Retry-After`. | # Envie um evento de entrega Source: https://docs.onbeef.app/api-reference/logistics/order-event-notification POST /v1/logistics/deliveryUpdate Evento de entrega enviado por operador de logística cadastrado pela Onbeef. Não funciona com a chave da loja. Recebe um evento de entrega de um operador de logística. Hoje este endpoint só serve a operador de logística cadastrado pela Onbeef. A chave gerada pela loja e o Bearer token não valem aqui. Empresa de entregas integra pela API de pedidos: siga [Integre as entregas](/guides/delivery-flow). ## Autenticação **X-App-Id** `string` *required* Identificador do operador, cadastrado pela Onbeef. **X-App-MerchantId** `string` *required* Identificador da loja, de 36 a 100 caracteres. **X-App-Signature** `string` *required* HMAC-SHA256 do corpo exato da requisição, em hexadecimal (64 caracteres), com o segredo cadastrado para a loja. ## Corpo da requisição **orderId** `string (uuid)` *required* O pedido na Onbeef. **deliveryId** `string` *required* O identificador da entrega no sistema do operador. **event** `object` *required* `type` e `datetime` (ISO 8601) são obrigatórios. `message` é opcional. Só dois valores de `event.type` têm efeito no pedido: | `event.type` | Efeito | | - | - | | `DELIVERY_ONGOING` | O pedido passa para **Em rota**. | | `DELIVERY_FINISHED` | O pedido passa para **Entregue**. | Qualquer outro tipo, e os demais campos do padrão Open Delivery (entregador, veículo, previsão), são guardados e não aparecem para a loja nem para o cliente. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/logistics/deliveryUpdate" \ --header "X-App-Id: " \ --header "X-App-MerchantId: " \ --header "X-App-Signature: " \ --header "Content-Type: application/json" \ --data '{ "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "deliveryId": "ENT-123", "event": { "type": "DELIVERY_ONGOING", "datetime": "2026-11-16T14:30:00Z" } }' ``` ## Resposta `204`, sem corpo. A mudança de status é aplicada em seguida. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `Missing required header: X-App-Id` | Faltou um dos três headers (chamada só com Bearer token). | Use a API de pedidos: [Integre as entregas](/guides/delivery-flow). | | `401` | `Invalid X-App-Id` | O operador não está cadastrado na Onbeef. | Use a API de pedidos. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId`. | | `429` | `Too Many Requests` | Mais de 120 chamadas por minuto no mesmo IP. | Espere o `Retry-After`. | # Consulte a loja e o catálogo Source: https://docs.onbeef.app/api-reference/merchant/get-merchant GET /v1/merchant Leia o status da loja, as categorias e os produtos, com o código do PDV de cada um. Use para conferir o vínculo e o resultado de um envio. Devolve a loja da chave usada no token: se está aberta, as categorias e os produtos. É a única leitura de catálogo da API. > [card] [Entenda o catálogo](/concepts/merchant) > > O que é loja, categoria, produto e oferta, e qual código liga o seu PDV à Onbeef. ## Requisição Sem parâmetros. ```bash Ambiente de teste theme={null} curl --url https://api.dev.connect.onbeefapp.com.br/v1/merchant \ --header 'Authorization: Bearer ' ``` ## Resposta **id** `string` Identificador da loja na Onbeef (UUID). Não é o código da loja no seu PDV. **status** `string` `AVAILABLE` (loja aberta para pedidos) ou `UNAVAILABLE` (loja fechada). Não considera o horário de funcionamento. É o valor que você reenvia em `merchantStatus` no envio `MERCHANT`. **lastUpdate** `string` Data da última alteração no cadastro da loja, em ISO 8601 UTC. Não muda quando o lojista edita um produto. **TTL** `integer` Por quantos segundos a Onbeef guarda esta resposta. Hoje, `600`. **categories** `array` Categorias da loja, na ordem do catálogo. **Campos da categoria** **id** `string` Identificador da categoria na Onbeef (UUID). **pdv_external_id** `string | null` **Código de integração com PDV** da categoria. É o valor que você envia em `categories[].id`. Vem `null` em categoria sem vínculo. **name** `string` Nome da categoria. **index** `integer` Posição da categoria no catálogo. **status** `string` `AVAILABLE` ou `UNAVAILABLE`. **productsId** `array of strings` `id` (UUID) de cada produto da categoria. **products** `array` Produtos que estão em pelo menos uma categoria. Os desativados também aparecem. **Campos do produto** **id** `string` Identificador do produto na Onbeef (UUID). Não é aceito como `itemId` no envio de catálogo. **pdv_external_id** `string | null` **Código de integração com PDV** do produto. É o valor que você envia em `items[].id` e `itemId`. Vem `null` em produto sem vínculo. **name** `string` Nome do produto, como está no painel. Reenvie este valor em `name` no envio `ITEM` para não trocar o nome que o lojista escreveu. **description** `string | null` Descrição do produto. **externalCode** `string | null` **Código da balança** do produto. Não é o código do PDV. **status** `string` `AVAILABLE` ou `UNAVAILABLE`. **unit** `string` `KG` (vendido por peso) ou `UN` (vendido por unidade). É o tipo que vale: o `unit` do envio não muda um produto que já existe. **price** `number | null` Preço em reais. Com `unit: "KG"`, é o preço do quilo. **serving** `integer | null` Quantas pessoas o produto serve. **media** `array of strings` URLs das fotos do produto. **index** `integer | null` Posição do produto no catálogo. **cuts** `array` Cortes do produto. O campo só aparece quando o produto tem corte. * `id`: identificador do corte. É o mesmo que vem no pedido, em `items[].options[]`. * `name`: nome do corte, como "Peça" ou "Bife". * `spice`: tempero do corte (`id` e `name`), ou `null`. A resposta traz outros campos além destes. Eles não têm uso na integração: ignore. ### Regras * **Só produto em categoria.** Produto sem categoria não aparece em `products`. * **Um envio de catálogo atualiza a resposta.** Quando o envio termina, a próxima consulta já mostra o resultado. * **Mudança feita no painel demora.** O que o lojista edita no painel leva até 600 segundos (o `TTL`) para aparecer aqui. Vale também para o `status` da loja e para o código do PDV que o lojista acabou de preencher. * **Não há aviso de mudança.** A Onbeef não notifica o PDV quando o catálogo muda no painel. Esta consulta é a única leitura. * **Cortes só se leem.** Eles não entram no envio de catálogo. Guarde o `id` do corte para reconhecer o corte no pedido. ## Exemplo ```json theme={null} { "lastUpdate": "2026-11-12T14:03:11.000000Z", "TTL": 600, "id": "0b8f6c1e-2d4a-4c57-9a55-6f1f0e2f7a10", "status": "AVAILABLE", "categories": [ { "id": "bdfbb2f3-af2a-4ad7-8714-f3c75531e78f", "pdv_external_id": "15", "name": "Bovinos", "index": 0, "status": "AVAILABLE", "productsId": ["1db3abc1-d295-4873-be31-ef64050a31f7"] }, { "id": "82532a6d-c6d4-44c7-ab32-a8eca9bb29ca", "pdv_external_id": null, "name": "Churrasco", "index": 1, "status": "AVAILABLE", "productsId": ["e74dd75f-2a7c-416a-997d-02bab6adc10b"] } ], "products": [ { "id": "1db3abc1-d295-4873-be31-ef64050a31f7", "pdv_external_id": "1001", "name": "Picanha", "externalCode": "000123", "description": "Peça resfriada, vendida por peso", "status": "AVAILABLE", "serving": 4, "unit": "KG", "media": ["https://pdv.example.com/fotos/1001.jpg"], "index": 0, "price": 94.9, "cuts": [ { "id": "6f1c2f0e-58a3-4d0a-9f4e-2f6f0c1f7a11", "name": "Peça", "spice": null }, { "id": "0b7d4c7a-93b1-4c53-8a55-7d2c5e0e4b20", "name": "Bife", "spice": { "id": "c3a1f9d2-4e6b-4f0a-b7a8-91d0e5c2a6f3", "name": "Alho" } } ] }, { "id": "e74dd75f-2a7c-416a-997d-02bab6adc10b", "pdv_external_id": null, "name": "Costela", "externalCode": null, "description": null, "status": "UNAVAILABLE", "serving": null, "unit": "KG", "media": [], "index": 0, "price": 39.9, "cuts": [ { "id": "6f1c2f0e-58a3-4d0a-9f4e-2f6f0c1f7a11", "name": "Peça", "spice": null } ] } ] } ``` O exemplo mostra só os campos documentados. O corte "Bife" (`0b7d4c7a-93b1-4c53-8a55-7d2c5e0e4b20`) é o mesmo `id` que chega no pedido, em `items[].options[]`. "Bovinos" e "Picanha" estão vinculados ao PDV. "Churrasco" e "Costela" foram criados no painel e ainda não têm código: veja [Loja que já tem produtos](/guides/catalog-linking). ## Erros | HTTP | Mensagem (`title`) | Motivo | O que fazer | | - | - | - | - | | `401` | `Token has expired` | O token passou de 12 horas. | Peça outro em `POST /oauth/token`. | | `403` | `Integration is not active` | A chave está **Inativa** no painel. | O lojista reativa a chave. Não precisa gerar outra. | | `429` | `Too Many Requests` | Mais de 200 leituras por minuto na loja. | Espere o tempo do cabeçalho `Retry-After`. | A lista completa está em [Erros](/api-reference/errors). # Consulte o resultado do envio Source: https://docs.onbeef.app/api-reference/merchant/get-status GET /v1/merchantStatus Veja se o último envio de catálogo terminou: PROCESSING, SUCCESS ou FAIL, com o motivo em moreInfo. Devolve o resultado do último `PUT /v1/merchantUpdate` da loja. Não é o status da loja: se ela está aberta ou fechada, quem diz é o `status` de [`GET /v1/merchant`](/api-reference/merchant/get-merchant). > [card] [Entenda o fluxo](/guides/catalog-sync) > > Como enviar o catálogo e o que conferir quando retorna 204 e nada aparece. ## Requisição Sem parâmetros. A loja é a da chave usada no token. ```bash Ambiente de teste theme={null} curl --url https://api.dev.connect.onbeefapp.com.br/v1/merchantStatus \ --header 'Authorization: Bearer ' ``` ## Resposta **status** `string` * `PROCESSING`: o envio foi recebido e ainda não terminou. * `SUCCESS`: tudo foi gravado, nada foi descartado. O catálogo online é atualizado em seguida. * `FAIL`: falhou ou gravou só uma parte. O `moreInfo` diz o quê. **lastRead** `string` Data e hora da última mudança de status, em ISO 8601 UTC. Não é a hora da sua consulta: muda quando um envio é recebido e quando ele termina. **moreInfo** `string | null` Texto em português com o que foi descartado. Vem `null` em `PROCESSING` e em `SUCCESS`. ```json SUCCESS theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "SUCCESS", "moreInfo": null } ``` ```json FAIL parcial theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "FAIL", "moreInfo": "1 de 2 ofertas atualizadas. Itens não encontrados: 1002. Verifique os dados enviados com o suporte do seu sistema PDV." } ``` ```json FAIL no MERCHANT theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "FAIL", "moreInfo": "1 de 1 categorias e 2 de 3 produtos atualizados. 1 produto recebido com dados incompletos foi descartado. Nenhum item foi removido do cardápio nesta atualização por segurança. Verifique os dados enviados com o suporte do seu sistema PDV." } ``` ```json Antes do primeiro envio theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "FAIL", "moreInfo": "Without Data" } ``` ### Regras * **Um resultado por loja.** Cada envio substitui o resultado do anterior. Não há histórico nem id de envio. * **O `204` já troca o resultado.** Quando ele chega, o status é `PROCESSING`, ou `FAIL` se o envio inteiro foi recusado: o que você lê depois é do seu envio, não do anterior. * **Uma sincronização por vez.** Envie a próxima só depois de sair de `PROCESSING`: com dois envios seguidos, o resultado pode ser o de qualquer um. O processamento tem limite de 5 minutos: se passar disso em `PROCESSING`, envie de novo. * **`FAIL` pode ser parcial.** O `moreInfo` começa com a contagem, como "8 de 10 ofertas atualizadas". O que foi encontrado já está gravado: corrija e reenvie só o que faltou. * **Consulte a cada 5 segundos.** * **O lojista vê o mesmo texto.** O `moreInfo` aparece no painel, no cartão **Status da Integração PDV**: **Ativo** (`SUCCESS`), **Pendente** (`PROCESSING`) ou **Erro** (`FAIL`). ## Mensagens do `moreInfo` | Mensagem | Envio | Motivo | O que fazer | | - | - | - | - | | "Without Data" | Qualquer | A loja nunca recebeu um `merchantUpdate`. | Faça o primeiro envio. Se já fez, confira a URL, o ambiente e a chave. | | "Itens não encontrados: 1001, 1002" | `ITEM`, `ITEM_OFFER` | Nenhum produto da loja tem esse **Código de integração com PDV**. A lista mostra até 10 códigos e termina com "e mais N". | Vincule o produto no painel ou crie com `MERCHANT`. Para achar todos, compare com `pdv_external_id` em `GET /v1/merchant`. Veja [Loja que já tem produtos](/guides/catalog-linking). | | "... ofertas recebidas sem itemId ou price.value foram descartadas" | `ITEM_OFFER` | Parte dos objetos veio sem `itemId` ou sem `price.value`. | Envie os dois campos em todos os objetos. | | "Nenhuma oferta recebida é válida: todas estão sem itemId ou price.value." | `ITEM_OFFER` | Todos os objetos vieram incompletos. Nada foi gravado. | Envie `itemId` e `price.value`. O preço fica dentro de `price`. | | "... itens recebidos sem id ou name foram descartados" | `ITEM` | Parte dos objetos veio sem `id` ou sem `name`. | Envie os dois campos em todos os objetos. | | "Nenhum item recebido é válido: todos estão sem id ou name." | `ITEM` | Todos os objetos vieram incompletos. Nada foi gravado. | Envie `id` e `name`. | | "O cadastro recebido do PDV está sem o id da loja." | `MERCHANT` | Faltou `updatedObjects[0].id`. Nada foi gravado. | Envie o código da loja no seu PDV. | | "... categorias recebidas sem id ou name foram descartadas" | `MERCHANT` | Parte das categorias veio sem `id` ou sem `name`. | Envie os dois campos em todas as categorias. | | "Nenhuma categoria recebida é válida: todas estão sem id ou name." | `MERCHANT` | Todas as categorias vieram incompletas. Nada foi gravado. | Envie `id` e `name` em todas as categorias. | | "... produtos recebidos com dados incompletos foram descartados" | `MERCHANT` | A ligação não fechou: oferta sem `id`, `itemId` sem produto igual em `items`, produto sem `name` ou oferta sem `price.value`. | Confira `itemOfferId` → `itemOffers[].id` → `itemId` → `items[].id`. | | "... categorias recebidas sem a lista de produtos (itemOfferId) tiveram os produtos mantidos como estavam" | `MERCHANT` | Alguma categoria veio sem a chave `itemOfferId`. Os produtos dela ficam como estão. | Envie `itemOfferId` em todas as categorias. Para esvaziar uma no envio completo, envie `[]`. | | "Nenhum item foi removido do cardápio nesta atualização por segurança" | `MERCHANT` completo | Algum objeto foi descartado, ou alguma categoria veio sem `itemOfferId`, então a remoção não rodou. | Corrija o que a mensagem aponta e envie de novo. | | "Kits de preço aberto não recebem preço do PDV: 40" | `MERCHANT`, `ITEM_OFFER` | O produto com esse código é um kit de preço aberto no painel. | O lojista muda o kit para preço fechado ou tira o código do PDV dele. | | "Entre em contato com o suporte" | Qualquer | Erro inesperado ao processar. | Escreva para a Onbeef com o payload e o horário do envio, antes de reenviar. | ## Erros | HTTP | Mensagem (`title`) | Motivo | O que fazer | | - | - | - | - | | `401` | `Token has expired` | O token passou de 12 horas. | Peça outro em `POST /oauth/token`. | | `403` | `Integration is not active` | A chave está **Inativa** no painel. | O lojista reativa a chave. Não precisa gerar outra. | | `429` | `Too Many Requests` | Mais de 200 leituras por minuto na loja. | Espere o tempo do cabeçalho `Retry-After`. | A lista completa está em [Erros](/api-reference/errors). # Envie o catálogo Source: https://docs.onbeef.app/api-reference/merchant/sync-catalog PUT /v1/merchantUpdate Crie e atualize categorias, produtos, preços e disponibilidade, e abra ou feche a loja. A resposta é 204 e o resultado sai em GET /v1/merchantStatus. Envia mudanças de catálogo do PDV para a Onbeef. Responde `204` sem corpo e processa depois: o resultado fica em [`GET /v1/merchantStatus`](/api-reference/merchant/get-status). > [card] [Entenda o fluxo](/guides/catalog-sync) > > O que enviar em cada situação, envio em lote, envio completo e o que conferir quando nada aparece. ## Corpo da requisição Envie `application/json` em UTF-8. **entityType** `string` *required* O tipo do envio. Define o formato de `updatedObjects`. * `MERCHANT`: categorias, produtos e ofertas juntos. É o único que cria e remove. * `ITEM`: cadastro de produtos que já existem (nome, descrição, foto). * `ITEM_OFFER`: preço e disponibilidade de produtos que já existem. **merchantStatus** `string` Obrigatório com `MERCHANT`. `AVAILABLE` abre a loja para pedidos e `UNAVAILABLE` fecha. O valor é aplicado na hora, antes do resto do envio: `AVAILABLE` fixo reabre a loja que o lojista fechou no painel. Antes de um envio `MERCHANT`, leia `status` em `GET /v1/merchant` e reenvie o mesmo valor. A leitura pode estar até 10 minutos atrasada: evite envios `MERCHANT` logo depois de a loja abrir ou fechar. Com `ITEM` e `ITEM_OFFER` o campo não tem efeito. **onlyAddProducts** `boolean` (default: false) Só vale com `MERCHANT`. * `true`: cria e atualiza o que veio. Não remove nada. * `false` ou ausente: envio completo. Remove todo produto e toda categoria com código do PDV que não veio. Em cada categoria enviada, a lista substitui só os produtos com código do PDV: o que foi criado no painel, sem código, continua. Veja [Envio completo](/guides/catalog-sync#envio-completo). Envie como booleano (`true`), não como texto (`"true"`). **updatedObjects** `array` *required* Lista com pelo menos um objeto. O formato depende do `entityType`. ## Formato de `updatedObjects` > [tab] MERCHANT > > **updatedObjects\[0].id** `string` *required* > > Código da loja no seu PDV. Você escolhe o valor, e a Onbeef guarda o do último envio. Sem ele, o envio termina em `FAIL` e nada é processado. O mesmo valor volta em `merchant.id` nos pedidos: use sempre o mesmo na mesma loja. > > **updatedObjects\[0].categories** `array` > > Categorias. Sem este campo, o envio só aplica o `merchantStatus`. > > **Campos da categoria** > > **id** `string` *required* > > Código da categoria no PDV. Use um id estável, nunca o nome. > > **name** `string` *required* > > Nome da categoria. Usado só na criação. > > **itemOfferId** `array of strings` > > Lista com o `id` de cada oferta da categoria. Envie em todas as categorias: sem a chave, nada é removido nem sai de categoria e o envio termina em `FAIL`. No envio completo sem falha, `[]` esvazia a categoria. > > **index** `integer` > > Posição da categoria no catálogo. Opcional e usado só na criação: sem ele, a categoria nova entra na posição `0`. Em categoria que já existe, é ignorado. > > **status** `string` > > `AVAILABLE` ou `UNAVAILABLE`. Sem o campo, a categoria nova nasce ativa e a existente fica como está. Envie só quando o status mudar no PDV. > > **updatedObjects\[0].itemOffers** `array` > > Ofertas: o preço e a disponibilidade de cada produto. > > **Campos da oferta** > > **id** `string` *required* > > Id da oferta. Precisa aparecer no `itemOfferId` de uma categoria. Só vale dentro do envio. > > **itemId** `string` *required* > > Código do produto no PDV. Precisa ser igual ao `id` de um objeto de `items`. > > **price.value** `number` *required* > > Preço em reais. Com `unit: "KG"`, é o preço do quilo. > > **status** `string` > > `AVAILABLE` ou `UNAVAILABLE`. Sem o campo, o produto novo nasce disponível e o existente fica como está. `AVAILABLE` reativa o produto que o lojista desativou no painel: envie só quando o status mudar no PDV. > > **updatedObjects\[0].items** `array` > > Produtos. > > **Campos do produto** > > **id** `string` *required* > > Código do produto no PDV. Envie como texto. É o **Código de integração com PDV** no painel. > > **name** `string` *required* > > Nome do produto. Usado só na criação: em produto que já existe, o nome do painel fica. > > **unit** `string` > > `"KG"` (por peso) ou `"UN"` (por unidade), em maiúsculas. Envie sempre: sem ele, o produto é criado por unidade. Não muda depois de criado: em produto que já existe, o preço é gravado no tipo que ele tem no painel. > > **description** `string` > > Descrição. Em produto que já existe, só é gravada se a descrição estiver vazia. > > **externalCode** `string` > > Código de balança. Substitui o **Código da balança** do painel. Não é o código do PDV. > > **serving** `integer` > > Quantas pessoas o produto serve. > > **image.url** `string` > > URL pública da foto. A Onbeef não copia a imagem: a URL precisa continuar no ar. `image.URL` também é aceito. > > O produto só entra se a ligação fechar: `categories[].itemOfferId[]` → `itemOffers[].id` → `itemOffers[].itemId` → `items[].id`. Produto ou oferta fora de categoria é ignorado. > > * **Produto que já existe.** O preço é atualizado. A disponibilidade só muda se a oferta trouxer `status`. O nome do painel fica. > * **Categoria que já existe.** Só o `status` é atualizado. Nome e ordem ficam como estão no painel. > * **Categoria dos produtos que já existem.** O produto só entra na categoria enviada se já estiver em alguma categoria com código do PDV. Senão, recebe o preço e fica onde está. Veja [Categorias da loja diferentes das do PDV](/guides/catalog-linking#categorias-da-loja-diferentes-das-do-pdv). > * **Blocos ignorados.** `basicInfo`, `services`, `menus`, `optionGroups` e `availabilities` são aceitos e ignorados. O mesmo vale para `price.originalValue` e `price.currency`. > > **Exemplo mínimo: abrir ou fechar a loja** > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "UNAVAILABLE", > "updatedObjects": [{ "id": "LOJA-01" }] > } > ``` > > **Exemplo: produto novo, sem remover nada** > > Sem `status`, o produto novo nasce disponível e a categoria que já existe fica como está. O `merchantStatus` é o valor lido em `GET /v1/merchant`. > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "AVAILABLE", > "onlyAddProducts": true, > "updatedObjects": [ > { > "id": "LOJA-01", > "categories": [ > { "id": "15", "name": "Bovinos", "itemOfferId": ["OF-1003"] } > ], > "itemOffers": [ > { "id": "OF-1003", "itemId": "1003", "price": { "value": 59.90 } } > ], > "items": [ > { "id": "1003", "name": "Fraldinha", "unit": "KG" } > ] > } > ] > } > ``` > > **Exemplo completo: catálogo inteiro** > > Envio completo, com todos os campos. Aqui o `status` vem do PDV: o refrigerante acabou. > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "AVAILABLE", > "onlyAddProducts": false, > "updatedObjects": [ > { > "id": "LOJA-01", > "categories": [ > { "id": "15", "name": "Bovinos", "index": 0, "status": "AVAILABLE", "itemOfferId": ["OF-1001", "OF-1003"] }, > { "id": "22", "name": "Bebidas", "index": 1, "status": "AVAILABLE", "itemOfferId": ["OF-2001"] } > ], > "itemOffers": [ > { "id": "OF-1001", "itemId": "1001", "price": { "value": 94.90 } }, > { "id": "OF-1003", "itemId": "1003", "price": { "value": 59.90 } }, > { "id": "OF-2001", "itemId": "2001", "price": { "value": 10.00 }, "status": "UNAVAILABLE" } > ], > "items": [ > { > "id": "1001", > "name": "Picanha", > "unit": "KG", > "description": "Peça resfriada, vendida por peso", > "externalCode": "000123", > "serving": 4, > "image": { "url": "https://pdv.example.com/fotos/1001.jpg" } > }, > { "id": "1003", "name": "Fraldinha", "unit": "KG" }, > { "id": "2001", "name": "Refrigerante 2 L", "unit": "UN" } > ] > } > ] > } > ``` > [tab] ITEM > > Lista de produtos que já existem na loja. Não cria produto e não altera preço. > > **updatedObjects\[].id** `string` *required* > > Código do produto no PDV. Se não existir na loja, o objeto é pulado e o envio termina em `FAIL` com "Itens não encontrados: ...". > > **updatedObjects\[].name** `string` *required* > > Nome do produto. Sempre substitui o nome que está no painel. Para manter o nome do painel, envie o `name` lido em `GET /v1/merchant`. > > **updatedObjects\[].description** `string` > > Descrição. Substitui a do painel. > > **updatedObjects\[].status** `string` > > `AVAILABLE` ou `UNAVAILABLE`. Sem o campo, a disponibilidade fica como está. > > **updatedObjects\[].externalCode** `string` > > Código de balança. Substitui o **Código da balança** do painel. > > **updatedObjects\[].serving** `integer` > > Quantas pessoas o produto serve. > > **updatedObjects\[].image.url** `string` > > URL pública da foto. Troca a foto que veio do PDV. As fotos que o lojista subiu no painel ficam. > > Campo opcional omitido fica como está. Campos de preço são ignorados. > > **Exemplo mínimo** > > ```json theme={null} > { > "entityType": "ITEM", > "updatedObjects": [ > { "id": "1001", "name": "Picanha" } > ] > } > ``` > > **Exemplo completo** > > ```json theme={null} > { > "entityType": "ITEM", > "updatedObjects": [ > { > "id": "1001", > "name": "Picanha", > "description": "Peça resfriada, vendida por peso", > "status": "AVAILABLE", > "externalCode": "000123", > "serving": 4, > "image": { "url": "https://pdv.example.com/fotos/1001.jpg" } > }, > { "id": "2001", "name": "Refrigerante 2 L", "status": "UNAVAILABLE" } > ] > } > ``` > [tab] ITEM_OFFER > > Lista de preços de produtos que já existem na loja. Não cria produto e não mexe em nome, descrição ou categoria. > > **updatedObjects\[].itemId** `string` *required* > > Código do produto no PDV. Se não existir na loja, o objeto é pulado e o envio termina em `FAIL` com "Itens não encontrados: ...". > > **updatedObjects\[].price.value** `number` *required* > > Preço em reais. Em produto por peso, é o preço do quilo. Obrigatório mesmo quando só o `status` muda. > > **updatedObjects\[].status** `string` > > `AVAILABLE` ou `UNAVAILABLE`. Sem o campo, a disponibilidade fica como está. > > `id`, `price.originalValue` e `price.currency` são aceitos e ignorados. > > **Exemplo mínimo** > > ```json theme={null} > { > "entityType": "ITEM_OFFER", > "updatedObjects": [ > { "itemId": "1001", "price": { "value": 94.90 } } > ] > } > ``` > > **Exemplo completo** > > ```json theme={null} > { > "entityType": "ITEM_OFFER", > "updatedObjects": [ > { "itemId": "1001", "price": { "value": 94.90 }, "status": "AVAILABLE" }, > { "itemId": "2001", "price": { "value": 10.00 }, "status": "UNAVAILABLE" } > ] > } > ``` ## Resposta `204`, sem corpo. A Onbeef recebeu o envio e vai processar. O `204` não confirma que o catálogo mudou. Quando ele chega, o resultado do envio anterior já foi substituído por `PROCESSING`. Consulte [`GET /v1/merchantStatus`](/api-reference/merchant/get-status) até o `status` sair de `PROCESSING`. Envie uma sincronização por vez. ## Erros Só o topo do corpo é validado na hora. O erro vem no formato `{ "title": "...", "status": 400 }`. | HTTP | Mensagem (`title`) | Motivo | O que fazer | | - | - | - | - | | `400` | `The entity type field is required.` | Faltou `entityType`. | Envie `MERCHANT`, `ITEM` ou `ITEM_OFFER`. | | `400` | `The selected entity type is invalid.` | `entityType` fora dos três aceitos, como `CATEGORY` ou `MENU`. | Use um dos três tipos. | | `400` | `The merchant status field is required when entity type is MERCHANT.` | `MERCHANT` sem `merchantStatus`. | Envie `AVAILABLE` ou `UNAVAILABLE`. | | `400` | `The selected merchant status is invalid.` | `merchantStatus` com outro valor, em qualquer tipo de envio. | Envie `AVAILABLE` ou `UNAVAILABLE`, ou tire o campo em `ITEM` e `ITEM_OFFER`. | | `400` | `The updated objects field is required.` | `updatedObjects` ausente ou vazio (`[]`). | Envie pelo menos um objeto. | | `400` | `The only add products field must be true or false.` | `onlyAddProducts` como texto. | Envie o booleano `true` ou `false`. | | `403` | `Integration is not active` | A chave está **Inativa** no painel. | O lojista reativa a chave. Não precisa gerar outra. | | `405` | `The POST method is not supported for route v1/merchantUpdate. Supported methods: PUT.` | Método diferente de `PUT`. | Use `PUT`. | | `429` | `Too Many Requests` | Mais de 60 escritas por minuto na loja. | Espere o tempo do cabeçalho `Retry-After` e envie em lote. | Erro dentro de `updatedObjects` não vira erro HTTP: a resposta é `204` e o problema aparece no `moreInfo` de [`GET /v1/merchantStatus`](/api-reference/merchant/get-status). Os erros de token estão em [Erros](/api-reference/errors). # Cadastre o webhook de pedidos Source: https://docs.onbeef.app/api-reference/merchant/update-merchant PUT /v1/merchantOnboarding Informe a URL do seu sistema que recebe os avisos de pedido. Este endpoint (merchantOnboarding) não envia catálogo. `PUT /v1/merchantOnboarding` cadastra a URL que recebe os avisos de pedido (webhook). Apesar do nome, ele não cria loja e não mexe no catálogo: para enviar catálogo, use [`PUT /v1/merchantUpdate`](/api-reference/merchant/sync-catalog). > [card] [Entenda o fluxo](/guides/orders-webhook) > > O que chega no webhook, como validar a assinatura e o que responder. ## Corpo da requisição **ordersWebhookURL** `string (URL)` *required* URL base do seu sistema. A Onbeef acrescenta `/v1/orderUpdate` ao final e envia os avisos para lá. Não inclua `/v1/orderUpdate` nem barra no final. `getMerchantURL` é guardado e não tem uso: não envie. Na resposta, ele vem `null`. ## Resposta `200` com a URL gravada. **ordersWebhookURL** `string` A URL base cadastrada. ### Regras * **O cadastro é da chave, não da loja.** Vale para a chave usada no token. Loja com duas chaves tem dois cadastros, e cada chave com webhook recebe os avisos. * **Chave nova, cadastro novo.** Ao gerar outra chave, cadastre o webhook de novo com o token dela. * **Para trocar a URL, envie de novo.** O valor novo substitui o anterior. * **Ambientes separados.** O cadastro do ambiente de teste não vale em produção. Cadastre nos dois. * **Não é pré-requisito do catálogo.** O envio de catálogo funciona sem webhook. ## Exemplo ```bash Ambiente de teste theme={null} curl --request PUT \ --url https://api.dev.connect.onbeefapp.com.br/v1/merchantOnboarding \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "ordersWebhookURL": "https://pdv.example.com/onbeef" }' ``` ```json theme={null} { "getMerchantURL": null, "ordersWebhookURL": "https://pdv.example.com/onbeef" } ``` Com esse cadastro, os avisos chegam em `POST https://pdv.example.com/onbeef/v1/orderUpdate`. ## Erros | HTTP | Mensagem (`title`) | Motivo | O que fazer | | - | - | - | - | | `400` | `The ordersWebhookURL field is required.` | Faltou `ordersWebhookURL`. | Envie a URL base do seu sistema. | | `400` | `The ordersWebhookURL field must be a valid URL.` | O valor não é uma URL. | Envie a URL completa, com `https://`. | | `401` | `Token has expired` | O token passou de 12 horas. | Peça outro em `POST /oauth/token`. | | `403` | `Integration is not active` | A chave está **Inativa** no painel. | O lojista reativa a chave. Não precisa gerar outra. | | `429` | `Too Many Requests` | Mais de 60 escritas por minuto na loja. | Espere o tempo do cabeçalho `Retry-After`. | A lista completa está em [Erros](/api-reference/errors). # Aceite um cancelamento Source: https://docs.onbeef.app/api-reference/orders/accept-cancellation POST /v1/orders/{orderId}/acceptCancellation Cancela o pedido na Onbeef, com estorno do pagamento online. Não há pedido de cancelamento para aceitar: use requestCancellation. Cancela o pedido na Onbeef e estorna o pagamento online. Hoje este endpoint não tem o que aceitar: a Onbeef nunca envia um pedido de cancelamento para a integração aprovar. Quando a loja ou o cliente cancela, o pedido já chega como `CANCELLED`. Para cancelar um pedido pelo seu sistema, use [Cancelar pedido](/api-reference/orders/request-cancellation), que registra o motivo. ## Regras * **Cancela direto.** A chamada tem o mesmo efeito de um cancelamento: não pode ser desfeita e sempre estorna o pagamento online. * **Sem motivo.** A chamada não leva `reason` nem `code`. A loja vê o pedido cancelado sem o motivo do seu sistema. * **O evento muda na hora.** O evento do pedido na Connect vira `CANCELLED` assim que a chamada é recebida, mesmo quando a Onbeef não cancela (pedido já entregue). Nesse caso, consulte o pedido no painel da loja. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição Envie a chamada sem corpo. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/acceptCancellation" \ --header "Authorization: Bearer " ``` ## Resposta `204`, sem corpo. A resposta só diz que a chamada foi recebida. O cancelamento é aplicado em seguida. Pelo webhook chega `CANCELLED`, duas vezes. Se a Onbeef recusar o cancelamento, chega `CANCELLATION_REQUEST_DENIED`. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Aceite um pedido Source: https://docs.onbeef.app/api-reference/orders/confirm POST /v1/orders/{orderId}/confirm Aceite um pedido pela API. Ele passa para Em preparo no painel da loja e o evento vira CONFIRMED. Aceita o pedido: ele passa para **Em preparo** no painel da loja e o evento vira `CONFIRMED`. Quem usa é o PDV que conduz o status do pedido no lugar da loja. Um PDV que só importa pedidos não precisa chamar, porque a loja aceita no painel da Onbeef. Empresa de entregas também não chama. > [card] [Entenda o fluxo](/guides/order-flow) > > Veja a ordem das chamadas quando o seu sistema conduz o status do pedido. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição **orderExternalCode** `string` *required* Código do pedido no seu sistema. A Onbeef só guarda o valor: ele não aparece no painel nem volta em [Consultar pedido](/api-reference/orders/get-order). Mantenha no seu sistema a relação entre o `orderId` e o seu código. **createdAt** `string (date-time)` *required* Data de criação do pedido. Envie o `createdAt` que veio no pedido. O campo é exigido pelo padrão Open Delivery e não altera o pedido. `preparationTime` e `reason` são aceitos e ignorados. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/confirm" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "orderExternalCode": "PDV-00123", "createdAt": "2026-11-12T17:30:00Z" }' ``` ## Resposta `202`, sem corpo. A resposta só diz que a chamada foi recebida. A mudança é aplicada em seguida. * **A confirmação é o evento.** Quando a mudança é aplicada, chega `CONFIRMED` pelo webhook e pela consulta de eventos. * **Duas notificações.** Pelo webhook, o evento de uma mudança feita pela sua integração chega duas vezes. Trate como normal. * **O cliente é avisado.** Ele recebe a mesma mensagem de WhatsApp que receberia se a loja aceitasse pelo painel, quando a loja usa as mensagens automáticas. ## Quando a mudança não é aplicada A recusa não volta na resposta e não gera evento. Se `CONFIRMED` não chegar em cerca de 70 segundos, a mudança não foi aplicada: consulte o pedido e leia o `lastEvent`. | Motivo | O que fazer | | - | - | | O pedido já foi entregue ou cancelado. | Nada. O pedido não muda mais. | | O pedido já passou dessa etapa (está **Pronto** ou **Em rota**). O status não volta. | Siga a partir do `lastEvent` atual. | | A loja já tinha aceitado o pedido no painel. | Nada. Nenhum evento novo é gerado. | ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `The order external code field is required.` | Falta `orderExternalCode` no corpo. | Envie o código do pedido no seu sistema. | | `400` | `The created at field is required.` | Falta `createdAt` no corpo. | Envie o `createdAt` do pedido. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Confirme eventos Source: https://docs.onbeef.app/api-reference/orders/confirm-events POST /v1/events/acknowledgment Avise que o seu sistema já gravou um ou mais eventos. Eles param de voltar na consulta de eventos da sua chave. Registra que o seu sistema já gravou um ou mais eventos. Depois disso, eles param de voltar em [Consultar eventos](/api-reference/orders/get-events) para a sua chave. > [card] [Entenda o fluxo](/guides/order-flow) > > Veja em que ponto do fluxo confirmar cada evento. ## Regras * **Confirme só depois de gravar.** Depois da confirmação o evento não volta mais, e a API não tem listagem de pedidos para você reencontrá-lo. * **Vale só para a sua chave.** Outro sistema ligado à mesma loja continua recebendo o evento até confirmar com a chave dele. * **Confirme também o que chegou por webhook.** O webhook não tira o evento da consulta. Evento não confirmado não expira: repete até ser confirmado ou até o pedido mudar de evento. * **Copie os valores da consulta.** Envie `id`, `orderId` e `eventType` exatamente como vieram. Não misture valores de eventos diferentes. * **Vários por chamada.** Gravou 40 eventos: confirme os 40 em um array. A rota divide com as outras escritas o limite de 60 por minuto da loja. * **Confirme também o que você não usa.** A alternativa é filtrar a consulta por `eventType`. * **`CANCELLATION_REQUEST_DENIED` não se confirma.** Ele chega só pelo webhook e não aparece na consulta de eventos. ## Corpo da requisição O corpo é um array JSON. Cada objeto confirma um evento de um pedido. Envie o header `Content-Type: application/json`. **id** `string (uuid)` *required* O `eventId` recebido na consulta de eventos ou no webhook. É o identificador do tipo de evento, igual para todos os pedidos. **orderId** `string (uuid)` *required* O `orderId` do evento. **eventType** `string` *required* O `eventType` do evento, por exemplo `CREATED` ou `DELIVERED`. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/events/acknowledgment" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '[ { "id": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c", "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "eventType": "CREATED" } ]' ``` ## Resposta `202`, sem corpo. Os eventos confirmados não aparecem mais na consulta desta chave. Os itens são confirmados um a um, na ordem do array. Se um item falha com `404`, os anteriores já foram confirmados. Reenviar o array inteiro é seguro: confirmar o mesmo evento de novo não muda nada. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `The selected 0.id is invalid.` | O `id` não é um `eventId` da Onbeef. O número é a posição do item no array. | Nenhum item foi confirmado. Copie o `eventId` da consulta e reenvie. | | `400` | `The selected 0.orderId is invalid.` | O `orderId` não existe. | Nenhum item foi confirmado. Corrija e reenvie. | | `400` | `The 0.eventType field is required.` | Falta um campo no item. | Nenhum item foi confirmado. Envie os três campos em cada item. | | `404` | `Order not found` | O pedido existe, mas é de outra loja. | Tire o item e reenvie. Os itens anteriores do array já foram confirmados. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Marque o pedido como entregue Source: https://docs.onbeef.app/api-reference/orders/delivered POST /v1/orders/{orderId}/delivered Avise que o cliente recebeu o pedido. Ele passa para Entregue no painel da loja e o evento vira DELIVERED. Marca que o cliente recebeu o pedido, na entrega ou na retirada: ele passa para **Entregue** no painel da loja e o evento vira `DELIVERED`. Quem usa é a [empresa de entregas](/guides/delivery-flow), quando o entregador conclui a entrega, e o PDV que conduz o status no lugar da loja. Um PDV que só importa pedidos não precisa chamar. > [card] [Entenda o fluxo](/guides/order-flow) > > Veja a ordem das chamadas quando o seu sistema conduz o status do pedido. > [!WARNING] > > `DELIVERED` é final. Depois dele o pedido não muda mais de status e não pode ser cancelado pela API nem pela loja no painel. Chame só quando o cliente estiver com o pedido. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição Envie a chamada sem corpo. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/delivered" \ --header "Authorization: Bearer " ``` ## Resposta `202`, sem corpo. A resposta só diz que a chamada foi recebida. A mudança é aplicada em seguida. * **A confirmação é o evento.** Quando a mudança é aplicada, chega `DELIVERED` pelo webhook e pela consulta de eventos. * **Duas notificações.** Pelo webhook, o evento de uma mudança feita pela sua integração chega duas vezes. Trate como normal. * **O cliente é avisado.** Ele recebe a mensagem de WhatsApp de pedido entregue, quando a loja usa as mensagens automáticas. * **Dá para pular etapas.** A chamada vale em pedido que ainda não passou por **Pronto** ou **Em rota**. * **Não registra pagamento.** Pedido pago na entrega continua com `payments.methods[].type` em `PENDING` depois do `DELIVERED`. * **Sem código de confirmação de entrega.** Ele não existe: a entrega é confirmada só com esta chamada. ## Quando a mudança não é aplicada A recusa não volta na resposta e não gera evento. Se `DELIVERED` não chegar em cerca de 70 segundos, a mudança não foi aplicada: consulte o pedido e leia o `lastEvent`. | Motivo | O que fazer | | - | - | | O pedido já foi entregue ou cancelado. | Nada. O pedido não muda mais. | | Pedido pago online, com item por peso, e a loja ainda não confirmou o peso. | Peça à loja para confirmar o peso no painel da Onbeef e chame de novo. | | Pedido pago com cartão online, e o cliente ainda não fez a validação de segurança do pagamento. | A loja resolve no painel da Onbeef. Depois, chame de novo. | ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Atualize o rastreamento Source: https://docs.onbeef.app/api-reference/orders/delivery-updates POST /v1/orders/{orderId}/tracking Guarda os dados de rastreamento da entrega. Hoje eles não são mostrados à loja nem ao cliente. Guarda os dados de rastreamento de uma entrega no pedido. Hoje este endpoint aceita os dados e não faz mais nada com eles: não aparecem para a loja nem para o cliente, e a chamada não muda o status do pedido nem gera evento. Para informar a saída e a entrega, use [Despachar pedido](/api-reference/orders/dispatch) e [Marcar como entregue](/api-reference/orders/delivered). ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição **deliveryTrackingInfo** `object` *required* Dados da entrega, no formato do padrão Open Delivery. A API só exige que o campo exista e seja um objeto: o conteúdo é guardado como veio, sem validação. Cada chamada substitui os dados da anterior. Campos mais comuns do padrão: | Campo | O que é | | - | - | | `deliveryPerson` | Nome e telefone do entregador. | | `vehicle` | Tipo e placa do veículo. | | `eta` | Previsão de chegada. | | `geoLocalization` | Latitude e longitude do entregador. | | `externalTrackingURL` | Link de acompanhamento no seu sistema. | ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/tracking" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "deliveryTrackingInfo": { "deliveryPerson": { "name": "Carlos" }, "externalTrackingURL": "https://entregas.exemplo.com/t/123" } }' ``` ## Resposta `202`, sem corpo. Nenhum evento chega depois. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | Mensagem de validação do campo | Faltou `deliveryTrackingInfo`, ou ele não é um objeto. | Corrija o corpo e reenvie. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Negue um cancelamento Source: https://docs.onbeef.app/api-reference/orders/deny-cancellation POST /v1/orders/{orderId}/denyCancellation Não muda o pedido na Onbeef. Só marca o evento do pedido na Connect como CANCELLED_DENIED. Marca o evento do pedido na Connect como `CANCELLED_DENIED`. Hoje este endpoint não muda o pedido na Onbeef: o status no painel da loja continua o mesmo e nada é estornado. Também não há o que negar, porque a Onbeef nunca envia um pedido de cancelamento para a integração aprovar. Quando a loja ou o cliente cancela, o pedido já chega como `CANCELLED`. ## Regras * **Só o evento muda.** A consulta de eventos passa a devolver `CANCELLED_DENIED` para o pedido, até a próxima mudança de status. * **Não desfaz cancelamento.** Um pedido cancelado na Onbeef continua cancelado depois da chamada. * **O motivo não aparece.** `reason` e `code` ficam guardados e não são mostrados à loja nem ao cliente. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição **reason** `string` *required* Explicação em texto livre. **code** `string` *required* Um dos códigos aceitos em [Cancelar pedido](/api-reference/orders/request-cancellation), como `UNAVAILABLE_ITEM` ou `DELIVERY_PROBLEM`. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/denyCancellation" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "reason": "Pedido já saiu para entrega", "code": "DELIVERY_PROBLEM" }' ``` ## Resposta `204`, sem corpo. Pelo webhook chegam duas notificações: `CANCELLED_DENIED` e `CANCELLATION_REQUEST_DENIED`. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | Mensagem de validação do campo | Faltou `reason` ou `code`, ou o `code` não está na lista. | Corrija o corpo e reenvie. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Despache um pedido Source: https://docs.onbeef.app/api-reference/orders/dispatch POST /v1/orders/{orderId}/dispatch Avise que o pedido saiu para entrega. Ele passa para Em rota no painel da loja e o evento vira DISPATCHED. Marca que o pedido saiu para entrega: ele passa para **Em rota** no painel da loja e o evento vira `DISPATCHED`. Quem usa é a empresa de entregas, quando o entregador sai com o pedido, e o PDV que conduz o status no lugar da loja. Um PDV que só importa pedidos não precisa chamar. > [card] [Entenda o fluxo](/guides/delivery-flow) > > Veja o fluxo completo de uma empresa de entregas, do pedido aceito ao pedido entregue. ## Regras * **Só pedido de entrega.** A chamada vale para `type: "DELIVERY"`. Em pedido de retirada (`TAKEOUT`), ela não é aplicada. * **Espere o pedido ficar pronto.** Chame depois de `READY_FOR_PICKUP`, ou no mínimo depois de `CONFIRMED`. A API aplica o `dispatch` mesmo em pedido que a loja ainda não aceitou. * **Vale a primeira chamada.** A loja, o PDV e a empresa de entregas podem marcar a saída. A segunda chamada é ignorada: combine com a loja quem conduz. * **Consulte o pedido antes de sair.** O valor a cobrar muda quando a loja pesa, sem gerar evento. Leia `payments` de novo na hora da coleta: veja [Pagamento](/guides/order-data#pagamento). * **Entrega que não deu certo.** Não existe chamada para isso. Avise a loja: [Cancelar pedido](/api-reference/orders/request-cancellation) estorna o cliente. * **O cliente é avisado.** Ele recebe a mensagem de WhatsApp de pedido a caminho, quando a loja usa as mensagens automáticas. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição Envie a chamada sem corpo. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/dispatch" \ --header "Authorization: Bearer " ``` ## Resposta `202`, sem corpo. A resposta só diz que a chamada foi recebida. A mudança é aplicada em seguida. * **A confirmação é o evento.** Quando a mudança é aplicada, chega `DISPATCHED` pelo webhook e pela consulta de eventos. * **Duas notificações.** Pelo webhook, o evento de uma mudança feita pela sua integração chega duas vezes. Trate como normal. ## Quando a mudança não é aplicada A recusa não volta na resposta e não gera evento. Se `DISPATCHED` não chegar em cerca de 70 segundos, a mudança não foi aplicada: consulte o pedido. `lastEvent` e `type` mostram o motivo. | Motivo | O que fazer | | - | - | | O pedido é de retirada (`TAKEOUT`). | Não despache. Quando o cliente retirar, use [Marcar como entregue](/api-reference/orders/delivered). | | O pedido já foi entregue ou cancelado. | Nada. O pedido não muda mais. | | O pedido já estava **Em rota**. | Nada. Nenhum evento novo é gerado. | | Pedido pago online, com item por peso, e a loja ainda não confirmou o peso. | Peça à loja para confirmar o peso no painel da Onbeef e chame de novo. | | Pedido pago com cartão online, e o cliente ainda não fez a validação de segurança do pagamento. | A loja resolve no painel da Onbeef. Depois, chame de novo. | ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Consulte eventos Source: https://docs.onbeef.app/api-reference/orders/get-events GET /v1/events:polling Liste o evento atual de cada pedido que a sua chave ainda não confirmou. É assim que o seu sistema descobre pedidos novos e mudanças de status. Devolve o evento atual de cada pedido da loja que a sua chave ainda não confirmou. > [card] [Entenda o fluxo](/guides/order-flow) > > Webhook, consulta de eventos e confirmação, sem perder pedido. ## Regras * **É uma foto, não uma fila.** Cada pedido aparece no máximo uma vez, com o evento mais recente. Se o pedido muda antes de você confirmar, só o evento novo aparece. * **O evento repete até você confirmar.** Evento não confirmado não expira: fica na consulta até a [confirmação](/api-reference/orders/confirm-events) ou até o pedido mudar de evento. * **Até 1000 itens por consulta.** Vêm dos pedidos mais antigos para os mais novos, sem paginação. O limite vale depois dos filtros. Confirme o que gravou e consulte de novo. * **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. * **Pedido agendado.** O filtro é pela data de criação. Pedido feito antes da data do `start_at` e entregue depois não aparece: no dia da virada, recue o `start_at` 7 dias e ignore o pedido que já estava entregue antes da virada. Veja [Pedido agendado na virada](/guides/order-import#pedido-agendado-na-virada). * **Intervalo.** Consulte a cada 30 segundos: são 2 das 200 leituras por minuto da loja, divididas entre todas as chaves dela. * **Identidade do evento.** `eventId` identifica o tipo de evento, igual para todos os pedidos. Um evento é o par `orderId` + `eventId`. ## Parâmetros de consulta **eventType** `string[]` Filtra pelo tipo do evento atual. Repita o parâmetro para pedir mais de um: `?eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13`. O formato com colchetes (`eventType[]=DELIVERED`) também é aceito. Sem o parâmetro, vêm todos os tipos. Valores: `CREATED`, `CONFIRMED`, `READY_FOR_PICKUP`, `DISPATCHED`, `DELIVERED`, `CANCELLED` e `CANCELLATION_REQUESTED`. Veja o status de cada um em [Eventos e status](/concepts/orders#eventos-e-status). `CANCELLATION_REQUEST_DENIED` chega só pelo [webhook](/guides/orders-webhook), nunca aparece nesta consulta e não precisa de confirmação. O filtro não confirma nada: os pedidos com outros eventos continuam pendentes para a sua chave, e não ocupam o limite de 1000. **start_at** `string` Traz só pedidos criados a partir desta data, inclusive. O filtro olha a criação do pedido, não a data do evento nem a do agendamento. É opcional na API, mas envie em toda consulta. * `Y-m-d` (`2026-11-13`): começa às 00:00:00 do dia, no horário de Brasília, qualquer que seja o fuso da loja. * `Y-m-d H:i` (`2026-11-13 03:00`): horário em UTC. Na URL, escreva o espaço como `%20`: `2026-11-13%2003:00`. **end_at** `string` Traz só pedidos criados até esta data, inclusive. * `Y-m-d` (`2026-11-13`): vai até as 23:59:59 do dia, no horário de Brasília. * `Y-m-d H:i` (`2026-11-14 02:59`): horário em UTC. Para um dia inteiro no horário de Brasília, use `Y-m-d` nos dois: `start_at=2026-11-13&end_at=2026-11-13`. Para carregar pedidos antigos, veja [Consulte pedidos antigos](/concepts/orders-history). ## Exemplo ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-11-13" \ --header "Authorization: Bearer " ``` ## Resposta `200` com um array. Sem eventos pendentes, o array vem vazio. ```json theme={null} [ { "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c", "eventType": "CREATED", "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "orderURL": "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479", "sourceAppId": "fb08c6b7-a844-43c6-b104-98e70c00fc20", "virtualBrand": null, "createdAt": "2026-11-12T17:30:00.000000Z" } ] ``` **eventId** `string (uuid)` Identificador do tipo de evento. Vai no campo `id` da [confirmação](/api-reference/orders/confirm-events). Para detectar repetição, combine com `orderId`. **eventType** `string` Evento atual do pedido. **orderId** `string (uuid)` Identificador do pedido. Use em [Consultar pedido](/api-reference/orders/get-order) e nas ações de status. **orderURL** `string (url)` Endereço pronto para consultar o pedido. **createdAt** `string (date-time)` Data de criação do pedido, em UTC. Não é a data do evento. Ignore `sourceAppId` (identificador da Onbeef, igual em todos os eventos) e `virtualBrand` (sempre `null`). ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `The selected eventType.0 is invalid.` | Um valor de `eventType` não é um tipo de evento. O número é a posição do valor na URL. | Use os valores de `eventType`. | | `400` | `The start at field must match the format Y-m-d.` | `start_at` ou `end_at` não está em `Y-m-d` nem em `Y-m-d H:i`. | Corrija o formato da data. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e repita a consulta. | | `403` | `Integration is not active` | A chave está **Inativa** no painel da loja. | Pare o polling e peça à loja para reativar a chave. Não há aviso de reativação: tente de novo a cada 10 minutos, por exemplo. | | `503` | Varia. | Falha temporária ao validar o token. | Tente de novo com espera crescente, até 3 vezes. | | `429` | `Too Many Requests` | A loja passou de 200 leituras por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Consulte um pedido Source: https://docs.onbeef.app/api-reference/orders/get-order GET /v1/orders/{orderId} Leia o pedido completo como ele está agora: itens, pesos, total, cliente, pagamento e entrega. Devolve o pedido completo como ele está no momento da consulta. > [card] [Entenda o fluxo](/guides/order-data) > > Como ler itens, total, pagamento e cliente. > [!WARNING] > > Itens, peso e total mudam depois que o pedido é criado, sem gerar evento: a loja pesa a carne e ajusta até a entrega. Não fature com a resposta de um pedido `CREATED`: consulte de novo no `DELIVERED`. Veja [quando importar o pedido](/guides/order-import). ## Regras * **Guarde o `id`.** É ele que entra nesta rota. A API não lista pedidos: o `id` chega pelo [webhook](/guides/orders-webhook) ou por [Consultar eventos](/api-reference/orders/get-events). * **Qualquer pedido da loja**, em qualquer status e data, no estado atual: peso ajustado e item removido já aparecem. * **Dinheiro.** Reais com duas casas, como número: `128.27` é R\$ 128,27. Não divida por 100. O valor é arredondado, não truncado. Em `payments`, vem sem `currency`. * **Datas.** ISO 8601 em UTC. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Exemplo ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479" \ --header "Authorization: Bearer " ``` ## Resposta `200` com o pedido. Veja o [exemplo de resposta](#exemplo-de-resposta). ### Identificação e status **id** `string (uuid)` Identificador do pedido. Use nesta rota e nas ações de status. **displayId** `string` Código que a loja vê, como `4F15BA00B`. O número curto do painel ("Pedido 300") não vem na API. **type** `string` `DELIVERY` (entrega, com o bloco `delivery`) ou `TAKEOUT` (retirada na loja, com o bloco `takeout`). **lastEvent** `string` Evento atual, de `CREATED` a `DELIVERED`, `CANCELLED` ou `CANCELLATION_REQUESTED`. Veja [Eventos e status](/concepts/orders#eventos-e-status). **salesChannel** `string` `CATALOG` (catálogo online), `EXTENSION` (criado pela loja no painel) ou `IMPORT_CUSTOMER` (histórico de cliente importado: já entregue, sem itens, não fature). Outros valores podem aparecer: não recuse o pedido por este campo. **createdAt** `string (date-time)` Criação do pedido. `preparationStartDateTime` é o momento do aceite, ou `null`. **orderTiming** `string` `INSTANT` (para agora, com `schedule: null`) ou `SCHEDULED` (agendado). No agendado, `schedule` traz a janela em `scheduledDateTimeStart` e `scheduledDateTimeEnd`. **extraInfo** `string | null` Observação do pedido. **merchant** `object` `name` e `id`. O `id` é o código da loja no PDV que sincroniza o catálogo ou, sem ele, o UUID da loja na Onbeef. Muda quando um PDV envia o primeiro catálogo: se não é você quem envia, não use para rotear. ### Itens **items** `array of objects` Um objeto por item. `name` é o nome do produto e `specialInstructions`, a observação do item. **Campos de item** **items\[].id** `string` **Código de integração com PDV** do produto, sem prefixo. Se vier um UUID, o produto não está vinculado: o valor muda a cada pedido. Quando a loja preenche o código, uma nova consulta do mesmo pedido já o devolve. Vale para kit e item de kit. Veja [como vincular produtos](/guides/catalog-linking). **items\[].externalCode** `string | null` Código de balança. Não é o código do produto no seu sistema. **items\[].kit_id** `string | null` Em item de kit, o `id` da linha do kit. `null` fora de kit e na linha do próprio kit. Veja o preço em [Kit](/guides/order-data#kit). **items\[].unit** `string` `KG` (por peso) ou `UN` (por unidade). A linha de um kit vem como `UN`. **items\[].quantity** `number` Com `KG`, o peso em quilos: `1.32` é 1,320 kg. Com `UN`, as unidades. **items\[].unitPrice** `object` Preço cobrado: por quilo com `KG`, por unidade com `UN`. `originalPrice` é o preço sem promoção nem desconto no item. **items\[].totalPrice** `object` Total da linha: `unitPrice` x `quantity` + `optionsPrice` (a soma do `totalPrice` das opções). No exemplo, 94,90 x 1,32 + 3,00 = 128,27. Em kit, a linha pode vir com valor zero: some o `totalPrice` de todas as linhas. **items\[].options** `array of objects` Cortes e adicionais, na mesma lista, com `id`, `name`, `quantity`, `unitPrice` e `totalPrice`. * **Corte:** traz também `unit: "KG"` e `specialInstructions`. A `quantity` é o peso nesse corte, já contado na `quantity` do item: não some de novo. O `id` é o de `cuts[].id` em [Consultar loja](/api-reference/merchant/get-merchant). * **Adicional:** `quantity` em unidades e o preço, que entra no `optionsPrice`. O `id` é sempre um UUID. ### Taxas, descontos e total **otherFees** `array of objects` Taxas, com `type`, `name` e `price`. `DELIVERY_FEE` (`Frete`) vem só quando a loja cobra frete. `SERVICE_FEE` é a `Taxa de serviço`. Vazio quando não há taxa. **discounts** `array of objects` Um objeto por desconto: cupom, clube, fidelidade, cashback, agendamento ou **Desconto personalizado** da loja. Não há campo com o tipo. O desconto de **Ajustar valor** não vem: veja [Desconto dado pela loja](/guides/order-import#desconto-dado-pela-loja). * `amount`: valor do desconto. * `target`: `CART` (itens) ou `DELIVERY_FEE` (taxa de entrega). Frete grátis da fidelidade vem como a taxa `DELIVERY_FEE` e um desconto do mesmo valor. * `sponsorshipValues`: sempre um objeto com `name: "MERCHANT"` e o mesmo `amount`. Em cupom, traz `discountCode`. **total** `object` `itemsPrice` (soma do `totalPrice` dos itens), `otherFees` (soma das taxas), `discount` (soma dos descontos) e `orderAmount`. `orderAmount = itemsPrice + otherFees - discount`. ### Pagamento **payments** `object` `prepaid` é o total do pedido quando `type` é `PREPAID`, senão `0`. `pending` é o total quando `type` é `PENDING`. `methods` traz sempre um objeto. **Campos de payments.methods\[]** **payments.methods\[].value** `number` Repete o `total.orderAmount`, recalculado a cada consulta: depois do ajuste de peso, acompanha o total novo. A API não informa o valor cobrado no cartão ou no PIX, o estorno nem a data do pagamento. **payments.methods\[].type** `string` * `PREPAID`: já está pago. Não cobre. * `PENDING`: não está pago. Cobre na entrega só 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. A API não tem campo que separe pagamento na entrega de pagamento online em andamento: cartão online ainda não capturado sai `PENDING`. Veja [Pagamento](/guides/order-data#pagamento). **payments.methods\[].method** `string` `PIX`, `CREDIT` (inclusive Apple Pay), `DEBIT`, `CASH`, `FOOD_VOUCHER` (vale alimentação), `MEAL_VOUCHER` (vale refeição) ou `OTHER`. PIX e cartão podem ser online ou na entrega. **payments.methods\[].methodInfo** `string | null` Com `OTHER`, o nome da forma, em texto livre: `Pagamento a prazo (Nota/Fiado)`, `Link de pagamento`, `Link via Whatsapp` ou o que a loja cadastrou, como boleto. `null` nos outros métodos. **payments.methods\[].changeFor** `number` Troco para: o valor em dinheiro que o cliente vai entregar. Pedido de 146,27 com `changeFor: 200` pede 53,73 de troco. Só aparece quando há troco. ### Cliente **customer** `object` * `id`: identificador do cliente na Onbeef. `null` quando o pedido não está ligado a um cadastro. * `name` e `email`, que pode vir `null`. * `phone.number`: como foi cadastrado, normalmente DDD e número (`11999999999`). Normalize. * `documentNumber`: CPF ou CNPJ informado no pedido ou, na falta dele, o do cadastro do cliente na loja. Pode vir `null`. Não indica que o cliente pediu o documento na nota. * `ordersCountOnMerchant`: pedidos entregues do cliente nesta loja. `null` sem `id`. ### Entrega e retirada **delivery** `object | null` Só em pedido `DELIVERY`. Vem `null` se o pedido não tem endereço. * `deliveryAddress`: `street`, `number`, `complement`, `reference`, `district`, `city`, `state`, `postalCode`, `country`, `formattedAddress` (em uma linha) e `coordinates`, com `latitude` e `longitude`, que podem vir `null`. * `estimatedDeliveryDateTime`: previsão de entrega. No agendado, o fim da janela. * `deliveryDateTime`: momento em que o pedido foi marcado como entregue. `null` antes disso. **takeout** `object` Só em pedido `TAKEOUT`. `takeoutDateTime` é a previsão de retirada ou, no agendado, o fim da janela. A hora em que o cliente retirou não vem na API. ### Campos fixos: ignore `sourceAppId` (identificador da Onbeef), `virtualBrand` (`null`), `sendDelivered` e `sendTracking` (`true`), `delivery.deliveredBy` (`MERCHANT`), `takeout.mode` (`DEFAULT`), `payments.methods[].brand` (`null`) e `customer.phone.extension` (`null`) têm sempre o mesmo valor. ## Exemplo de resposta Pedido de entrega com um item por peso, com corte e adicional, e um item por unidade. Tem cupom de R\$ 10,00 e pagamento em dinheiro na entrega. * Picanha: 94,90 x 1,32 = 125,27, mais 3,00 do adicional = 128,27. * Itens: 128,27 + 20,00 = 148,27. * Total: 148,27 + 8,00 - 10,00 = 146,27. ```json theme={null} { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "DELIVERY", "sourceAppId": "fb08c6b7-a844-43c6-b104-98e70c00fc20", "virtualBrand": null, "displayId": "4F15BA00B", "salesChannel": "CATALOG", "createdAt": "2026-11-12T17:30:00.000000Z", "lastEvent": "READY_FOR_PICKUP", "merchant": { "id": "LOJA-01", "name": "Açougue Exemplo" }, "items": [ { "id": "1001", "name": "Picanha", "externalCode": "000123", "kit_id": null, "unit": "KG", "quantity": 1.32, "specialInstructions": "Bem limpa", "unitPrice": { "value": 94.9, "currency": "BRL" }, "originalPrice": { "value": 94.9, "currency": "BRL" }, "optionsPrice": { "value": 3, "currency": "BRL" }, "totalPrice": { "value": 128.27, "currency": "BRL" }, "options": [ { "id": "0b7d4c7a-93b1-4c53-8a55-7d2c5e0e4b20", "name": "Bife", "quantity": 1.32, "unitPrice": { "value": 0, "currency": "BRL" }, "unit": "KG", "specialInstructions": "Bifes de 2 dedos", "totalPrice": { "value": 0, "currency": "BRL" } }, { "id": "5a1d2c3b-7e8f-4a9b-b0c1-d2e3f4a5b6c7", "name": "Embalagem a vácuo", "unitPrice": { "value": 3, "currency": "BRL" }, "quantity": 1, "totalPrice": { "value": 3, "currency": "BRL" } } ] }, { "id": "2001", "name": "Refrigerante 2 L", "externalCode": null, "kit_id": null, "unit": "UN", "quantity": 2, "specialInstructions": null, "unitPrice": { "value": 10, "currency": "BRL" }, "originalPrice": { "value": 10, "currency": "BRL" }, "optionsPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 20, "currency": "BRL" }, "options": [] } ], "otherFees": [ { "name": "Frete", "type": "DELIVERY_FEE", "price": { "value": 8, "currency": "BRL" } } ], "discounts": [ { "amount": { "value": 10, "currency": "BRL" }, "target": "CART", "sponsorshipValues": [ { "name": "MERCHANT", "amount": { "value": 10, "currency": "BRL" }, "discountCode": "BEMVINDO10" } ] } ], "total": { "itemsPrice": { "value": 148.27, "currency": "BRL" }, "otherFees": { "value": 8, "currency": "BRL" }, "discount": { "value": 10, "currency": "BRL" }, "orderAmount": { "value": 146.27, "currency": "BRL" } }, "customer": { "id": "9c2e4f6a-1b3d-4e5f-8a7b-6c5d4e3f2a1b", "name": "João da Silva", "phone": { "number": "11999999999", "extension": null }, "email": "joao@example.com", "documentNumber": null, "ordersCountOnMerchant": 3 }, "schedule": null, "orderTiming": "INSTANT", "preparationStartDateTime": "2026-11-12T17:35:10.000000Z", "payments": { "prepaid": 0, "pending": 146.27, "methods": [ { "value": 146.27, "currency": "BRL", "type": "PENDING", "method": "CASH", "brand": null, "methodInfo": null, "changeFor": 200 } ] }, "extraInfo": "Interfone 31", "sendDelivered": true, "sendTracking": true, "delivery": { "deliveredBy": "MERCHANT", "deliveryAddress": { "country": "BR", "state": "SP", "city": "São Paulo", "district": "Moema", "street": "Av. Exemplo", "number": "100", "complement": "BL 02 AP 31", "reference": "Casa amarela", "formattedAddress": "Av. Exemplo, 100, Moema, São Paulo - SP, BR", "postalCode": "04000-000", "coordinates": { "latitude": -23.54823, "longitude": -46.63632 } }, "estimatedDeliveryDateTime": "2026-11-12T18:00:00.000000Z", "deliveryDateTime": null } } ``` ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `404` | `Order not found` | O `orderId` não existe, é de outra loja ou é de outro ambiente (teste ou produção). | Confira o `orderId` e a URL do ambiente. | `401 Token has expired`, `403 Integration is not active`, `429 Too Many Requests` e as outras mensagens estão em [Erros e limites](/api-reference/errors). # Marque o pedido como pronto Source: https://docs.onbeef.app/api-reference/orders/ready-for-pickup POST /v1/orders/{orderId}/readyForPickup Avise que o pedido está pronto. Ele passa para Pronto no painel da loja e o evento vira READY_FOR_PICKUP. Marca o pedido como pronto: ele passa para **Pronto** no painel da loja e o evento vira `READY_FOR_PICKUP`. Quem usa é o PDV que conduz o status do pedido no lugar da loja. Um PDV que só importa pedidos não precisa chamar, porque a loja marca no painel da Onbeef. Empresa de entregas também não chama: quem prepara o pedido é a loja. > [card] [Entenda o fluxo](/guides/order-flow) > > Veja a ordem das chamadas quando o seu sistema conduz o status do pedido. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição Envie a chamada sem corpo. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/readyForPickup" \ --header "Authorization: Bearer " ``` ## Resposta `202`, sem corpo. A resposta só diz que a chamada foi recebida. A mudança é aplicada em seguida. * **A confirmação é o evento.** Quando a mudança é aplicada, chega `READY_FOR_PICKUP` pelo webhook e pela consulta de eventos. * **Duas notificações.** Pelo webhook, o evento de uma mudança feita pela sua integração chega duas vezes. Trate como normal. * **O cliente é avisado na retirada.** Em pedido `TAKEOUT`, ele recebe a mensagem de WhatsApp de pedido pronto para retirar, quando a loja usa as mensagens automáticas. * **Dá para pular o aceite.** A chamada vale em pedido `CREATED`: ele vai direto para **Pronto**. ## Quando a mudança não é aplicada A recusa não volta na resposta e não gera evento. Se `READY_FOR_PICKUP` não chegar em cerca de 70 segundos, a mudança não foi aplicada: consulte o pedido e leia o `lastEvent`. | Motivo | O que fazer | | - | - | | O pedido já foi entregue ou cancelado. | Nada. O pedido não muda mais. | | O pedido já saiu para entrega (está **Em rota**). O status não volta. | Siga a partir do `lastEvent` atual. | | O pedido já estava **Pronto**. | Nada. Nenhum evento novo é gerado. | | Pedido de retirada pago online, com item por peso, e a loja ainda não confirmou o peso. | Peça à loja para confirmar o peso no painel da Onbeef e chame de novo. | | Pedido de retirada pago com cartão online, e o cliente ainda não fez a validação de segurança do pagamento. | A loja resolve no painel da Onbeef. Depois, chame de novo. | Os dois últimos motivos valem só em pedido `TAKEOUT`, porque nele **Pronto** é o momento em que o cliente leva o pedido. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Cancele um pedido Source: https://docs.onbeef.app/api-reference/orders/request-cancellation POST /v1/orders/{orderId}/requestCancellation Cancele um pedido que a loja não vai cumprir. A Onbeef cancela e estorna o pagamento online. Cancela o pedido na Onbeef e estorna o pagamento online. Quem usa é o PDV que conduz o status do pedido, quando a loja não vai cumprir o pedido. Um PDV que só importa pedidos não precisa chamar: a loja cancela no painel da Onbeef e você recebe `CANCELLED`. Empresa de entregas só chama a pedido da loja. > [card] [Entenda o fluxo](/concepts/orders) > > Veja o ciclo do pedido e onde o cancelamento entra. > [!WARNING] > > O cancelamento não pode ser desfeito e sempre estorna o pagamento online do cliente. Não existe cancelamento sem estorno pela API. Entrega que não deu certo (cliente ausente, endereço errado) não é motivo para chamar: avise a loja e deixe ela decidir. ## Regras * **Sem etapa de aprovação.** O pedido é cancelado direto. A Onbeef nunca pede ao seu sistema para aprovar um cancelamento. * **A loja vê o motivo.** O `code` vira o motivo do cancelamento no painel: `UNAVAILABLE_ITEM` aparece como "Item indisponível". O `reason` aparece como detalhe. * **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. * **Empresa de entregas: só a pedido da loja.** Os códigos `DELIVERY_PROBLEM` e `RESTAURANT_WITHOUT_DELIVERY_PERSON` também cancelam e estornam. Eles não registram uma tentativa de entrega. * **O estorno não aparece no pedido.** Depois do `CANCELLED`, ignore o bloco `payments` da consulta. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição **reason** `string` *required* Explicação em texto livre. A loja lê este texto no pedido cancelado. **code** `string` *required* Motivo do cancelamento. Use um destes valores: | Código | Use quando | | - | - | | `UNAVAILABLE_ITEM` | Um item do pedido está em falta. | | `DUPLICATE_APPLICATION` | O pedido veio em duplicidade. | | `RESTAURANT_WITHOUT_DELIVERY_PERSON` | A loja está sem entregador. | | `ORDER_OUTSIDE_THE_DELIVERY_AREA` | O endereço fica fora da área de entrega. | | `OUTSIDE_DELIVERY_HOURS` | O pedido chegou fora do horário de entrega. | | `RISK_AREA` | O endereço fica em área de risco. | | `DELIVERY_PROBLEM` | Houve um problema na entrega. | | `OUTDATED_MENU` | O catálogo estava desatualizado. | | `BLOCKED_CUSTOMER` | A loja não atende esse cliente. | | `INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT` | A loja teve um problema interno. | | `SYSTEMIC_ISSUES` | Houve um problema de sistema. | **mode** `string` *required* `AUTO` (cancelado pelo seu sistema) ou `MANUAL` (cancelado por uma pessoa). O campo é exigido pelo padrão Open Delivery e não muda o cancelamento. `outOfStockItems` e `invalidItems` são aceitos e ignorados. Diga no `reason` qual item faltou. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/requestCancellation" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "reason": "A picanha acabou hoje.", "code": "UNAVAILABLE_ITEM", "mode": "MANUAL" }' ``` ## Resposta `202`, sem corpo. A resposta só diz que a chamada foi recebida. O cancelamento é aplicado em seguida. 1. O evento do pedido vira `CANCELLATION_REQUESTED`, no webhook e na consulta de eventos. 2. Quando o cancelamento é aplicado, o evento vira `CANCELLED`. Pelo webhook, ele chega duas vezes: trate como normal. Considere o pedido cancelado só quando chegar `CANCELLED`. ## Quando o cancelamento não é aplicado A recusa não volta na resposta, que continua `202`. Quando a Onbeef não consegue cancelar, `CANCELLATION_REQUEST_DENIED` chega só pelo [webhook](/guides/orders-webhook), sem aparecer na consulta de eventos. | Motivo | O que fazer | | - | - | | O pagamento online ainda está sendo processado. | Espere alguns minutos e peça de novo. | | O pedido já foi entregue. | Nada pela API. O pedido continua **Entregue**. | ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `Order has already same event type` | O pedido já está cancelado. | Nada. Não repita a chamada. | | `400` | `The selected code is invalid.` | O `code` não está na lista. | Use um dos 11 códigos da tabela. | | `400` | `The reason field is required.` | Falta `reason` no corpo. Com `code` ou `mode`, a mensagem troca o nome do campo. | Envie os três campos obrigatórios. | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Valide o código de entrega Source: https://docs.onbeef.app/api-reference/orders/validate-delivery-code POST /v1/orders/{orderId}/validateCode Compara um código com o código de entrega do pedido. Hoje os pedidos não têm código de entrega e a resposta é sempre 400. Compara o código enviado com o código de entrega do pedido. Hoje este endpoint responde sempre `400` `Invalid code provided`: os pedidos da Onbeef não têm código de entrega, então nenhum código confere. Para confirmar a entrega, use [Marcar como entregue](/api-reference/orders/delivered), que não exige código. ## Parâmetros de rota **orderId** `string (uuid)` *required* O `orderId` recebido no evento. ## Corpo da requisição **deliveryCode** `string` *required* O código informado pelo cliente. ## Exemplo ```bash Ambiente de teste theme={null} curl --request POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/validateCode" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "deliveryCode": "1234" }' ``` ## Resposta ```json 400 theme={null} { "title": "Invalid code provided", "status": 400 } ``` A chamada não muda o status do pedido e não gera evento. ## Erros | Status | `title` | Motivo | O que fazer | | - | - | - | - | | `400` | `Invalid code provided` | O pedido não tem código de entrega. | Não chame. Confirme a entrega com [Marcar como entregue](/api-reference/orders/delivered). | | `404` | `Order not found` | O `orderId` não existe ou é de outra loja. | Confira o `orderId` e a URL do ambiente. | | `401` | `Token has expired` | Passaram as 12 horas de validade do token. | Peça outro em [`POST /oauth/token`](/api-reference/auth/token) e reenvie. | | `429` | `Too Many Requests` | A loja passou de 60 escritas por minuto. | Espere o tempo do header `Retry-After`. | As outras mensagens estão em [Erros e limites](/api-reference/errors). # Referência da API Source: https://docs.onbeef.app/api-reference/overview Veja as URLs, a autenticação, o formato dos dados e a lista de endpoints da Onbeef Connect API. A Onbeef Connect API é REST, no padrão [Open Delivery](https://abrasel-nacional.github.io/docs). As convenções desta página valem para todos os endpoints. ## URLs base | Ambiente | URL base | Painel da loja | | - | - | - | | [Teste (sandbox)](/environments/sandbox) | `https://api.dev.connect.onbeefapp.com.br` | [lojista.dev.onbeefapp.com.br](https://lojista.dev.onbeefapp.com.br/) | | [Produção](/environments/production) | `https://api.connect.onbeefapp.com.br` | [lojista.onbeefapp.com.br](https://lojista.onbeefapp.com.br/) | Os recursos usam o prefixo `/v1/`. O token usa `/oauth/token`, sem prefixo. A chave de um ambiente não funciona no outro. ## Autenticação Toda chamada em `/v1/` leva o token no header: ```http theme={null} Authorization: Bearer ``` O token nasce da chave da loja em [`POST /oauth/token`](/api-reference/auth/token) e vale 12 horas. A chave é por loja: o token só enxerga a loja da chave, e você não envia o id da loja. Veja [Autenticação](/authentication/overview). ## Formato dos dados | Dado | Convenção | Exemplo | | - | - | - | | Corpo | JSON em UTF-8, com `Content-Type: application/json`. Só o token aceita também formulário. | | | Data e hora | ISO 8601 em UTC. Converta para o horário da loja ao exibir. | `2026-11-12T17:30:00.000000Z` | | Dinheiro | Reais, com duas casas, com a moeda. Em `payments`, o valor vem como número. | `{ "value": 78.84, "currency": "BRL" }` | | Pedido | `id` é um UUID gerado pela Onbeef. | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | | Produto e categoria | O código é o do seu sistema, enviado como texto. | `"1001"` | * **Envie acentos em UTF-8.** Texto em outra codificação chega quebrado ao catálogo. * **Não há header de versão nem de idempotência.** Os únicos headers usados são `Authorization` e `Content-Type`. * **Os filtros de data do polling têm regra própria.** Envie `start_at` em toda consulta. Veja [Consulte eventos](/api-reference/orders/get-events). ## Respostas de sucesso | Status | Significado | Como confirmar o resultado | | - | - | - | | `200` | Concluído. O corpo traz o recurso. | A própria resposta. | | `202` | Recebido. A mudança é aplicada depois. | Nas mudanças de status do pedido, pelo evento novo. | | `204` | Recebido, sem corpo. | Na sincronização de catálogo, por `GET /v1/merchantStatus`. | `202` e `204` não dizem que a operação deu certo. Um erro de regra não volta na resposta. Veja [Deu 202 ou 204 e nada aconteceu](/api-reference/errors#deu-202-ou-204-e-nada-aconteceu). ## Erros e limites Todo erro responde no mesmo formato. Validação é `400`: não existe `422`. ```json theme={null} { "title": "Order not found", "status": 404 } ``` Os limites são por minuto: 30 pedidos de token, 200 leituras por loja e 60 escritas por loja. Acima disso a API responde `429` com o header `Retry-After`. As mensagens literais e o que fazer em cada caso estão em [Erros e limites](/api-reference/errors). ## Endpoints | Endpoint | O que faz | | - | - | | [`POST /oauth/token`](/api-reference/auth/token) | Troca a chave por um token. | | [`GET /v1/merchant`](/api-reference/merchant/get-merchant) | Lê a loja, as categorias e os produtos. | | [`PUT /v1/merchantUpdate`](/api-reference/merchant/sync-catalog) | Envia catálogo, preço e disponibilidade, e abre ou fecha a loja. | | [`GET /v1/merchantStatus`](/api-reference/merchant/get-status) | Mostra o resultado da última sincronização de catálogo. | | [`PUT /v1/merchantOnboarding`](/api-reference/merchant/update-merchant) | Cadastra a URL do webhook de pedidos. | | [`GET /v1/events:polling`](/api-reference/orders/get-events) | Lista os eventos de pedido ainda não confirmados pela chave. | | [`POST /v1/events/acknowledgment`](/api-reference/orders/confirm-events) | Confirma eventos recebidos. | | [`GET /v1/orders/{id}`](/api-reference/orders/get-order) | Lê o pedido completo. | | [`POST /v1/orders/{id}/confirm`](/api-reference/orders/confirm) | Aceita o pedido. | | [`POST /v1/orders/{id}/readyForPickup`](/api-reference/orders/ready-for-pickup) | Marca o pedido como pronto. | | [`POST /v1/orders/{id}/dispatch`](/api-reference/orders/dispatch) | Marca a saída para entrega. | | [`POST /v1/orders/{id}/delivered`](/api-reference/orders/delivered) | Marca o pedido como entregue. | | [`POST /v1/orders/{id}/requestCancellation`](/api-reference/orders/request-cancellation) | Cancela o pedido. | > [card] [Erros e limites](/api-reference/errors) > > Mensagens literais, limites por minuto e o que fazer. > [card] [Início rápido](/quickstart) > > Chave, token e primeira chamada em 10 minutos. # Autentique a integração Source: https://docs.onbeef.app/authentication/overview Troque a chave da loja por um token OAuth 2.0 e envie o token em cada chamada. Veja as regras da chave e os erros 401 e 403. A Onbeef Connect API usa OAuth 2.0 com o grant `client_credentials`. Você troca a chave da loja por um token e envia o token em cada chamada. A chave é o par **ID** e **Chave** que a loja gera no painel: o **ID** é o `client_id` e a **Chave** é o `client_secret`. ## Como funciona 1. A loja gera a chave no painel e passa o **ID** e a **Chave** para você. 2. Você envia os dois para [`POST /oauth/token`](/api-reference/auth/token) e recebe um token. 3. Você envia o token no header `Authorization: Bearer ` de cada chamada. 4. O token vale 12 horas. Perto do fim, você pede outro com a mesma chave. ### Regras * **A chave é por loja.** O token só enxerga a loja da chave, e você não informa o id da loja nas chamadas. Rede com 50 lojas tem 50 chaves. * **A chave não tem escopo.** Toda chave lê e escreve catálogo e pedidos da loja. * **Uma loja pode ter várias chaves,** uma por sistema. Webhook e confirmação de eventos são por chave. * **O limite de leitura e de escrita é por loja,** dividido entre as chaves dela. Veja [Limites](/api-reference/errors#limites). * **O token vale 12 horas.** Use o `expires_in` recebido. Não há refresh token: peça outro. * **Reaproveite o token.** O limite de 30 pedidos de token por minuto é o único dividido entre as lojas do seu servidor: guarde um token por loja, inclusive entre reinícios. * **A Chave fica no servidor.** Nunca em aplicativo, navegador ou repositório. Ela também assina o [webhook de pedidos](/guides/orders-webhook). ## Gere a chave No ambiente de teste, você gera a chave na loja de teste. Em produção, quem gera é o lojista: a Onbeef não entrega credencial de loja real. **1. Abra a tela de integrações** No painel, acesse **Configurações** > **Canais e Integrações** > **Integrações**. **2. Crie a chave** Clique no cartão **Nova chave API**, preencha o campo **Nome** e clique em **Adicionar Chave**. **3. Copie os valores** A janela **Credenciais Geradas com Sucesso!** mostra o **ID** e a **Chave** uma única vez. Copie os dois e clique em **Continuar**. * **A tela mostra Exclusivo do plano Expert:** a loja não tem o plano que libera integrações. * **O item Integrações não aparece no menu:** o usuário não tem a permissão de integrações. * **ID do Merchant não é o `client_id`.** Ele aparece no botão **Dados de Integrações**, identifica a loja e não serve para pedir token. ## Peça e envie o token ```bash Ambiente de teste theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=" \ -d "client_secret=" ``` O endpoint aceita `application/x-www-form-urlencoded` e `application/json`. Envie o `access_token` em toda chamada: ```http theme={null} Authorization: Bearer ``` ## Chave inativa ou apagada O lojista controla a chave pelo cartão dela na tela **Integrações**. | O que aconteceu | O que você recebe | Como resolver | | - | - | - | | O lojista mudou o interruptor para **Inativa**. | `403` `Integration is not active`, no pedido de token e em toda chamada. | O lojista volta para **Ativa**. A mesma chave funciona. | | A loja saiu do plano Expert. | O mesmo `403`. As chaves ficam **Inativas** sozinhas. | A loja volta ao plano e ativa a chave. | | O lojista apagou a chave (ícone de lixeira, **Apagar**). | `401` `The client credentials were incorrect.` no pedido de token. `401` `Client not found` com um token já emitido. | Não tem volta. A loja gera outra chave. | ## Erros Todo erro responde `{ "title": "...", "status": 401 }`. Decida pelo `status`. Em `401`, peça outro token e repita uma vez. Se o pedido de token também falhar, pare e avise o lojista. | Status | `title` | O que fazer | | - | - | - | | `401` | `The client credentials were incorrect.` | No pedido de token. Confira **ID**, **Chave**, `grant_type` e a URL base. | | `401` | `Token not provided`, `Invalid token` ou `Token has expired` | Envie `Authorization: Bearer `, com um token novo do mesmo ambiente. | | `401` | `Client not found` | A chave foi apagada. A loja gera outra. | | `403` | `Integration is not active` | A chave está **Inativa**. Avise o lojista e não repita em laço. | | `429` | `Too Many Requests` | Espere os segundos do header `Retry-After`. | A lista completa está em [Erros e limites](/api-reference/errors). [Ambiente trocado](/environments/sandbox#ambiente-trocado) é a causa número 1 de `401`, `404` e `500` no começo. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Referência do token](/api-reference/auth/token) > > Campos, respostas e exemplos de `POST /oauth/token`. > [card] [Início rápido](/quickstart) > > Chave, token e primeira chamada em 10 minutos. # Changelog da Onbeef Connect API Source: https://docs.onbeef.app/changelog Acompanhe mudanças na API que podem exigir ajuste na sua integração. Consulte o changelog antes de publicar uma nova versão da sua integração. Entradas marcadas com **Ação necessária** pedem mudança no seu código. Dúvidas sobre uma mudança: [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br). Mudança que pode quebrar uma integração é avisada antes, por e-mail, e fica disponível primeiro no [ambiente de teste](/environments/sandbox). **16/11/2026** Catálogo online e envio completo * **Catálogo online.** Preço, disponibilidade (`ITEM_OFFER`) e cadastro (`ITEM`) aparecem no catálogo online logo depois que o envio termina em `SUCCESS`. * **Envio completo sem `itemOfferId`.** Categoria sem a chave `itemOfferId` mantém os produtos, nada é removido e o envio termina em `FAIL`, com "... categorias recebidas sem a lista de produtos (itemOfferId) tiveram os produtos mantidos como estavam" no `moreInfo`. `itemOfferId: []` continua esvaziando a categoria. * **Produto criado no painel.** No envio completo, a lista de cada categoria substitui só os produtos com código do PDV. Produto sem código continua na categoria. **Ação necessária** se o seu envio `MERCHANT` omite `itemOfferId` em alguma categoria: envie a chave em todas. Veja [Envio completo](/guides/catalog-sync#envio-completo). **10/11/2026** Apple Pay em /v1/orders/\{orderId} Pedido pago com Apple Pay sai com `method: "CREDIT"` em `payments.methods[]`. Veja [Entenda os dados do pedido](/guides/order-data). **26/10/2026** E-mail e documento do cliente `customer.email` e `customer.documentNumber` passam a vir do cadastro do cliente naquela loja. Quando o pedido não traz o dado, a API usa o que a loja tem cadastrado para o cliente. **19/10/2026** Formas de pagamento no padrão Open Delivery `payments.methods[].method` passa a usar um código próprio para cada forma de pagamento: | Forma de pagamento | Antes | Agora | | - | - | - | | Cartão de débito | `CREDIT` ou `OTHER` | `DEBIT` | | Vale alimentação | `OTHER` | `FOOD_VOUCHER` | | Vale refeição | `OTHER` | `MEAL_VOUCHER` | | Boleto, pagamento a prazo, link de pagamento | `OTHER` | `OTHER`, com o nome em `methodInfo` | > [!WARNING] > > **Ação necessária** se a sua integração mapeia `method` para as formas de pagamento do seu sistema: inclua `DEBIT`, `FOOD_VOUCHER` e `MEAL_VOUCHER`, e leia `methodInfo` quando o método for `OTHER`. Veja [Entenda os dados do pedido](/guides/order-data). **21/08/2026** Desconto dado pela loja no total do pedido O desconto que a loja aplica no campo **Desconto personalizado** (em **adicionar desconto**, no detalhe do pedido, e na criação do pedido pela loja) passa a aparecer em `discounts` e a entrar em `total.discount`. Antes, o pedido saía sem esse desconto. **Ajustar valor** não está incluído: o desconto dado por esse botão continua fora da API. Veja [Quando importar o pedido](/guides/order-import). **07/08/2026** Padronização das respostas de erro Todas as respostas de erro passam a usar o mesmo formato: ```json theme={null} { "title": "Descrição do erro", "status": 400 } ``` * Antes, alguns erros usavam `error` ou `message` no lugar de `title`. * Erros de validação, que em alguns casos retornavam `500`, agora retornam `400` com a descrição do campo (`"The ordersWebhookURL field is required."`). * Credenciais inválidas e tokens malformados retornam `401`. * O `429` também passa a usar `title`. > [!WARNING] > > **Ação necessária** se a sua integração lê `error` ou `message` nas respostas de erro: passe a ler `title` e `status`. Veja [Erros e limites](/api-reference/errors). **07/08/2026** Onboarding e status sem merchantId * `PUT /v1/merchantOnboarding` não recebe mais `merchantId`: a loja é identificada pela credencial do token. O campo `getMerchantURL` deixou de ser obrigatório. * `GET /v1/merchantStatus` também não precisa mais de `merchantId`. Veja [Cadastre o webhook de pedidos](/api-reference/merchant/update-merchant) e [Consulte a sincronização](/api-reference/merchant/get-status). **07/08/2026** Catálogo e status do lojista em /v1/merchantUpdate * `merchantStatus` só é exigido quando `entityType` é `MERCHANT`. * O tipo do produto (`KG`, `UN` ou `KIT`) não muda mais depois de criado. Antes, o campo `unit` de um `ITEM` ou `MERCHANT` podia converter um kit ou um produto por peso em unidade. * `ITEM_OFFER` passa a aplicar o status da oferta à disponibilidade do produto: `AVAILABLE` disponibiliza e `UNAVAILABLE` indisponibiliza. Antes, o status era ignorado. * Alterações de `ITEM` e `ITEM_OFFER` aparecem na hora em `GET /v1/merchant`, sem esperar o cache. * Em `GET /v1/merchant`, produto ou categoria com status desconhecido volta como `UNAVAILABLE`, em vez de interromper a resposta. Veja [Sincronize o catálogo](/api-reference/merchant/sync-catalog). **07/08/2026** Motivo de cancelamento por falta de entregador `RESTAURANT_WITHOUT_DELIVERY_PERSON` agora aparece no painel da loja como "Loja sem motoboy". Antes, o cancelamento era registrado com o motivo genérico. Não é preciso mudar nada na sua integração. Veja [Cancele um pedido](/api-reference/orders/request-cancellation). **07/08/2026** Coordenadas numéricas em /v1/orders/\{orderId} `delivery.deliveryAddress.coordinates.latitude` e `longitude` passam de texto para número. ```json theme={null} { "coordinates": { "latitude": -16.7190445, "longitude": -49.2610131 } } ``` > [!WARNING] > > **Ação necessária** se a sua integração espera esses campos como texto: ajuste a desserialização. **21/07/2026** Totais e valores dos pedidos **Cálculo dos totais.** `itemsPrice` passou a ser a soma dos itens. Antes, ele era calculado a partir do saldo final e podia absorver o desconto. ```text theme={null} itemsPrice = soma dos itens orderAmount = itemsPrice + otherFees - discount ``` **Duas casas decimais.** Todos os valores monetários são arredondados para duas casas (`HALF_UP`), e o mesmo valor aparece no total, no pagamento pendente e nos métodos de pagamento. Antes, alguns valores vinham como `652.4313999999999`. **Nome do campo `target`.** O `target` dos descontos era enviado como `"target "`, com um espaço no fim. Agora segue o nome do Open Delivery. Veja [Consulte um pedido](/api-reference/orders/get-order). **16/07/2026** Código do PDV na categoria A categoria que já existe na Onbeef passa a aceitar o **Código de integração com PDV**, preenchido pelo lojista na edição da categoria. Com o código, a sincronização reconhece a categoria e cria os produtos nela, em vez de criar outra com o mesmo nome. Veja [Loja que já tem produtos](/guides/catalog-linking). **15/07/2026** Motivo da falha da sincronização Quando uma sincronização de catálogo falha, `GET /v1/merchantStatus` traz o motivo em `moreInfo`. O lojista vê o mesmo texto no cartão **Status da Integração PDV**, na tela **Integrações**. Veja [Consulte a sincronização](/api-reference/merchant/get-status). **25/09/2025** Datas em UTC Os campos de data e hora (`createdAt`, `preparationStartDateTime`, `scheduledDateTimeStart`, `scheduledDateTimeEnd`, `estimatedDeliveryDateTime`, `deliveryDateTime` e os demais) passam a ser retornados em UTC. Antes, vinham no horário local com o sufixo `Z`. | Antes | Agora | | - | - | | `2025-07-09T10:30:30.000000Z` | `2025-07-09T13:30:30.000000Z` | > [!WARNING] > > **Ação necessária** se a sua integração usava o valor direto como horário local: converta de UTC para o fuso da loja. **28/08/2025** Ajustes no retorno de /v1/orders/\{orderId} * `deliveredBy` retorna `MERCHANT` quando a loja escolhe um entregador próprio. Antes era sempre `MARKETPLACE`. * `preparationStartDateTime` considera o agendamento do pedido e, sem agendamento, a hora atual. Antes era sempre a hora atual mais 60 minutos. * `schedule` retorna os horários corretos. Antes vinham com 3 horas a mais. * `estimatedDeliveryDateTime` considera o agendamento; sem ele, usa o tempo mínimo da loja ou 30 minutos após a criação. * `takeoutDateTime` traz a retirada agendada, quando houver. * `deliveryDateTime` traz a data da entrega depois que o pedido chega a `DELIVERED`. * `sponsorshipValues` passa a ser um array, como no Open Delivery. * `total.discount` traz o valor real dos descontos. Antes era sempre `0`. * Itens: `kit_id` usa o mesmo identificador do PDV que o `id` do kit; `extraInfo` foi renomeado para `specialInstructions`; novo `originalPrice` com o preço sem desconto; `unitPrice` e `totalPrice` passam a vir com desconto; `options` inclui os cortes das carnes. # Como o catálogo funciona Source: https://docs.onbeef.app/concepts/merchant Entenda loja, categoria, produto e oferta nesta API, o que fica só no painel e qual código liga o seu PDV à Onbeef. O catálogo é a lista de produtos que o cliente vê na loja online. O seu PDV envia categorias, produtos e preços, em mão única: o que o lojista muda no painel não volta para o PDV. ## As quatro peças | Peça | O que é | No envio | | - | - | - | | Loja | O açougue da chave. | `updatedObjects[0].id` e `merchantStatus` | | Categoria | Um grupo de produtos: Bovinos, Bebidas. | `categories[]` | | Produto | O que a loja vende, com nome, unidade e foto. | `items[]` | | Oferta | O preço e a disponibilidade de um produto. | `itemOffers[]` | A oferta liga o produto à categoria. O produto só entra no catálogo quando a ligação fecha: ```text theme={null} categories[].itemOfferId[] aponta para itemOffers[].id itemOffers[].itemId aponta para items[].id ``` O `merchantStatus` abre (`AVAILABLE`) ou fecha (`UNAVAILABLE`) a loja para pedidos, na hora, em todo envio `MERCHANT`. Veja a [regra do `merchantStatus`](/guides/catalog-sync#regras). ## Produto por quilo e por unidade * **`"KG"`:** venda por peso (picanha, costela). O `price.value` é o preço de 1 quilo. * **`"UN"`:** venda por unidade (carvão, refrigerante). O `price.value` é o preço de 1 unidade. * **Só em maiúsculas.** Outro valor, ou sem o campo, o produto nasce por unidade: o preço do quilo vira o preço da unidade. * **O tipo não muda.** Depois de criado, o `unit` enviado é ignorado, e o preço é gravado no tipo que o produto já tem. Confira o `unit` em `GET /v1/merchant` antes de vincular. * **Produto por quilo nasce com o corte "Peça",** de 1 kg estimado. O lojista ajusta no painel. ## O que fica só no painel A API não cria nem altera: * **Cortes e temperos.** Lidos em `GET /v1/merchant` (`cuts[]`) e no pedido (`items[].options[]`), com o mesmo `id`. * **Complementos, kits e horários.** Os blocos `optionGroups`, `availabilities` e `services` são aceitos e ignorados. * **Promoções.** O `price.value` é sempre o preço cheio, e `price.originalValue` é ignorado. * **Estoque.** Acabou: `UNAVAILABLE`. * **Nome e ordem das categorias.** `name` e `index` valem só na criação. ## Identificadores Produto e categoria são localizados só pelo **Código de integração com PDV**. | Dado | No envio | Na tela da Onbeef | Em `GET /v1/merchant` | No pedido | | - | - | - | - | - | | Código do produto no PDV | `items[].id` e `itemId` | **Código de integração com PDV** | `products[].pdv_external_id` | `items[].id` | | Código de balança | `items[].externalCode` | **Código da balança** | `products[].externalCode` | `items[].externalCode` | | Código da categoria no PDV | `categories[].id` | **Código de integração com PDV** | `categories[].pdv_external_id` | Não vem | | Código da loja no PDV | `updatedObjects[0].id` | Não aparece | Não vem | `merchant.id` | | Id interno da Onbeef (UUID) | Não é aceito | Não aparece | `id` | Não vem | * **Envie o `id` sempre como texto.** `"1001"`, não `1001`. * **Use um id estável na categoria,** nunca o nome: se ele mudar, a Onbeef cria outra categoria. * **`externalCode` é o código de balança.** Se você envia, ele substitui o que o lojista digitou. * **O `itemOffers[].id` só vale dentro do envio.** Ele liga a oferta à categoria e não é guardado. * **Você escolhe o código da loja.** Use sempre o mesmo. * **Item de pedido com UUID no `id` é produto sem código.** Veja [Loja que já tem produtos](/guides/catalog-linking). ## O que cada envio sobrescreve O que o próximo envio faz com o que o lojista editou ("se vier": sobrescreve quando o campo é enviado). | O que o lojista editou | `MERCHANT` | `ITEM` | `ITEM_OFFER` | | - | - | - | - | | Preço | Sobrescreve | Não mexe | Sobrescreve | | Produto ativo ou desativado | Se vier `status` | Se vier `status` | Se vier `status` | | Nome do produto | Mantém | Sobrescreve sempre | Não mexe | | Descrição | Só preenche se estiver vazia | Se vier | Não mexe | | Código da balança e porção (`serving`) | Se vier | Se vier | Não mexe | | Foto | Troca a do PDV. As do painel ficam. | O mesmo | Não mexe | | Nome e ordem da categoria, cortes, horários e promoções | Mantém | Não mexe | Não mexe | | Produtos dentro de uma categoria enviada | Substitui os que têm código do PDV, só no [envio completo](/guides/catalog-sync#envio-completo). Os criados no painel, sem código, ficam. | Não mexe | Não mexe | Por isso, omita `status` quando a disponibilidade não mudou no PDV: `AVAILABLE` reativa o produto que o lojista desativou. E, para trocar só a foto ou a descrição com `ITEM`, envie o nome lido em `GET /v1/merchant`. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Sincronizar catálogo](/guides/catalog-sync) > > O que enviar em cada situação. > [card] [Loja que já tem produtos](/guides/catalog-linking) > > Vincule pelo código do PDV, sem duplicar. # Como um pedido funciona Source: https://docs.onbeef.app/concepts/orders Veja o caminho do pedido na entrega e na retirada, os eventos que você recebe e quem muda cada status. O pedido nasce na Onbeef, quando o cliente compra no catálogo online ou a loja lança no painel. A API avisa o seu sistema a cada mudança de status. ## O caminho do pedido ```mermaid theme={null} flowchart LR A["CREATED
Pendente"] --> B["CONFIRMED
Em preparo"] B --> C["READY_FOR_PICKUP
Pronto"] C -->|Entrega| D["DISPATCHED
Em rota"] D --> E["DELIVERED
Entregue"] C -->|Retirada| E ``` O pedido só anda para a frente e pode pular etapas: de **Pendente** direto para **Pronto**, por exemplo. Não espere receber todos os eventos, nem em ordem. ## Eventos e status Um evento é um aviso de que o pedido mudou: chegou, ficou pronto, foi cancelado. | Evento | Status no painel | O que significa | | - | - | - | | `CREATED` | Pendente | O pedido chegou e espera a loja aceitar. | | `CONFIRMED` | Em preparo | A loja aceitou. | | `READY_FOR_PICKUP` | Pronto | A loja separou e pesou. | | `DISPATCHED` | Em rota | Saiu para entrega. Só em entrega (`type: DELIVERY`): a retirada (`TAKEOUT`) pula esta etapa. | | `DELIVERED` | Entregue | O cliente recebeu ou retirou. Final. | | `CANCELLED` | Cancelado | Final. | | `CANCELLATION_REQUESTED` | Não muda | O seu sistema pediu o cancelamento. | | `CANCELLATION_REQUEST_DENIED` | Não muda | A Onbeef não conseguiu cancelar. Chega só pelo webhook. | ### Regras * **O evento é o estado atual, não um histórico.** Cada pedido tem um evento por vez: o novo substitui o anterior. Se a loja aceita antes da sua consulta, você vê só o `CONFIRMED`. * **Evento não confirmado não expira.** Ele fica na consulta até ser confirmado ou até o pedido mudar de evento. * **A identidade do evento é o par `orderId` + `eventId`.** O `eventId` identifica o tipo do evento e é igual em todos os pedidos. * **`createdAt` é a criação do pedido.** O evento não tem data própria. * **Ajuste de item, peso ou valor não gera evento.** Veja [Quando importar o pedido](/guides/order-import). ## Quando o pedido aparece | Situação | Quando o `CREATED` aparece | | - | - | | Pagamento na entrega | Na hora. | | Cartão pelo catálogo online | Na hora, se o cartão foi autorizado. Cartão recusado não gera pedido. | | PIX pelo catálogo online | Só depois que o cliente paga. PIX vencido nunca aparece. | | Pedido lançado pela loja em **Painel de Vendas** > **Novo pedido** | Na hora. | Rascunho e venda do tablet de fidelidade não geram evento. ### Pago ou a cobrar Em `payments.methods[]`, `PREPAID` é pedido já pago: não cobre. `PENDING` é pedido não pago, inclusive cartão online ainda não capturado. `OTHER` (fiado, link, boleto) nunca se cobra na porta. A API não separa pagamento na entrega de pagamento online em andamento: veja [Pagamento](/guides/order-data#pagamento). ## Quem muda o status | Quem | Como | | - | - | | A loja | Painel da Onbeef. | | O seu sistema | [Ações de status](/guides/order-flow#se-o-seu-sistema-conduz-o-status), se você conduz o pedido. | | A empresa de entregas da loja | `dispatch` e `delivered`, pela [integração de entregas](/guides/delivery-flow). | Toda chave da loja recebe o mesmo evento. Para PDV e ERP, a Onbeef recomenda que a loja conduza o pedido e o seu sistema só leia: veja [Quando importar o pedido](/guides/order-import). ## Cancelamento A loja cancela pelo painel antes de **Entregue**, inclusive **Em rota**, e você recebe `CANCELLED`. A Onbeef nunca pede ao seu sistema para aprovar um cancelamento. Pedido **Entregue** só o suporte da Onbeef cancela, a pedido da loja: chega `CANCELLED` depois do `DELIVERED`. Para cancelar pelo seu sistema: ```bash Ambiente de teste theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}/requestCancellation \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "reason": "Acabou a picanha", "code": "UNAVAILABLE_ITEM", "mode": "AUTO" }' ``` A resposta é `202`. O pedido passa por `CANCELLATION_REQUESTED` e termina em `CANCELLED`. A loja vê o motivo (`code`) e o detalhe (`reason`). A lista de códigos está em [Cancelar pedido](/api-reference/orders/request-cancellation). > [!WARNING] > > Cancelar pela API estorna o pagamento online do cliente. Não existe cancelamento sem estorno. * **Pedido já entregue.** 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. * **`CANCELLATION_REQUEST_DENIED`.** A Onbeef não conseguiu cancelar, como no pagamento online em processamento: envie o cancelamento de novo. Chega só pelo webhook, não entra no polling nem precisa de confirmação. * **Entrega frustrada não é cancelamento.** Empresa de entregas só cancela se a loja pedir. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Receba pedidos](/guides/order-flow) > > Webhook, polling e confirmação. > [card] [Quando importar o pedido](/guides/order-import) > > O ponto certo para faturar. # Consulte pedidos antigos Source: https://docs.onbeef.app/concepts/orders-history Use o polling com filtro de data para a carga inicial e para relatórios, com uma chave que não confirma eventos. A API não tem listagem de pedidos. Para carregar um período, use o polling do dia a dia com filtro de data e sem confirmar os eventos. ## Quando usar | Situação | O que fazer | | - | - | | Carga inicial ou relatório de um período | Consulte com `start_at` e `end_at`, sem confirmar, com uma chave só para isso. | | Um pedido que você já conhece | `GET /v1/orders/{orderId}` responde para qualquer pedido da loja, de qualquer data. | ## Como funciona 1. Você consulta `GET /v1/events:polling` com `start_at` e `end_at`. 2. A API devolve um item por pedido criado no período, com o evento atual dele, não os status pelos quais ele passou. 3. Para cada item, você consulta `GET /v1/orders/{orderId}` e grava pelo `id`: se o pedido já existe no seu sistema, atualize. 4. Você não confirma os eventos: a mesma consulta devolve os mesmos pedidos amanhã. ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-07-01&end_at=2026-07-31" \ -H "Authorization: Bearer " ``` ### Regras * **O filtro é pela criação do pedido**, não pela data do evento nem da entrega. Pedido criado no dia 21 e agendado para o dia 22 entra no dia 21: leia a entrega em `schedule`. * **`Y-m-d` é o dia inteiro, no horário de Brasília**, qualquer que seja o fuso da loja. `start_at=2026-07-01` começa às 00:00:00 e `end_at=2026-07-31` termina às 23:59:59. Os dois limites entram no resultado. * **`Y-m-d H:i` é lido como UTC.** `start_at=2026-07-01 00:00` filtra a partir de 21:00 do dia 30 de junho, em Brasília. Na URL, o espaço vira `%20`: `2026-07-01%2000:00`. * **Até 1000 pedidos, dos mais antigos para os mais novos**, depois dos filtros, sem paginação nem aviso de corte. Vieram 1000 itens: divida o período. * **Evento confirmado não volta**, nem com filtro de data. Se você guardou o `id`, consulte o pedido direto. Senão, peça à loja outra chave. * **Espalhe as consultas.** A loja tem 200 leituras por minuto, divididas entre todas as chaves. Para 1000 pedidos, use pelo menos 10 minutos. ### O que não aparece Pedido com PIX online não pago e venda do tablet de fidelidade. Pedido criado antes de dezembro de 2024 pode não aparecer. O histórico de um cliente importado de outro sistema aparece como um pedido `DELIVERED`, com `salesChannel: "IMPORT_CUSTOMER"`, a data original e sem itens. Não fature. ## Use uma chave só para consulta A confirmação vale só para a chave que confirmou: operar e consultar pedidos antigos pedem chaves diferentes. | Chave | Confirma eventos? | Resultado | | - | - | - | | Operação (PDV, entregas) | Sim, depois de gravar. | O polling traz só o que falta processar. | | Consulta (relatório, BI, CRM) | Nunca. | O polling com data traz todos os pedidos do período, mesmo os anteriores à chave. | A loja gera cada chave em **Configurações** > **Canais e Integrações** > **Integrações**, no cartão **Nova chave API**. ## Chave nova em loja com histórico O polling devolve todo pedido cujo evento atual a chave ainda não confirmou. Evento não confirmado não expira: em uma loja com anos de pedidos, uma chave sem filtro não chega aos pedidos de hoje. 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. ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-11-13" \ -H "Authorization: Bearer " ``` ### Pedido agendado O filtro é pela data de criação. Pedido feito antes da data do `start_at` e entregue depois não aparece: no dia da virada, recue o `start_at` 7 dias e ignore o pedido que já estava entregue antes da virada. * **Entrega.** Ignore o pedido com `delivery.deliveryDateTime` anterior à data da virada. * **Retirada.** A data em que o cliente retirou não vem na API: combine com a loja. O pedido agendado traz `orderTiming: "SCHEDULED"` e a janela em `schedule`. A previsão da retirada vem em `takeout.takeoutDateTime`. ## Cargas repetidas * **Releia os dias que ainda têm pedido aberto.** Pedido criado ontem e cancelado hoje não entra na consulta só de hoje. Consulte o período até todos os pedidos chegarem a `DELIVERED` ou `CANCELLED`, e sobrescreva pelo `id`. * **Para valores finais, espere o `DELIVERED`.** Peso e total mudam sem evento: veja [Quando importar o pedido](/guides/order-import). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Receba pedidos](/guides/order-flow) > > O polling do dia a dia. > [card] [Consultar eventos](/api-reference/orders/get-events) > > Referência de `GET /v1/events:polling`. # Comece aqui Source: https://docs.onbeef.app/desenvolvedores Escolha o tipo de sistema, veja o que a API faz e não faz e chegue à primeira chamada. A Onbeef Connect API liga o sistema da loja à Onbeef: catálogo, pedidos e entregas. É uma API REST no padrão [Open Delivery](https://abrasel-nacional.github.io/docs), nas partes de catálogo e de pedidos, aberta a qualquer integrador e sem custo pela integração. Você é lojista e não vai programar? Vá para [Para lojistas](/lojistas/overview). ## Escolha o seu sistema PDV ou ERP Mantém preço e disponibilidade do catálogo online e importa o pedido fechado para faturar. Integrar PDV ou ERP → [Open](/desenvolvedores/pdv) Empresa de entregas Recebe os eventos dos pedidos da loja, chama o entregador e informa a saída e a entrega. Integrar entregas → [Open](/desenvolvedores/logistica) O seu sistema é um CRM, um atendimento ou um agente de IA? Veja [Outros sistemas](#outros-sistemas). Integre meu sistema com a Onbeef Connect API seguindo [https://docs.onbeef.app/desenvolvedores.md](https://docs.onbeef.app/desenvolvedores.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## A API em 30 segundos ### O que ela faz * **Catálogo, do seu sistema para a Onbeef.** Cria e atualiza categorias, produtos, preço e disponibilidade. Abre e fecha a loja. * **Pedidos, da Onbeef para o seu sistema.** Avisa de cada pedido novo e de cada mudança de status. Entrega o pedido completo: itens, pesos, totais, pagamento, cliente e endereço. * **Status e cancelamento, do seu sistema para a Onbeef.** Aceita o pedido, marca como pronto, em rota e entregue, ou cancela. ### O que ela não faz * **Criar pedido.** A Onbeef é a origem do pedido: ele nasce no catálogo online ou no painel da loja. * **Alterar itens, peso ou valor de um pedido.** A API recebe só status e cancelamento. * **Levar estoque, promoção, cortes, kits ou clientes.** Tudo isso fica no painel da Onbeef. * **Avisar o seu sistema de mudanças de catálogo feitas no painel.** O catálogo é mão única: do seu sistema para a Onbeef. * **Homologação.** Terminou de testar, a integração já pode ser ativada em lojas. A lista completa está nas [Perguntas frequentes](/desenvolvedores/faq). ### Regras * **Uma chave por loja.** A chave é o par **ID** e **Chave** que a loja gera no painel. Rede com 50 lojas tem 50 chaves. * **`202` e `204` são recebimento, não resultado.** O resultado chega depois, num evento do pedido ou no status da sincronização. Veja [Deu 202 ou 204 e nada aconteceu](/api-reference/errors#deu-202-ou-204-e-nada-aconteceu). * **O mesmo evento pode chegar mais de uma vez.** Um evento é um aviso de que o pedido mudou: chegou, ficou pronto, foi cancelado. Identifique cada um pelo par `orderId` + `eventId`. * **Erro sempre no mesmo formato.** Todo erro responde `{ "title": "...", "status": 400 }`. Decida pelo `status`. * **`start_at` em toda consulta de eventos.** Sem ele, a consulta devolve primeiro os pedidos mais antigos da loja. * **A loja precisa do plano Expert.** Se a loja sai do plano, as chaves dela ficam inativas. ## Primeiros passos **1. Peça uma loja de teste** Escreva para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br). A Onbeef cria a loja no ambiente de teste (sandbox) e envia o login do painel. Veja [Ambiente de teste](/environments/sandbox). **2. Faça a primeira chamada** Gere a chave no painel de teste, peça o token e consulte a loja. O [Início rápido](/quickstart) leva 10 minutos. **3. Siga o roteiro do seu sistema** [PDV ou ERP](/desenvolvedores/pdv) ou [empresa de entregas](/desenvolvedores/logistica). Cada roteiro diz o que implementar e em que ordem. **4. Passe para produção** Troque a URL e a chave, cadastre o webhook de novo se você usa e confira o [checklist de produção](/environments/production#checklist). ## Outros sistemas CRM, atendimento e agente de IA usam a mesma API e o mesmo tipo de chave. O que dá para ler: * **Catálogo e preços.** `GET /v1/merchant` traz categorias, produtos, preço e cortes. * **Pedidos e clientes.** Receba os eventos por [webhook](/guides/orders-webhook) ou polling e busque o pedido em `GET /v1/orders/{id}`. Os dados do cliente vêm dentro do pedido. * **Pedidos anteriores à integração.** Veja [Consulte pedidos antigos](/concepts/orders-history). Peça à loja uma chave só para o seu sistema. Webhook e confirmação de eventos são por chave: você confirma os seus eventos sem tirar nada da integração do PDV. Não dá para criar pedido pela API. Pedido que nasce no WhatsApp ou no telefone é lançado pela loja no painel, em **Painel de Vendas** > **Novo pedido**, e chega à API como qualquer outro. ## Precisa de ajuda? Dúvida técnica vai por e-mail para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br). Envie o endpoint, o payload, o `id` do pedido e o horário da chamada. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Início rápido](/quickstart) > > Chave, token e primeira chamada em 10 minutos. > [card] [Autenticação](/authentication/overview) > > Como a chave funciona e como tratar 401 e 403. > [card] [Ambiente de teste](/environments/sandbox) > > Loja de teste, pedidos de teste e o que testar. > [card] [Perguntas frequentes](/desenvolvedores/faq) > > As dúvidas que os integradores mais mandam. # Perguntas frequentes Source: https://docs.onbeef.app/desenvolvedores/faq 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](/quickstart). 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](/authentication/overview). > [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](/api-reference/errors#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](/environments/sandbox#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](/authentication/overview#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](/guides/order-import). > [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](/concepts/orders-history). ## 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](/guides/catalog-sync). > [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](/guides/catalog-sync#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](/guides/catalog-linking). > [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](/guides/catalog-sync#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](/guides/orders-webhook) 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](/guides/orders-webhook). > [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](/guides/order-import). > [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](/api-reference/errors#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`](/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](/guides/delivery-flow). > [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](/environments/production#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](/api-reference/errors#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](/changelog). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Comece aqui](/desenvolvedores) > > O roteiro por tipo de sistema. > [card] [Erros e limites](/api-reference/errors) > > Mensagens literais, limites por minuto e o que fazer. # Integre uma empresa de entregas Source: https://docs.onbeef.app/desenvolvedores/logistica Receba os eventos dos pedidos da loja com uma chave gerada por ela, chame o entregador e informe a saída e a entrega. A empresa de entregas usa a mesma API de pedidos do PDV, com uma chave gerada pela loja, sem ativação com a Onbeef. É a parte de pedidos do padrão Open Delivery, não a de logística. Integre meu sistema de entregas com a Onbeef Connect API seguindo [https://docs.onbeef.app/desenvolvedores/logistica.md](https://docs.onbeef.app/desenvolvedores/logistica.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Como funciona 1. A loja gera uma chave no painel e envia o **ID** e a **Chave** para você. 2. 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. 3. Você consulta o pedido em `GET /v1/orders/{id}`: endereço em `delivery.deliveryAddress`, cliente e pagamento. 4. Você chama o entregador no evento `CONFIRMED` (a loja aceitou) ou `READY_FOR_PICKUP` (o pedido está pronto). 5. Antes de o entregador sair, você consulta o pedido de novo: o peso e o valor a cobrar mudam sem evento. 6. O entregador saiu: chame `dispatch`. O pedido fica **Em rota** e o cliente recebe a mensagem de WhatsApp de saída. 7. 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_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. * **Pedido agendado.** Traz `orderTiming: "SCHEDULED"` e a janela em `schedule`. Não há evento no dia: o sinal continua sendo `CONFIRMED` e `READY_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ó 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. * **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 `confirm` nem `readyForPickup`.** Quem aceita e prepara é a loja. * **Só chame `dispatch` depois de `READY_FOR_PICKUP`.** No mínimo, depois de `CONFIRMED`. A API aplica o `dispatch` mesmo em pedido que a loja ainda não aceitou. * **`202` não é confirmação.** A confirmação é o evento `DISPATCHED` ou `DELIVERED`. Sem ele em cerca de 70 segundos, a mudança não foi aplicada e não há aviso de erro: consulte o pedido. `lastEvent` e `type` mostram 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 do `Retry-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](mailto: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](/quickstart). **2. Receba os pedidos** Cadastre o [webhook de pedidos](/guides/orders-webhook) 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](/guides/delivery-flow). A referência está em [`dispatch`](/api-reference/orders/dispatch) e [`delivered`](/api-reference/orders/delivered). **4. Passe para produção** Confira o [checklist de produção](/environments/production#checklist). Em produção, quem gera a chave é o lojista. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Integre as entregas](/guides/delivery-flow) > > O passo a passo, do pedido recebido à entrega. > [card] [Webhook de pedidos](/guides/orders-webhook) > > Receba os eventos no seu servidor em tempo real. # Integre um PDV ou ERP Source: https://docs.onbeef.app/desenvolvedores/pdv Mantenha o catálogo online igual ao do PDV e importe o pedido fechado para faturar. Veja o modelo recomendado e o roteiro. A integração de PDV ou ERP tem dois objetivos: manter preço e disponibilidade do catálogo online iguais aos do PDV e levar o pedido da Onbeef para o PDV faturar. Você pode implementar só um dos dois ou os dois. Integre meu PDV com a Onbeef Connect API seguindo [https://docs.onbeef.app/desenvolvedores/pdv.md](https://docs.onbeef.app/desenvolvedores/pdv.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## O que a integração faz | | Direção | Resultado para a loja | | - | - | - | | **Catálogo** | PDV → Onbeef | Preço mudou ou produto acabou no PDV: o catálogo online acompanha. Produto novo no PDV entra na Onbeef. | | **Pedidos** | Onbeef → PDV | O pedido feito na Onbeef entra no PDV com itens, pesos, totais, pagamento e cliente, pronto para faturar. | ## O modelo recomendado **A loja opera o pedido na Onbeef e o PDV importa o pedido fechado.** É a posição oficial da Onbeef para PDV e ERP. 1. O cliente pede no catálogo online. 2. A loja aceita, pesa, ajusta e entrega o pedido pelo painel da Onbeef. 3. O PDV consulta os eventos no polling a cada 30 segundos, sempre com `start_at`. O webhook é opcional, para tempo real. 4. No evento `DELIVERED`, o PDV busca o pedido em `GET /v1/orders/{id}`, fatura e confirma o evento. Nesse modelo o PDV só lê e confirma eventos. Ele não chama `confirm`, `readyForPickup`, `dispatch` nem `delivered`. ### Por que importar o pedido fechado * **Carne é vendida por peso.** O cliente pede 1 kg, a loja pesa 1,080 kg, e o pedido muda depois de criado. * **Ajuste de item ou peso não gera evento.** O PDV só vê o peso novo se consultar o pedido de novo. * **`DELIVERED` é o único ponto em que o pedido não muda mais.** Antes disso a loja ainda pode ajustar. * **A API não recebe ajuste vindo do PDV.** Mudou item, peso ou valor no PDV: não muda na Onbeef, e os pontos de fidelidade do cliente ficam errados. A loja ajusta na Onbeef, em **Ajustar o pedido** ou bipando a etiqueta da balança no pedido. > [!WARNING] > > Não fature antes do `DELIVERED`. No `CREATED`, quantidade e total são provisórios até a loja confirmar o peso. Caso real: um PDV consultou o pedido 1 minuto depois do Pronto, a loja pesou 14 minutos depois (0,720 kg virou 0,600 kg) e o cupom saiu com o peso errado. O PDV precisa do pedido antes da entrega, para separação ou expedição? Aceite `READY_FOR_PICKUP`, `DISPATCHED` ou `DELIVERED` como gatilho, o que chegar primeiro, acompanhe o `CANCELLED` e consulte de novo no `DELIVERED` antes de faturar. O guia [Quando importar o pedido](/guides/order-import) traz a tabela. Prefere que o PDV conduza o status do pedido? Esse é o modelo alternativo: veja [Receba pedidos](/guides/order-flow). ## O que a integração não faz * **Criar pedido na Onbeef.** A Onbeef é a origem do pedido. * **Alterar itens, peso ou valor de um pedido.** A API recebe só status e cancelamento. * **Trazer o desconto de Ajustar valor.** Para dar desconto num pedido, a loja integrada usa **Desconto personalizado**, que vem em `discounts`. **Ajustar valor** não vem na API. * **Enviar vendas do balcão ou clientes para a Onbeef.** * **Levar pontos de fidelidade de um sistema para o outro.** 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. * **Levar estoque.** A API não envia nem recebe estoque. Produto acabou: marque como indisponível com `ITEM_OFFER` e `status: "UNAVAILABLE"`. * **Criar ou marcar promoção.** `price.originalValue` é ignorado. Promoção é manual no painel. * **Sincronizar cortes, temperos, complementos e horários, ou criar kit.** Ficam no painel da Onbeef. * **Avisar o PDV de mudança de catálogo feita no painel.** O catálogo é mão única, do PDV para a Onbeef. A leitura é `GET /v1/merchant`. * **Listar pedidos.** Só os eventos trazem o `id` de cada pedido. ## Loja que já tem produtos na Onbeef O vínculo entre o produto do PDV e o da Onbeef é só pelo **Código de integração com PDV**, em produto e em categoria. Sem o código, a sincronização cria outro produto e outra categoria: a loja fica com item duplicado e categoria vazia. Antes da primeira sincronização de uma loja que já vende, passe os códigos para o lojista preencher. Veja [Vincule uma loja que já tem produtos](/guides/catalog-linking). ## 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](/quickstart). **2. Sincronize o catálogo** Leia [Como o catálogo funciona](/concepts/merchant) e siga [Sincronize o catálogo](/guides/catalog-sync). O guia traz a tabela "o que aconteceu no PDV, o que enviar". No envio `MERCHANT`, leia antes `status` em `GET /v1/merchant` e reenvie o mesmo valor em `merchantStatus`. **3. Receba os pedidos** Leia [Como um pedido funciona](/concepts/orders) e ligue o polling: é ele que garante que nenhum pedido se perde. Envie `start_at` em toda consulta, fixo na data em que a integração começou a valer na loja. O [webhook de pedidos](/guides/orders-webhook) é opcional. **4. Importe o pedido no ponto certo** Siga [Quando importar o pedido](/guides/order-import) e use [Entenda os dados do pedido](/guides/order-data) para mapear itens, totais e pagamento. **5. Passe para produção** Confira o [checklist de produção](/environments/production#checklist). Não há homologação. **6. Oriente o seu lojista** Quem explica a integração para a loja é você: de onde vêm os códigos, que o pedido só entra no PDV depois de marcado como **Entregue** (inclusive retirada) e o que ajustar na Onbeef. As páginas [Ative a integração](/lojistas/ativar) e [Vincule os produtos](/lojistas/vincular-produtos) ajudam. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Sincronize o catálogo](/guides/catalog-sync) > > O que enviar em cada situação, com payload mínimo. > [card] [Quando importar o pedido](/guides/order-import) > > Quando importar e como lidar com o ajuste de peso. # Passe para produção Source: https://docs.onbeef.app/environments/production Troque a URL e a chave, cadastre o webhook de novo, confira o checklist e ative a integração em lojas reais. Não há homologação. Em produção você troca a URL base e a chave. Não há homologação: terminou de testar, a integração já pode ser ativada em lojas reais. ## O que muda | | Ambiente de teste | Produção | | - | - | - | | URL base | `https://api.dev.connect.onbeefapp.com.br` | `https://api.connect.onbeefapp.com.br` | | Painel da loja | [lojista.dev.onbeefapp.com.br](https://lojista.dev.onbeefapp.com.br/) | [lojista.onbeefapp.com.br](https://lojista.onbeefapp.com.br/) | | Quem gera a chave | Você, na loja de teste | O lojista, no painel dele | | Webhook | Cadastrado com a chave de teste | Cadastrado de novo, com a chave de produção | | Pedidos | De teste | De clientes reais | O resto é igual: mesmos endpoints, mesmos payloads, mesmos limites. > [!WARNING] > > Em produção, cada chamada mexe em loja real. Uma sincronização completa remove produtos do catálogo, `merchantStatus` errado abre ou fecha a loja, e um cancelamento estorna o pagamento do cliente. ## Checklist Confira cada item antes de ativar a primeira loja. * **Um token guardado por loja.** O seu sistema só pede outro perto do fim da validade, e guarda o token entre reinícios. O limite de 30 pedidos de token por minuto é o único dividido entre as lojas do seu servidor. * **Polling ligado, mesmo com webhook.** O polling em `GET /v1/events:polling`, a cada 30 segundos, é o que garante que nenhum pedido se perde. * **Eventos idempotentes.** O mesmo evento pode chegar mais de uma vez. Identifique pelo par `orderId` + `eventId` e não duplique o pedido. * **Evento confirmado só depois de gravado.** Evento não confirmado não expira: fica na consulta até ser confirmado ou até o pedido mudar de evento. * **`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. * **`start_at` recuado no dia da virada.** O filtro é pela data de criação, e pedido agendado feito antes da data não aparece. 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. * **Pedido importado no ponto certo.** Para faturar, importe no `DELIVERED`. Veja [Quando importar o pedido](/guides/order-import). * **Sincronização conferida no `merchantStatus`.** Depois de cada envio de catálogo, `GET /v1/merchantStatus` termina em `SUCCESS`. Se passar de 5 minutos em `PROCESSING`, envie de novo. * **Campo `merchantStatus` com o status real.** No envio `MERCHANT`, `AVAILABLE` fixo reabre uma loja que o lojista fechou no painel. Antes do envio, leia `status` em `GET /v1/merchant` e reenvie o mesmo valor. * **`429` e `503` tratados.** Em `429`, espere os segundos de `Retry-After`: o limite é da loja, dividido entre o PDV e a empresa de entregas. Em `503`, tente de novo com espera crescente, até 3 vezes. * **Valor a cobrar lido antes da saída (entregas).** Consulte o pedido de novo antes de o entregador sair. Veja [Integre as entregas](/guides/delivery-flow). * **`403` sem laço de tentativas.** `Integration is not active`: avise o lojista. ## Como a loja ativa 1. A loja precisa do plano **Expert**. Sem ele, a tela mostra **Exclusivo do plano Expert**. 2. O lojista gera a chave em **Configurações** > **Canais e Integrações** > **Integrações**, no cartão **Nova chave API**, e passa o **ID** e a **Chave** para você. A Onbeef não entrega credencial de loja real. 3. Você configura a URL de produção e a chave. Se usa webhook, cadastra de novo: o cadastro é por chave. 4. Em PDV, a loja que já vende preenche o **Código de integração com PDV** antes da primeira sincronização. Veja [Vincule uma loja que já tem produtos](/guides/catalog-linking). 5. Você acompanha os primeiros pedidos reais com a loja. ### Regras * **Uma chave por loja.** Cada loja nova repete os passos acima. * **Você orienta o seu lojista,** inclusive sobre o que configurar na Onbeef. A Onbeef orienta sobre a Onbeef. A página [Ative a integração](/lojistas/ativar) serve de base para o seu passo a passo. * **Chave inativa responde `403`.** Veja [Chave inativa ou apagada](/authentication/overview#chave-inativa-ou-apagada). ## Apareça na tela Integrações Não há homologação. Quando terminar, envie a [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br) a logo do seu sistema e um texto curto de como a loja ativa a integração do seu lado. A Onbeef inclui o seu sistema na seção **Explorar integrações** da tela **Integrações**, onde a loja clica em **Conectar** para gerar a chave. ## Depois de ativar * **Acompanhe o changelog.** Mudança que pode quebrar integração é avisada antes e sobe primeiro no ambiente de teste. Veja o [changelog](/changelog). * **Dúvida técnica vai por e-mail,** com o endpoint, o payload, o `id` do pedido e o horário da chamada. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Erros e limites](/api-reference/errors) > > Mensagens literais, limites por minuto e o que fazer. > [card] [Perguntas frequentes](/desenvolvedores/faq) > > As dúvidas mais comuns. # Ambiente de teste Source: https://docs.onbeef.app/environments/sandbox Peça uma loja de teste, gere a chave no painel de teste, crie pedidos e valide a integração antes de ativar em loja real. O ambiente de teste (sandbox) tem API, painel e loja próprios. A Onbeef cria uma loja de teste para você, e você desenvolve a integração inteira nela, sem tocar em loja real. | | Endereço | | - | - | | API | `https://api.dev.connect.onbeefapp.com.br` | | Painel da loja | [lojista.dev.onbeefapp.com.br](https://lojista.dev.onbeefapp.com.br/) | ## Como funciona 1. Você pede a loja de teste por e-mail para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br), dizendo qual é o seu sistema. 2. A Onbeef cria a loja e envia o login do painel de teste. 3. Você gera a chave no painel de teste, em **Configurações** > **Canais e Integrações** > **Integrações**. O passo a passo está no [Início rápido](/quickstart). 4. Você cria pedidos de teste e acompanha os eventos no seu sistema. ### Regras * **Chave de teste só funciona na URL de teste.** Chave de loja real só funciona na URL de produção. * **A chave de teste é sua.** Você mesmo gera, desativa e apaga no painel de teste. * **Mudança na API chega primeiro aqui.** Mudança que pode quebrar integração é avisada antes, sobe primeiro no ambiente de teste e entra no [changelog](/changelog). * **A tela Integrações não aparece no menu?** Conclua o cadastro inicial da loja de teste. Se a tela mostrar **Exclusivo do plano Expert**, a loja de teste está sem o plano: avise pelo mesmo e-mail. ## Crie pedidos de teste Não há endpoint para criar pedido. Crie os pedidos como a loja e o cliente criam: * **Pelo catálogo online da loja de teste.** Faça o pedido como um cliente faria. * **Pelo painel de teste.** Abra **Painel de Vendas** e clique em **Novo pedido**. Depois avance o pedido pelo painel, como a loja faz: aceite, marque como pronto, envie para entrega e conclua. Cada mudança gera um evento para a sua integração. Pedido pago por PIX online só aparece na API depois de pago. Pedido com pagamento na entrega aparece na hora. ## O que testar | Cenário | O que conferir | | - | - | | Pedido de entrega, do `CREATED` ao `DELIVERED` | Os eventos chegam por webhook e por polling, e você confirma cada um. | | Pedido de retirada | O pedido vem com `type: "TAKEOUT"` e não passa por `DISPATCHED`. | | Pedido agendado | O pedido vem com `orderTiming: "SCHEDULED"` e a janela em `schedule`. | | Consulta com `start_at` | O polling com `start_at` na data de hoje não traz os pedidos de teste antigos. | | Item por peso ajustado pela loja | Ajuste o peso no painel, em **Ajustar o pedido**. O ajuste não gera evento: consulte o pedido de novo e confira a quantidade nova. | | Cancelamento feito pela loja | Chega o evento `CANCELLED`. | | Mesmo evento recebido duas vezes | O seu sistema não duplica o pedido. | | Token vencido | O seu sistema pede outro token e repete a chamada. | | Sincronização de catálogo (PDV) | `GET /v1/merchantStatus` termina em `SUCCESS` depois de cada envio. | | Loja que já tem produtos (PDV) | Com o **Código de integração com PDV** preenchido, a sincronização atualiza o produto em vez de criar outro. | | Saída e entrega (empresa de entregas) | `dispatch` deixa o pedido **Em rota** e `delivered` deixa **Entregue** no painel. | | Valor a cobrar depois da pesagem (empresa de entregas) | Ajuste o peso no painel e consulte o pedido de novo: `payments.methods[0].value` muda sem evento. | Terminou? Confira o [checklist de produção](/environments/production#checklist). ## Ambiente trocado Ambiente trocado é a causa número 1 de `401`, `404` e `500` no começo da integração. A URL, a chave e o pedido precisam ser do mesmo ambiente. | O que você vê | Causa | O que fazer | | - | - | - | | `401` `The client credentials were incorrect.` ou `500` no pedido de token | Chave de produção na URL de teste, ou o contrário. | Use a chave gerada no painel do mesmo ambiente da URL. | | `401` em toda chamada com um token recém-emitido | Token pedido em um ambiente e usado no outro. | Peça o token na mesma URL base das chamadas. | | `404` `Order not found` | Pedido de produção consultado na URL de teste, ou o contrário. | Confira a URL base e de qual loja é o pedido. | | O webhook não chega | O webhook foi cadastrado com a chave de um ambiente e os pedidos estão no outro. | Cadastre o webhook de novo com a chave do ambiente certo. | Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Início rápido](/quickstart) > > Chave, token e primeira chamada em 10 minutos. > [card] [Produção](/environments/production) > > O que muda e o checklist antes de ativar. # Vincule uma loja que já tem produtos Source: https://docs.onbeef.app/guides/catalog-linking Ligue os produtos e as categorias que já existem na Onbeef ao código do seu PDV antes do primeiro envio, para não duplicar o catálogo. A loja que já vende pela Onbeef tem produtos com foto e cortes, mas sem o código do seu PDV. Antes do primeiro envio, vincule o que já existe ou comece do zero. Implemente no meu PDV o vínculo de uma loja que já tem produtos na Onbeef, seguindo [https://docs.onbeef.app/guides/catalog-linking.md](https://docs.onbeef.app/guides/catalog-linking.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Quando usar Loja sem produtos vai direto para [Sincronizar catálogo](/guides/catalog-sync). Loja que já tem catálogo escolhe: * **Vincular pelo código (recomendado).** A loja preenche o **Código de integração com PDV** em cada produto e categoria. O envio atualiza o que tem código e cria o que falta. Fotos, cortes e nomes ficam. * **[Começar do zero](#comecar-do-zero).** A loja exclui as categorias e o PDV envia tudo. Fotos e cortes são refeitos. ## Como funciona 1. A Onbeef procura o produto pelo **Código de integração com PDV**, comparado com o `id` ou `itemId` que você envia. 2. A categoria é procurada pelo código dela, comparado com `categories[].id`. 3. Achou: atualiza. Não achou: o `MERCHANT` cria outro, e `ITEM` e `ITEM_OFFER` falham. O código é a única ligação: a Onbeef não compara nome, código de barras, código de balança nem o `id` (UUID) de `GET /v1/merchant`. ### O que acontece sem vínculo * **Produto e categoria sem código, `MERCHANT`:** nasce outra categoria com o mesmo nome e outro produto dentro dela. Catálogo duplicado. * **Produto com código em categoria sem código, `MERCHANT`:** o produto recebe o preço e fica onde está. A categoria do PDV nasce sem ele: ele só entra na categoria enviada se já estiver em alguma com código. * **Produto sem código, `ITEM` ou `ITEM_OFFER`:** `FAIL` com "Itens não encontrados: ...". ### Categorias da loja diferentes das do PDV Decida com o lojista o que fazer com a categoria que não existe no PDV, como "Churrasco": * **Manter as categorias dela.** O lojista põe o código da categoria do PDV na categoria da loja. "Churrasco" com o código `15` passa a ser a categoria `15`, com o nome do painel. * **Usar as categorias do PDV.** As da loja ficam sem código. O envio cria as do PDV, e o lojista move os produtos. ### Regras * **Produto e categoria têm código próprio.** Vincule os dois. * **Um código, um lugar.** O mesmo código não pode estar em dois produtos nem em duas categorias. O painel recusa: "Já existe outra categoria com o código de integração com PDV informado". Exclua a categoria criada por um envio anterior e ponha o código na que a loja mantém. * **O código é digitado no painel,** com a lista que você passa. Não há preenchimento por API, e a importação de arquivo da tela **Códigos & Balança** preenche só o **Código da balança**. * **`externalCode` não vincula.** Ele é o código de balança. * **Envie só o que a loja vende online.** Tudo o que é novo no envio entra no catálogo. ## Passo a passo **1. Entregue a lista de códigos ao lojista** Gere no PDV a lista com código e nome de cada produto e categoria: o valor de `items[].id` e de `categories[].id`. **2. O lojista preenche os códigos no painel** * **Produtos:** no catálogo, botão **Códigos & Balança**, coluna **Código de integração com PDV**. * **Categorias:** na edição da categoria, em **Vincular esta categoria ao seu sistema de PDV**. Envie ao lojista o [passo a passo com as telas](/lojistas/vincular-produtos). **3. Confira o vínculo** ```bash Ambiente de teste theme={null} curl --url https://api.dev.connect.onbeefapp.com.br/v1/merchant \ --header 'Authorization: Bearer ' ``` ```json theme={null} { "categories": [ { "id": "bdfbb2f3-af2a-4ad7-8714-f3c75531e78f", "pdv_external_id": "15", "name": "Bovinos" }, { "id": "82532a6d-c6d4-44c7-ab32-a8eca9bb29ca", "pdv_external_id": null, "name": "Churrasco" } ], "products": [ { "id": "1db3abc1-d295-4873-be31-ef64050a31f7", "pdv_external_id": "1001", "name": "Picanha", "unit": "KG" }, { "id": "e74dd75f-2a7c-416a-997d-02bab6adc10b", "pdv_external_id": null, "name": "Costela", "unit": "KG" } ] } ``` `pdv_external_id: null` é item sem código, como "Churrasco" e "Costela". Compare os códigos com a lista do PDV antes de enviar. Compare também o `unit`. Se o painel vende por unidade e o PDV envia `KG`, o preço do quilo vira preço da unidade: deixe o produto fora do envio até os dois venderem do mesmo jeito. O código preenchido leva até 10 minutos para aparecer nesta consulta, mas o envio já usa assim que o lojista salva. **4. Faça a primeira carga** Envie em `merchantStatus` o `status` lido no passo anterior. A leitura pode estar até 10 minutos atrasada: evite a primeira carga logo depois de a loja abrir ou fechar. ```json theme={null} { "entityType": "MERCHANT", "merchantStatus": "AVAILABLE", "onlyAddProducts": true, "updatedObjects": [ { "id": "LOJA-01", "categories": [ { "id": "15", "name": "Bovinos", "itemOfferId": ["OF-1001", "OF-1003"] }, { "id": "22", "name": "Bebidas", "itemOfferId": ["OF-2001"] } ], "itemOffers": [ { "id": "OF-1001", "itemId": "1001", "price": { "value": 94.90 } }, { "id": "OF-1003", "itemId": "1003", "price": { "value": 59.90 } }, { "id": "OF-2001", "itemId": "2001", "price": { "value": 10.00 } } ], "items": [ { "id": "1001", "name": "Picanha", "unit": "KG" }, { "id": "1003", "name": "Fraldinha", "unit": "KG" }, { "id": "2001", "name": "Refrigerante 2 L", "unit": "UN" } ] } ] } ``` * **Sem `status` nas ofertas e nas categorias.** O que já existe fica como o lojista deixou, e o que é novo nasce ativo. Com `"status": "AVAILABLE"`, todo produto desativado no painel voltaria a vender. * **Produto que já existe:** recebe o preço do PDV. Nome, fotos, cortes e tipo ficam. A descrição só é preenchida se estiver vazia. * **`onlyAddProducts: true`:** nada sai da loja. `"LOJA-01"` é o [código da loja no seu PDV](/guides/catalog-sync#o-codigo-da-loja). **5. Confira o resultado** Espere o `SUCCESS` em `GET /v1/merchantStatus` e procure produto repetido ou categoria vazia. ## Depois do vínculo No dia a dia, siga [Sincronizar catálogo](/guides/catalog-sync), com dois cuidados: * **`ITEM` sempre grava o `name` enviado.** Para manter o nome do lojista, envie o nome lido em `GET /v1/merchant`. * **Não use o [envio completo](/guides/catalog-sync#envio-completo).** Ele remove o que tem código do PDV e não veio, e tira da categoria o produto com código que o lojista pôs nela pelo painel. Produto sem código fica onde está. ## Começar do zero 1. Combine com o lojista antes: fotos e cortes do painel se perdem. 2. O lojista exclui as categorias. O produto que só estava nelas sai junto. 3. Você envia o catálogo inteiro com `MERCHANT`, com o `merchantStatus` lido em `GET /v1/merchant`. ## O que orientar o lojista * **Não cadastrar pelo painel um produto que existe no PDV** sem pôr o código: no próximo envio ele duplica. * **Preço muda no PDV,** e produto desativado no painel volta quando o PDV envia como disponível. Veja [o que cada envio sobrescreve](/concepts/merchant#o-que-cada-envio-sobrescreve). Catálogo já duplicou: o lojista exclui a categoria criada pelo envio (os produtos que só estavam nela saem junto) e preenche o código no que fica. Você envia de novo com `onlyAddProducts: true`. ## Teste No ambiente de teste (sandbox), desative um produto no painel, envie a primeira carga sem `status` e confira que ele continua desativado. Para ver a duplicação, envie um `MERCHANT` com o nome de um produto sem código. ## Perguntas frequentes > [accordion] O item do pedido veio com um UUID no id. O que significa? > > O produto vendido não tem código do PDV, inclusive item dentro de kit. Peça ao lojista para preencher. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Sincronizar catálogo](/guides/catalog-sync) > > O que enviar em cada situação. > [card] [Para o lojista: vincular produtos](/lojistas/vincular-produtos) > > O passo a passo das telas. # Sincronize o catálogo Source: https://docs.onbeef.app/guides/catalog-sync Envie do PDV só o que mudou: preço, disponibilidade, cadastro ou produto novo. Depois confira o resultado em GET /v1/merchantStatus. Quando algo muda no seu PDV, envie só a mudança com `PUT /v1/merchantUpdate`: o resto do catálogo fica como está. Implemente a sincronização de catálogo da Onbeef no meu PDV, seguindo [https://docs.onbeef.app/guides/catalog-sync.md](https://docs.onbeef.app/guides/catalog-sync.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## O que enviar em cada situação | O que aconteceu no PDV | `entityType` | O que vai em `updatedObjects` | | - | - | - | | Mudou o preço | `ITEM_OFFER` | `itemId` e `price.value` | | O produto acabou, voltou ou saiu de linha | `ITEM_OFFER` | `itemId`, `price.value` e `status` (`UNAVAILABLE` ou `AVAILABLE`) | | Mudou nome, descrição, foto ou código de balança | `ITEM` | `id`, `name` e o que mudou | | Produto ou categoria nova | `MERCHANT` com `onlyAddProducts: true` | A categoria, a oferta e o produto novos | | Abrir ou fechar a loja | `MERCHANT` | Só o código da loja | O `itemId` e o `id` são o código do produto no seu PDV, o **Código de integração com PDV** do painel. Produto que saiu de linha fica desativado: o lojista exclui pelo painel. > [tab] Preço > > ```json theme={null} > { > "entityType": "ITEM_OFFER", > "updatedObjects": [ > { "itemId": "1001", "price": { "value": 94.90 } } > ] > } > ``` > > Sem `status`, a disponibilidade fica como está. > [tab] Acabou ou voltou > > ```json theme={null} > { > "entityType": "ITEM_OFFER", > "updatedObjects": [ > { "itemId": "1001", "price": { "value": 94.90 }, "status": "UNAVAILABLE" } > ] > } > ``` > > O `price.value` é obrigatório mesmo quando só o `status` muda. > [tab] Nome, foto, descrição > > ```json theme={null} > { > "entityType": "ITEM", > "updatedObjects": [ > { > "id": "1001", > "name": "Picanha", > "description": "Peça resfriada, vendida por peso", > "image": { "url": "https://pdv.example.com/fotos/1001.jpg" } > } > ] > } > ``` > > O `name` é obrigatório e sempre substitui o nome do painel: para trocar só a foto ou a descrição, envie o nome lido em `GET /v1/merchant`. > [tab] Produto novo > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "AVAILABLE", > "onlyAddProducts": true, > "updatedObjects": [ > { > "id": "LOJA-01", > "categories": [ > { "id": "15", "name": "Bovinos", "itemOfferId": ["OF-1003"] } > ], > "itemOffers": [ > { "id": "OF-1003", "itemId": "1003", "price": { "value": 59.90 } } > ], > "items": [ > { "id": "1003", "name": "Fraldinha", "unit": "KG" } > ] > } > ] > } > ``` > > Envie a categoria com `id`, `name` e `itemOfferId` mesmo que ela já exista. Nada é removido. Sem `status`, o produto novo nasce disponível e a categoria fica como o lojista deixou. > [tab] Catálogo inteiro > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "AVAILABLE", > "onlyAddProducts": false, > "updatedObjects": [ > { > "id": "LOJA-01", > "categories": [ > { "id": "15", "name": "Bovinos", "index": 0, "itemOfferId": ["OF-1001", "OF-1003"] }, > { "id": "22", "name": "Bebidas", "index": 1, "itemOfferId": ["OF-2001"] } > ], > "itemOffers": [ > { "id": "OF-1001", "itemId": "1001", "price": { "value": 94.90 } }, > { "id": "OF-1003", "itemId": "1003", "price": { "value": 59.90 } }, > { "id": "OF-2001", "itemId": "2001", "price": { "value": 10.00 } } > ], > "items": [ > { "id": "1001", "name": "Picanha", "unit": "KG" }, > { "id": "1003", "name": "Fraldinha", "unit": "KG" }, > { "id": "2001", "name": "Refrigerante 2 L", "unit": "UN" } > ] > } > ] > } > ``` > > Leia [Envio completo](#envio-completo) antes: o que não vier é removido. > [tab] Abrir ou fechar a loja > > ```json theme={null} > { > "entityType": "MERCHANT", > "merchantStatus": "UNAVAILABLE", > "updatedObjects": [{ "id": "LOJA-01" }] > } > ``` > > Sem `categories`, o envio só abre ou fecha a loja. ## Como funciona 1. Você envia `PUT /v1/merchantUpdate`. O `204`, sem corpo, só diz que a Onbeef recebeu. 2. Você consulta `GET /v1/merchantStatus` até sair de `PROCESSING`. 3. `SUCCESS`: tudo gravado. `FAIL`: o `moreInfo` diz o que foi descartado, e o lojista vê o mesmo texto no cartão **Status da Integração PDV**. ### Regras * **`ITEM_OFFER` e `ITEM` só atualizam.** Produto sem o código do PDV termina em `FAIL` com "Itens não encontrados: ...". * **O catálogo online muda em seguida.** Preço, disponibilidade e cadastro aparecem para o cliente logo depois que o envio termina em `SUCCESS`. * **`merchantStatus` é aplicado na hora.** Todo `MERCHANT` exige o campo, e `AVAILABLE` fixo reabre a loja que o lojista fechou. Antes de um envio `MERCHANT`, leia `status` em `GET /v1/merchant` e reenvie o mesmo valor. A leitura pode estar até 10 minutos atrasada: evite envios `MERCHANT` logo depois de a loja abrir ou fechar. * **`status` só quando muda.** `AVAILABLE` reativa o produto que o lojista desativou. * **`unit` em maiúsculas.** Só `"KG"` ou `"UN"`. Com `KG`, o `price.value` é o preço do quilo. * **Erro de conteúdo nunca vira erro HTTP.** Aparece só no `moreInfo`. * **Uma sincronização por vez.** Envios seguidos podem terminar fora de ordem. Passou de 5 minutos em `PROCESSING`, o limite do processamento: envie de novo. * **Em lote.** Mudaram 300 preços: envie os 300 em um `updatedObjects`. O limite é de 60 escritas por minuto por loja. Item não encontrado não impede os outros: o `FAIL` lista os que faltaram. * **JSON em UTF-8.** Outra codificação quebra os acentos. Veja [o que cada envio sobrescreve](/concepts/merchant#o-que-cada-envio-sobrescreve) do que o lojista editou. ### O código da loja Todo `MERCHANT` leva em `updatedObjects[0].id` o código da loja no seu PDV, como `"LOJA-01"`: sem ele, o envio termina em `FAIL`. Você escolhe o valor, e ele volta em `merchant.id` de todo pedido. ## Passo a passo **1. Envie a mudança** ```bash Ambiente de teste theme={null} curl --request PUT \ --url https://api.dev.connect.onbeefapp.com.br/v1/merchantUpdate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "entityType": "ITEM_OFFER", "updatedObjects": [{ "itemId": "1001", "price": { "value": 94.90 } }] }' ``` A resposta é `204`. Com `POST` no lugar de `PUT`, a API responde `405`. **2. Confira o resultado** ```bash Ambiente de teste theme={null} curl --url https://api.dev.connect.onbeefapp.com.br/v1/merchantStatus \ --header 'Authorization: Bearer ' ``` ```json theme={null} { "lastRead": "2026-11-12T14:03:11.000000Z", "status": "SUCCESS", "moreInfo": null } ``` Repita a cada 5 segundos enquanto vier `PROCESSING`. Depois, confira o produto em `GET /v1/merchant`, pelo `pdv_external_id`. ## Envio completo É o `MERCHANT` com `onlyAddProducts: false`, ou sem o campo: a única forma de excluir pela API o que saiu do PDV. > [!WARNING] > > O envio completo remove todo produto e toda categoria com código do PDV que não vier no payload. Dentro de cada categoria enviada, a lista do envio substitui só os produtos com código do PDV: o produto criado no painel, sem código, continua nela. * **Envie o catálogo inteiro,** com `itemOfferId` em todas as categorias. Produto fora de todas as listas conta como produto que não veio. Para esvaziar uma categoria, envie `itemOfferId: []`. * **Use só quando o PDV é a única fonte do catálogo.** O produto com código do PDV que o lojista pôs em outra categoria pelo painel sai dela. Com algum objeto descartado, ou com alguma categoria sem a chave `itemOfferId`, nada é removido, o envio termina em `FAIL` e o `moreInfo` avisa: "Nenhum item foi removido do cardápio nesta atualização por segurança". Nenhum produto sai de categoria nesse envio: ele só acrescenta. ## Retornou 204 e nada apareceu Em `GET /v1/merchantStatus`: | O que você vê | Causa | O que fazer | | - | - | - | | `FAIL`: "... categorias recebidas sem a lista de produtos (itemOfferId) tiveram os produtos mantidos como estavam" | Categoria sem `itemOfferId`, ou com o campo escrito `itemsOfferId`. | Envie `itemOfferId` com o `id` de cada oferta. | | `FAIL`: "... produtos recebidos com dados incompletos foram descartados" | Oferta sem `id`, `itemId` diferente do `items[].id`, produto sem `name` ou oferta sem `price.value`. | Confira `itemOfferId` → `itemOffers[].id` → `itemId` → `items[].id`. | | `FAIL`: "Itens não encontrados: 1001, 1002", ou `SUCCESS` com produto duplicado | A loja já tinha o produto, sem o código do PDV. | Vincule: [Loja que já tem produtos](/guides/catalog-linking). | O `index` da categoria é opcional: sem ele, a categoria nova entra na posição `0`. As outras mensagens, como "Without Data", estão em [Resultado do envio](/api-reference/merchant/get-status). ## Teste No [ambiente de teste (sandbox)](/environments/sandbox): 1. Leia `status` em `GET /v1/merchant`, envie a aba **Produto novo** com esse valor em `merchantStatus` e espere o `SUCCESS`. 2. Envie a aba **Preço** com `itemId` `1003` e confira em `GET /v1/merchant`. 3. Envie um `itemId` que não existe e leia o `moreInfo`. ## Perguntas frequentes > [accordion] O PDV tem mais produtos do que a loja vende online. Envio todos? > > Não. Todo produto novo do envio entra no catálogo. Para criar um produto já desativado, envie a oferta com `status: "UNAVAILABLE"`. > [accordion] O produto mudou de categoria no PDV. Ele muda na Onbeef? > > Com `onlyAddProducts: true`, ele entra na categoria nova e continua na antiga, até o lojista tirar pelo painel. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Loja que já tem produtos](/guides/catalog-linking) > > Vincule pelo código do PDV antes do primeiro envio. > [card] [Referência: enviar catálogo](/api-reference/merchant/sync-catalog) > > Todos os campos de `PUT /v1/merchantUpdate`. # Integre as entregas Source: https://docs.onbeef.app/guides/delivery-flow Receba os eventos dos pedidos da loja, trate os de entrega, chame o entregador e informe a saída e a entrega para a Onbeef. A empresa de entregas usa a mesma API de pedidos do PDV, com uma chave gerada pela loja. Não há ativação nem homologação com a Onbeef. Implemente a integração de entregas da Onbeef no meu sistema de logística, seguindo [https://docs.onbeef.app/guides/delivery-flow.md](https://docs.onbeef.app/guides/delivery-flow.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Regras > [!WARNING] > > Só chame `dispatch` depois do `READY_FOR_PICKUP`, ou no mínimo do `CONFIRMED`. A API aplica o `dispatch` mesmo em pedido que a loja ainda não aceitou, e ele vai para **Em rota** sem preparo. * **Você recebe todos os pedidos da loja.** Não há filtro. Trate só `type: "DELIVERY"` e confirme os eventos de `TAKEOUT`, para saírem do polling. * **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, e um pedido antigo parado em **Pronto** aciona um entregador. * **Pedido agendado.** Traz `orderTiming: "SCHEDULED"` e a janela em `schedule`. Não há evento no dia: o sinal continua sendo `CONFIRMED` e `READY_FOR_PICKUP`, quando a loja começar a preparar. * **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. * **Aceitar e preparar é com a loja.** Não chame `confirm` nem `readyForPickup`. * **`202` é só o recebimento.** A mudança está feita quando chega `DISPATCHED` ou `DELIVERED`. Sem evento em cerca de 70 segundos, não foi aplicada. * **Saída não aplicada.** Consulte o pedido: `lastEvent` e `type` mostram o motivo (retirada, já entregue, cancelado, já em rota). Em pedido pago online com item por peso, peça à loja para confirmar o peso no painel e chame de novo. Veja [todos os motivos](/api-reference/orders/dispatch). * **Quem marca a saída.** A loja, pelo painel, 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`. * **Limites.** A loja tem 200 leituras e 60 escritas por minuto, divididas com o PDV. A consulta a cada 30 segundos cabe: 2 leituras por minuto, mais uma por pedido novo. Em `429`, a entrega segue e você repete a chamada depois do `Retry-After`. * **A loja cancelou.** Você recebe `CANCELLED`, inclusive em pedido **Em rota**: dispense o entregador. * **A entrega não pôde ser feita.** Avise a loja: não há chamada para isso. Não cancele: [`requestCancellation`](/concepts/orders#cancelamento) estorna o pagamento online. Só use se a loja pedir. Pedido já entregue não é cancelado. * **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**. * **A chave não tem escopo.** Dá acesso ao catálogo e aos pedidos da loja. ## Passo a passo **1. Peça a chave à loja** A loja gera a chave em **Configurações** > **Canais e Integrações** > **Integrações**, no cartão **Nova chave API**. Peça uma só para você: cada sistema confirma os próprios eventos. Siga o [Início rápido](/quickstart). **2. Receba os eventos** Cadastre a sua URL no [webhook de pedidos](/guides/orders-webhook) e consulte o polling a cada 30 segundos. O polling é obrigatório: é ele que garante que nenhum pedido se perde. Depois de gravar, [confirme os eventos](/guides/order-flow#passo-a-passo). ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-11-13" \ -H "Authorization: Bearer " ``` Várias lojas na mesma URL: o header `X-App-MerchantId` diz qual é a loja. **3. Consulte o pedido e chame o entregador** ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}" \ -H "Authorization: Bearer " ``` ```json theme={null} { "type": "DELIVERY", "orderTiming": "INSTANT", "schedule": null, "delivery": { "deliveryAddress": { "street": "Av. Exemplo", "number": "100", "complement": "BL 02 AP 31", "reference": "Casa amarela", "district": "Moema", "city": "São Paulo", "state": "SP", "postalCode": "04000-000", "coordinates": { "latitude": -23.54823, "longitude": -46.63632 } }, "estimatedDeliveryDateTime": "2026-11-12T18:00:00.000000Z" } } ``` Se `delivery` vier `null`, o pedido está sem endereço: avise a loja. Cliente em `customer`, observação em `extraInfo`: veja [Entenda os dados do pedido](/guides/order-data). Chame o entregador no `CONFIRMED` (a loja aceitou) ou no `READY_FOR_PICKUP` (o pedido está pronto). **4. Leia o que cobrar na entrega** Consulte o pedido de novo na hora da saída e leia `payments.methods[0]`. O valor muda quando a loja pesa, sem evento: R\$ 97,09 no `CONFIRMED` viram R\$ 102,40 depois da pesagem. | `type` | `method` | Na porta | | - | - | - | | `PREPAID` | Qualquer um | Já está pago. Não cobre. | | `PENDING` | Dinheiro, PIX, cartão ou vale | Cobre `value` só se a loja confirmar que o pedido é para pagar na entrega. `changeFor` é o valor para o troco. | | `PENDING` | `OTHER` (fiado, link de pagamento, boleto) | Nunca cobre. | A API não tem campo que separe pagamento na entrega de pagamento online em andamento: cartão online ainda não capturado também sai `CREDIT` com `PENDING`. **Ajustar valor** não vem na API: oriente a loja a usar **Desconto personalizado**. **5. Informe a saída** ```bash Ambiente de teste theme={null} curl -X POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}/dispatch" \ -H "Authorization: Bearer " ``` Com o `DISPATCHED`, o pedido fica **Em rota** e o cliente recebe a mensagem de WhatsApp de saída. **6. Informe a entrega** ```bash Ambiente de teste theme={null} curl -X POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}/delivered" \ -H "Authorization: Bearer " ``` Com o `DELIVERED`, o pedido fica **Entregue**, sem volta. ## 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 por e-mail. ## Teste No ambiente de teste (sandbox), crie um pedido de entrega em **Painel de Vendas** > **Novo pedido**. Aceite e marque **Pronto** pelo painel, confira os eventos e chame `dispatch` e `delivered`. Em [produção](/environments/production), a loja gera a chave. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Receba pedidos](/guides/order-flow) > > Webhook, polling e confirmação. > [card] [Entenda os dados do pedido](/guides/order-data) > > Endereço, cliente e pagamento. # Entenda os dados do pedido Source: https://docs.onbeef.app/guides/order-data Leia os identificadores, os itens por quilo, os totais, o pagamento e as datas que vêm na consulta do pedido. `GET /v1/orders/{orderId}` devolve o pedido como ele está agora. A lista completa, com os campos fixos para ignorar, está em [Consultar pedido](/api-reference/orders/get-order). ## Identificadores ```json theme={null} { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "displayId": "4F15BA00B", "salesChannel": "CATALOG", "lastEvent": "READY_FOR_PICKUP", "merchant": { "id": "LOJA-01", "name": "Açougue Exemplo" } } ``` * **`id`.** Identificador único. Guarde: é ele que entra em `GET /v1/orders/{orderId}`. * **`displayId`.** Código que a loja vê no painel e na impressão. Mostre para a loja conferir. O número curto do painel ("Pedido 300") não vem na API e reinicia todo mês. * **`merchant.id`.** Código da loja no PDV que sincroniza o catálogo dela. Sem sincronização, vem o UUID da loja na Onbeef. Se não é você quem envia o catálogo, roteie pela chave que fez a consulta. ## Itens ```json theme={null} { "items": [ { "id": "1001", "name": "Picanha", "externalCode": "000123", "kit_id": null, "unit": "KG", "quantity": 1.32, "specialInstructions": "Bem limpa", "unitPrice": { "value": 94.9, "currency": "BRL" }, "originalPrice": { "value": 94.9, "currency": "BRL" }, "optionsPrice": { "value": 3, "currency": "BRL" }, "totalPrice": { "value": 128.27, "currency": "BRL" }, "options": [ { "id": "0b7d4c7a-93b1-4c53-8a55-7d2c5e0e4b20", "name": "Bife", "quantity": 1.32, "unit": "KG", "specialInstructions": "Bifes de 2 dedos", "unitPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 0, "currency": "BRL" } }, { "id": "5a1d2c3b-7e8f-4a9b-b0c1-d2e3f4a5b6c7", "name": "Embalagem a vácuo", "quantity": 1, "unitPrice": { "value": 3, "currency": "BRL" }, "totalPrice": { "value": 3, "currency": "BRL" } } ] }, { "id": "2001", "name": "Refrigerante 2 L", "externalCode": null, "kit_id": null, "unit": "UN", "quantity": 2, "specialInstructions": null, "unitPrice": { "value": 10, "currency": "BRL" }, "originalPrice": { "value": 10, "currency": "BRL" }, "optionsPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 20, "currency": "BRL" }, "options": [] } ] } ``` * **`id` é o Código de integração com PDV do produto**, o mesmo `id` que você envia no catálogo, sem prefixo. * **`id` em formato UUID é produto sem vínculo.** O valor muda a cada pedido: não cadastre como código de produto. Peça à loja para preencher o código e consulte de novo, mesmo se você não envia catálogo. Em kit, confira cada produto. Veja [Vincule produtos que já existem](/guides/catalog-linking). * **`externalCode` é o código de balança.** Não é o código do PDV. * **`unit: "KG"`.** `quantity` vem em quilos (1.32 = 1,320 kg) e `unitPrice` é o preço por quilo. Com `"UN"`, unidades e preço de cada uma. * **Corte.** Vem em `options[]` com `unit: "KG"`, peso e observação, sempre com preço zero. O `id` é o de `cuts[].id` em `GET /v1/merchant`. * **Adicional.** Vem em `options[]` sem `unit`, com preço. O `id` é sempre um UUID. * **Observação.** A do item vem em `specialInstructions`. A do pedido, em `extraInfo`. ### Valor da linha ```text theme={null} totalPrice = unitPrice x quantity + optionsPrice ``` Na Picanha: 94,90 x 1,32 = 125,27, mais 3,00 do adicional, dá 128,27. Se o documento fiscal exige `unitPrice` x `quantity` = `totalPrice`, lance o adicional como linha à parte. ### Kit O kit vem como uma linha, com `kit_id: null`. Cada produto escolhido vem em outra, com `kit_id` igual ao `id` da linha do kit. * **Kit com preço próprio, como o de Preço Fechado.** A linha do kit traz o preço. As dos produtos vêm com valor zero, ou só com o acréscimo da escolha. * **Kit de Preço Aberto.** A linha do kit vem com valor zero. Cada produto traz o próprio preço. ```json theme={null} { "items": [ { "id": "3001", "name": "Kit Churrasco", "kit_id": null, "unit": "UN", "quantity": 1, "unitPrice": { "value": 199.9, "currency": "BRL" }, "totalPrice": { "value": 199.9, "currency": "BRL" } }, { "id": "1001", "name": "Picanha", "kit_id": "3001", "unit": "KG", "quantity": 1, "unitPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 0, "currency": "BRL" } }, { "id": "2001", "name": "Refrigerante 2 L", "kit_id": "3001", "unit": "UN", "quantity": 2, "unitPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 0, "currency": "BRL" } } ] } ``` O exemplo é um kit de **Preço Fechado**. Cada real aparece em uma linha só: some o `totalPrice` de todas as linhas, como a API faz em `total.itemsPrice`. O `id` do kit é o código do PDV, se a loja preencheu, ou um UUID. ## Totais ```text theme={null} orderAmount = itemsPrice + otherFees - discount ``` `itemsPrice` soma o `totalPrice` dos itens. `otherFees` soma o frete (`DELIVERY_FEE`) e a taxa de serviço (`SERVICE_FEE`). Os valores vêm em reais, com duas casas, arredondados: 1,320 kg a R\$ 94,90 dá 125,268 e sai 125.27. Frete grátis da fidelidade vem como frete mais um desconto do mesmo valor. Se a loja não cobra frete, `otherFees` vem sem `DELIVERY_FEE`. ```json theme={null} { "otherFees": [ { "name": "Frete", "type": "DELIVERY_FEE", "price": { "value": 8, "currency": "BRL" } } ], "discounts": [ { "amount": { "value": 8, "currency": "BRL" }, "target": "DELIVERY_FEE", "sponsorshipValues": [ { "name": "MERCHANT", "amount": { "value": 8, "currency": "BRL" }, "discountCode": null } ] } ], "total": { "itemsPrice": { "value": 148.27, "currency": "BRL" }, "otherFees": { "value": 8, "currency": "BRL" }, "discount": { "value": 8, "currency": "BRL" }, "orderAmount": { "value": 148.27, "currency": "BRL" } } } ``` Aqui, 148,27 + 8,00 - 8,00 = 148,27. * **Um item de `discounts[]` por desconto.** Cupom, clube, fidelidade, cashback, agendamento e desconto da loja, sem campo com o tipo. O cupom traz o código em `sponsorshipValues[].discountCode`. O `target` é `CART` (itens) ou `DELIVERY_FEE` (frete). * **Desconto da loja.** O de **Desconto personalizado** vem em `discounts[]`. O de **Ajustar valor** não vem: o pedido sai com a soma dos itens. Veja [Desconto dado pela loja](/guides/order-import#desconto-dado-pela-loja). ## Pagamento ```json theme={null} { "payments": { "prepaid": 0, "pending": 148.27, "methods": [ { "value": 148.27, "currency": "BRL", "type": "PENDING", "method": "CASH", "brand": null, "methodInfo": null, "changeFor": 200 } ] } } ``` * **`type: "PREPAID"`.** Já está pago. Não cobre. * **`type: "PENDING"`.** Não está pago. Cobre na entrega só se `method` for dinheiro, PIX, cartão ou vale e a loja confirmar que o pedido é para pagar na entrega. `method`: `PIX`, `CREDIT` (inclusive Apple Pay), `DEBIT`, `CASH`, `FOOD_VOUCHER` (vale alimentação), `MEAL_VOUCHER` (vale refeição) ou `OTHER`. * **Online ou na entrega.** A API não tem campo que separe pagamento na entrega de pagamento online em andamento: cartão online ainda não capturado também sai `CREDIT` com `PENDING`. * **`OTHER` nunca se cobra na porta.** O nome vem em `methodInfo`, texto livre: "Pagamento a prazo (Nota/Fiado)", "Link de pagamento", "Link via Whatsapp" ou a forma criada pela loja, como boleto. * **Troco.** Em `CASH`, `changeFor` traz o valor que o cliente vai entregar. * **Pago na entrega continua `PENDING`** depois do `DELIVERED`: a API não registra o recebimento na porta. * **O valor vem do total.** `value`, `prepaid` e `pending` repetem o `total.orderAmount`, recalculado a cada consulta. Se falta pagar uma diferença depois do ajuste, o pedido sai `PENDING` com o total inteiro. * **O que não vem.** Valor cobrado no cartão ou no PIX, estorno, data do pagamento e `currency` nos números de `payments`. ## Cliente ```json theme={null} { "customer": { "id": "9c2e4f6a-1b3d-4e5f-8a7b-6c5d4e3f2a1b", "name": "João da Silva", "phone": { "number": "11999999999", "extension": null }, "email": "joao@example.com", "documentNumber": null, "ordersCountOnMerchant": 3 } } ``` `documentNumber` traz o CPF ou CNPJ informado no pedido ou, na falta dele, o do cadastro do cliente na loja. A API não diz se o cliente pediu o documento na nota. ## Entrega, retirada e datas Em `type: "DELIVERY"` vem o bloco `delivery`, com o endereço em `deliveryAddress` e a hora da entrega em `deliveryDateTime`. Em `"TAKEOUT"` vem o bloco `takeout`: a hora em que o cliente retirou não vem na API. Pedido para agora vem com `orderTiming: "INSTANT"` e `schedule: null`. O agendado vem assim: ```json theme={null} { "createdAt": "2026-11-12T17:30:00.000000Z", "orderTiming": "SCHEDULED", "schedule": { "scheduledDateTimeStart": "2026-11-14T13:00:00.000000Z", "scheduledDateTimeEnd": "2026-11-14T14:00:00.000000Z" } } ``` `createdAt` é o dia em que o cliente fez o pedido. O dia da entrega está em `schedule`. O `start_at` do polling olha o `createdAt`: veja [Pedido agendado na virada](/guides/order-import#pedido-agendado-na-virada). Toda data vem em UTC, em ISO 8601. Converta para o horário da loja: `17:30` UTC é `14:30` em Brasília. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Quando importar o pedido](/guides/order-import) > > Quando peso e total não mudam mais. > [card] [Consultar pedido](/api-reference/orders/get-order) > > Todos os campos. # Receba pedidos Source: https://docs.onbeef.app/guides/order-flow Descubra os pedidos da loja por webhook e polling, consulte cada um e confirme o evento depois de gravar. Receber um pedido tem três chamadas: descobrir o evento, consultar o pedido e confirmar o evento. Implemente o recebimento de pedidos da Onbeef no meu sistema, seguindo [https://docs.onbeef.app/guides/order-flow.md](https://docs.onbeef.app/guides/order-flow.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Como funciona 1. O pedido chega ou muda de status. Isso gera um [evento](/concepts/orders#eventos-e-status). 2. A Onbeef avisa a sua URL na hora, pelo [webhook](/guides/orders-webhook). 3. A cada 30 segundos, você consulta `GET /v1/events:polling` com `start_at` e recebe os eventos que ainda não confirmou. 4. Para cada evento, você consulta `GET /v1/orders/{orderId}` e grava o pedido. 5. Depois de gravar, você confirma o evento em `POST /v1/events/acknowledgment`. ### Regras * **Webhook e polling juntos.** O webhook avisa em tempo real e é opcional: tem 3 tentativas e depois desiste. O polling é obrigatório: é ele que garante que nenhum pedido se perde. * **O polling é uma foto.** Devolve o evento atual de cada pedido, até 1000, dos mais antigos para os mais novos. * **Confirme só depois de gravar.** Evento confirmado some do polling desta chave, e a API não tem listagem para reencontrar o pedido. * **Sem confirmação, o evento repete.** Evento não confirmado não expira: fica na consulta até ser confirmado ou até o pedido mudar de evento. * **A confirmação é por chave.** Ela não tira o evento de outro sistema da loja. Peça uma chave só sua. * **Deduplique pelo par `orderId` + `eventId`.** O mesmo evento pode chegar pelo webhook e pelo polling. * **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. * **Pedido agendado.** O filtro é pela data de criação: no dia da virada, recue o `start_at` 7 dias e ignore o pedido que já estava entregue antes. Veja [Pedido agendado na virada](/guides/order-import#pedido-agendado-na-virada). * **Limites por loja.** São 200 leituras e 60 escritas por minuto. O polling a cada 30 segundos usa 2 leituras. Só o limite de token é compartilhado entre as lojas do seu servidor: guarde um token por loja e reaproveite. * **Erro `503`.** Tente de novo com espera crescente, até 3 vezes. Veja [Erros e limites](/api-reference/errors). ## Passo a passo Você precisa de um token: veja o [Início rápido](/quickstart). **1. Consulte os eventos** ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?start_at=2026-11-13" \ -H "Authorization: Bearer " ``` Troque `2026-11-13` pela data em que a integração começou na loja. A resposta traz um item por pedido: ```json theme={null} [ { "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c", "eventType": "CREATED", "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "orderURL": "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479", "sourceAppId": "fb08c6b7-a844-43c6-b104-98e70c00fc20", "virtualBrand": null, "createdAt": "2026-11-12T17:30:00.000000Z" } ] ``` Para receber só alguns eventos, repita o filtro: `?eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13`. Ignore `sourceAppId` e `virtualBrand`. **2. Consulte o pedido** ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479" \ -H "Authorization: Bearer " ``` A resposta traz o pedido como ele está agora: veja [Entenda os dados do pedido](/guides/order-data). `404 Order not found` em pedido que existe quase sempre é ambiente trocado: chave de um ambiente não funciona no outro. **3. Grave o pedido no seu sistema** Guarde o `id`: é com ele que você consulta de novo. Antes de faturar, veja [Quando importar o pedido](/guides/order-import): o pedido com item por peso muda depois de criado. **4. Confirme o evento** Envie o `eventId` no campo `id`, com o `orderId` e o `eventType` recebidos: ```bash Ambiente de teste theme={null} curl -X POST "https://api.dev.connect.onbeefapp.com.br/v1/events/acknowledgment" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[{ "id": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c", "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "eventType": "CREATED" }]' ``` A resposta é `202`, sem corpo. Confirme vários eventos na mesma lista, inclusive o que o seu sistema não usa, para ele parar de voltar. ## Se o seu sistema conduz o status Opcional. No modelo recomendado, a loja conduz o pedido no painel e o seu sistema só lê. Use as ações só se a loja opera o pedido dentro do seu sistema. | Ação | Status no painel | Quando chamar | | - | - | - | | [`confirm`](/api-reference/orders/confirm) | Em preparo | A loja aceitou o pedido. | | [`readyForPickup`](/api-reference/orders/ready-for-pickup) | Pronto | O pedido está separado. | | [`dispatch`](/api-reference/orders/dispatch) | Em rota | O entregador saiu. Só em entrega. | | [`delivered`](/api-reference/orders/delivered) | Entregue | O cliente recebeu ou retirou. | Todas são `POST /v1/orders/{orderId}/`. O `confirm` exige `orderExternalCode` (o código do pedido no seu sistema) e `createdAt` (o do pedido) no corpo. Eles não aparecem no painel nem na consulta. As outras ações não levam corpo. ```bash Ambiente de teste theme={null} curl -X POST "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}/confirm" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "orderExternalCode": "PDV-98231", "createdAt": "2026-11-12T17:30:00Z" }' ``` ### Regras do 202 * **`202` é só o recebimento.** A confirmação é o evento novo, pelo webhook ou pelo polling. * **Sem evento em cerca de 70 segundos, não foi aplicada.** A API não avisa o erro. Consulte o pedido: `lastEvent` e `type` mostram o motivo. * **Motivos para não aplicar.** `dispatch` em retirada. Pedido já entregue ou cancelado. Status anterior ao atual. * **Peso sem confirmar.** Pedido pago online com item por peso só avança depois que a loja confirma o peso no painel. Vale para `dispatch` e `delivered` em entrega, e para `readyForPickup` e `delivered` em retirada. * **Dá para pular etapa**, como `readyForPickup` em pedido `CREATED`. Não dá para voltar. * **O cliente é avisado.** Cada ação dispara a mesma mensagem de WhatsApp que o painel envia. * **O evento chega duas vezes pelo webhook** quando a mudança é feita pela integração. Trate como normal. Para cancelar, veja [Cancelamento](/concepts/orders#cancelamento). ## Teste No [ambiente de teste (sandbox)](/environments/sandbox), entre em `https://lojista.dev.onbeefapp.com.br` e crie um pedido em **Painel de Vendas** > **Novo pedido**. O `CREATED` aparece na próxima consulta, se o `start_at` for de hoje ou anterior. Mude o status pelo painel e veja o evento novo substituir o anterior. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Quando importar o pedido](/guides/order-import) > > O ponto certo para faturar. > [card] [Receba pedidos por webhook](/guides/orders-webhook) > > URL e assinatura. # Quando importar o pedido Source: https://docs.onbeef.app/guides/order-import Deixe a loja operar o pedido na Onbeef e importe o pedido fechado no PDV, quando peso e total não mudam mais. A loja opera o pedido na Onbeef: aceita, pesa, ajusta e entrega. O PDV ou ERP importa o pedido fechado para faturar. É o modelo que a Onbeef recomenda: o seu sistema só lê e confirma eventos. Implemente a importação de pedidos fechados da Onbeef no meu PDV, seguindo [https://docs.onbeef.app/guides/order-import.md](https://docs.onbeef.app/guides/order-import.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Por que o pedido muda Carne é vendida por peso. O cliente pede 1 kg, a loja pesa 1,080 kg, e quantidade e total mudam depois de criado. A loja ajusta no painel, em **Ajustar o pedido**, ou bipando a etiqueta da balança no pedido. **Ajustar item ou peso não gera evento.** O seu sistema só vê a mudança quando consulta `GET /v1/orders/{orderId}` de novo. | Pedido | Até quando a loja pode ajustar | | - | - | | Pago online | Uma vez, antes de sair para entrega. Em retirada, antes de ficar pronto. | | Pago na entrega | Quantas vezes precisar, até a entrega. | `DELIVERED` é o único ponto em que nenhum pedido muda mais. Depois dele, a loja não cancela pelo painel. ## Quando importar | O seu sistema | Importe | Como | | - | - | - | | Só fatura ou emite cupom | No `DELIVERED` | Filtre o polling por `DELIVERED` e `CANCELLED`, e consulte o pedido. | | Precisa do pedido antes (separação, expedição) | A partir de `READY_FOR_PICKUP` | Use `READY_FOR_PICKUP`, `DISPATCHED` ou `DELIVERED` como gatilho. Consulte de novo no `DELIVERED` antes de faturar. | ### Regras * **Não fature no `CREATED`.** Quantidade e total são provisórios até a loja confirmar o peso. Importar para a loja ver o pedido, pode. * **Aceite três eventos como gatilho.** O polling só mostra o evento mais recente: se o pedido sair antes da sua consulta, você vê `DISPATCHED` e nunca `READY_FOR_PICKUP`. * **Consulte de novo antes de faturar.** O pedido lido no `READY_FOR_PICKUP` ainda pode mudar. Caso real: um PDV emitiu o cupom no **Pronto**, com 0,720 kg. A loja pesou 14 minutos depois e ajustou para 0,600 kg, sem evento. * **Dê um botão à loja.** "Atualizar pedido da Onbeef", no PDV, cobre o ajuste feito depois da importação. * **Sem Entregue, sem `DELIVERED`.** O evento só existe quando a loja marca **Entregue**, inclusive na retirada. Pedido parado em **Pronto** nunca chega: avise a loja. * **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. * **Ignore `salesChannel: "IMPORT_CUSTOMER"`.** É histórico de cliente importado: vem `DELIVERED`, sem itens. Confirme o evento e não fature. * **Não chame as ações de status.** Ficam com a loja, no painel. * **A API só recebe status e cancelamento.** Item, peso ou valor alterado no PDV não muda o pedido na Onbeef, e os pontos de fidelidade do cliente ficam errados. Oriente a loja a ajustar na Onbeef. ## Passo a passo **1. Consulte os pedidos entregues e os cancelados** ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/events:polling?eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13" \ -H "Authorization: Bearer " ``` O limite de 1000 itens vale depois do filtro. **2. Consulte o pedido** ```bash Ambiente de teste theme={null} curl "https://api.dev.connect.onbeefapp.com.br/v1/orders/{orderId}" \ -H "Authorization: Bearer " ``` Pesos e total já são finais: veja [Entenda os dados do pedido](/guides/order-data). **3. Fature e confirme o evento** Depois de gravar e faturar, [confirme o evento](/guides/order-flow#passo-a-passo). Confirme também o `CANCELLED`, sem faturar. Para importar antes, troque o filtro: ```text theme={null} ?eventType=READY_FOR_PICKUP&eventType=DISPATCHED&eventType=DELIVERED&eventType=CANCELLED&start_at=2026-11-13 ``` ### Pedido agendado na virada O filtro é pela data de criação. Pedido feito antes da data do `start_at` e entregue depois não aparece: no dia da virada, recue o `start_at` 7 dias e ignore o pedido que já estava entregue antes da virada. * **Entrega.** Ignore o pedido com `delivery.deliveryDateTime` anterior à data da virada. * **Retirada.** A data em que o cliente retirou não vem na API: combine com a loja. Exemplo: a integração começa no dia 13. A encomenda feita no dia 11 para o dia 14 aparece com `start_at=2026-11-06`. Um `start_at` que anda com o dia perde toda encomenda feita com antecedência. ### Cancelado depois de faturado * **A loja cancelou depois da importação.** Chega `CANCELLED`: cancele a pré-venda ou o documento emitido. * **Devolução e estorno de pedido entregue.** Ficam fora da API: trate no PDV. * **O suporte da Onbeef cancelou um pedido entregue.** Chega `CANCELLED` depois do `DELIVERED` já confirmado: cancele o documento fiscal. Por isso o filtro inclui `CANCELLED`. ## Desconto dado pela loja | No painel | Na API | | - | - | | **Desconto personalizado**, em **adicionar desconto**, no detalhe do pedido | Vem em `discounts[]` e entra em `total.discount`. | | **Ajustar valor**: troca o total sem mexer nos itens | Não vem. O pedido sai com a soma dos itens. | > [!WARNING] > > Os itens somam R\$ 100,00 e a loja usa **Ajustar valor** para cobrar R\$ 90,00: a API devolve R\$ 100,00 em `total.orderAmount`, e nenhum campo avisa. Oriente a loja integrada: para dar desconto, **Desconto personalizado**; para corrigir peso ou quantidade, **Ajustar o pedido**; **Ajustar valor**, nunca. ## Teste No ambiente de teste (sandbox), crie um pedido com produto por quilo em **Painel de Vendas** > **Novo pedido**. Consulte, ajuste o peso em **Ajustar o pedido** e consulte de novo: `quantity` e `total` mudam, sem evento novo. Marque **Entregue** e confira o `DELIVERED`. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Entenda os dados do pedido](/guides/order-data) > > Itens, totais e pagamento. > [card] [Receba pedidos](/guides/order-flow) > > Polling e confirmação. # Receba pedidos por webhook Source: https://docs.onbeef.app/guides/orders-webhook Cadastre a URL do seu servidor, valide a assinatura e receba em tempo real cada pedido novo e cada mudança de status. O webhook é um aviso que a Onbeef envia para a sua URL quando um pedido chega ou muda de status. Ele traz o mesmo dado do polling, em tempo real, e funciona junto com ele. Implemente o webhook de pedidos da Onbeef no meu sistema, seguindo [https://docs.onbeef.app/guides/orders-webhook.md](https://docs.onbeef.app/guides/orders-webhook.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Como funciona 1. Você cadastra a URL base do seu servidor com `PUT /v1/merchantOnboarding`. 2. A cada evento, a Onbeef envia um `POST` para a sua URL base seguida de `/v1/orderUpdate`. 3. O seu servidor valida a assinatura, grava o evento e responde `2xx` em até 10 segundos. 4. O seu sistema consulta o pedido e segue o fluxo de [Receba pedidos](/guides/order-flow). ### Regras * **Cadastre só a URL base.** A Onbeef acrescenta `/v1/orderUpdate`. Não inclua esse caminho nem uma barra no final. Se a notificação não chega, confira se o seu servidor responde em `/v1/orderUpdate`: o erro mais comum é a rota responder `404`. * **Um cadastro por chave.** Cada chave tem a própria URL e assina com o próprio `client_secret`. Rede com 50 lojas tem 50 chaves e 50 cadastros, que podem apontar para a mesma URL. * **Várias lojas na mesma URL.** O header `X-App-MerchantId` traz o `id` que `GET /v1/merchant` devolve para a chave da loja. Guarde esse `id` junto com a chave e use o header para escolher o `client_secret` antes de validar. Outra saída é uma URL base por loja. * **O mesmo evento pode chegar mais de uma vez.** Mudança de status feita pela sua integração gera duas notificações, e a que falhou é reenviada. Deduplique pelo par `orderId` + `eventId` e responda `2xx` nas repetições. * **Ajuste de item ou peso não gera notificação.** Veja [Quando importar o pedido](/guides/order-import). * **O polling continua obrigatório.** O webhook não tem garantia de entrega. Veja [Tempos e tentativas](#tempos-e-tentativas). ## Passo a passo **1. Cadastre a URL** ```bash Ambiente de teste theme={null} curl -X PUT "https://api.dev.connect.onbeefapp.com.br/v1/merchantOnboarding" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ordersWebhookURL": "https://pdv.example.com/onbeef" }' ``` A resposta é `200` com a URL gravada. Neste exemplo, as notificações chegam em `https://pdv.example.com/onbeef/v1/orderUpdate`. Para trocar a URL, envie a chamada de novo. O painel não tem tela para esse cadastro. **2. Receba a notificação** A Onbeef envia um `POST` com `Content-Type: application/json`: ```json theme={null} { "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c", "eventType": "CREATED", "orderURL": "https://api.dev.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479", "createdAt": "2026-11-12T17:30:00.000000Z", "sourceAppId": "fb08c6b7-a844-43c6-b104-98e70c00fc20", "virtualBrand": null } ``` Os campos são os do polling: `orderId` entra em `GET /v1/orders/{orderId}`, `eventId` identifica o tipo do [evento](/concepts/orders#eventos-e-status) e `createdAt` é a criação do pedido, não a data do evento. Ignore `sourceAppId` e `virtualBrand`. O corpo real vem em uma linha só, sem espaços e com as barras escapadas (`\/`), como no [vetor de teste](#vetor-de-teste). | Header | O que é | | - | - | | `X-App-Signature` | Assinatura do corpo. | | `X-App-MerchantId` | Identificador da loja na Onbeef (UUID). É o `id` de `GET /v1/merchant` e o **ID do Merchant** que a loja vê em **Dados de Integrações**. Não é o `merchant.id` do pedido, que traz o código da loja no PDV. | | `X-App-Id` | Identificador da Onbeef Connect, igual a `sourceAppId`. | **3. Valide a assinatura** `X-App-Signature` é o HMAC-SHA256 do corpo cru, em hexadecimal minúsculo de 64 caracteres. A chave do HMAC é o `client_secret` da chave que cadastrou a URL. Calcule sobre os bytes recebidos, antes de converter o JSON. O corpo traz barras escapadas (`\/`) em `orderURL`, e reescrever o JSON muda a assinatura. ```javascript Node.js theme={null} import crypto from "node:crypto"; import express from "express"; const app = express(); app.post("/onbeef/v1/orderUpdate", express.raw({ type: "application/json" }), (req, res) => { const expected = crypto .createHmac("sha256", process.env.ONBEEF_CLIENT_SECRET) .update(req.body) .digest("hex"); const received = req.get("X-App-Signature") ?? ""; const valid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); if (!valid) return res.sendStatus(401); const event = JSON.parse(req.body); // grave event.orderId, event.eventId e event.eventType antes de responder res.sendStatus(200); }); ``` ```php PHP theme={null} $body = file_get_contents('php://input'); $expected = hash_hmac('sha256', $body, getenv('ONBEEF_CLIENT_SECRET')); $received = $_SERVER['HTTP_X_APP_SIGNATURE'] ?? ''; if (!hash_equals($expected, $received)) { http_response_code(401); exit; } $event = json_decode($body, true); // grave $event['orderId'], $event['eventId'] e $event['eventType'] antes de responder http_response_code(200); ``` Com várias lojas na mesma URL, troque a variável fixa por uma busca pelo `X-App-MerchantId`. Assinatura inválida: responda `401`. A Onbeef conta como falha e tenta de novo. **4. Responda 2xx e processe depois** Grave o evento, responda `200` e consulte o pedido fora da requisição. Depois de gravar o pedido, confirme o evento em `POST /v1/events/acknowledgment`, para ele sair do polling. Junte vários eventos na mesma confirmação: ela conta nas 60 escritas por minuto da loja. ## Vetor de teste Prove a sua validação sem depender de uma notificação real. O corpo é uma linha só, com 342 bytes: ```text theme={null} {"orderId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","eventId":"d6703cc8-9e79-415d-ac03-a4dc7f6ab43c","eventType":"CREATED","orderURL":"https:\/\/api.dev.connect.onbeefapp.com.br\/v1\/orders\/f47ac10b-58cc-4372-a567-0e02b2c3d479","createdAt":"2026-11-12T17:30:00.000000Z","sourceAppId":"fb08c6b7-a844-43c6-b104-98e70c00fc20","virtualBrand":null} ``` | Dado | Valor | | - | - | | `client_secret` | `segredo-de-teste` | | `X-App-Signature` esperado | `dacbcc45e568490a3a18db837aaa3a936428b8aced548e55e6acb44091c8c1c3` | ## Tempos e tentativas A Onbeef espera 5 segundos para conectar e 10 segundos pela resposta. Resposta fora de `2xx` ou demora acima desses tempos conta como falha. | Tentativa | Quando | | - | - | | 1ª | Na hora do evento. | | 2ª | 10 segundos depois da primeira falha. | | 3ª | 60 segundos depois da segunda falha. | Depois da terceira falha, a notificação não é mais enviada. Se o seu servidor ficar fora do ar por mais de 70 segundos, ela se perde. Por isso o polling é obrigatório: consulte [`GET /v1/events:polling`](/api-reference/orders/get-events) a cada 30 segundos, com ou sem webhook. Ele devolve o evento atual de todo pedido que a sua chave ainda não confirmou. Se o pedido avançou nesse intervalo, você recebe o estado novo e não o intermediário. ## Teste No ambiente de teste (sandbox), cadastre uma URL pública do seu servidor de desenvolvimento. Crie um pedido em **Painel de Vendas** > **Novo pedido** e mude o status pelo painel: cada mudança envia uma notificação. Em produção, cadastre a URL de novo com a chave da loja real. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Receba pedidos](/guides/order-flow) > > Polling e confirmação. > [card] [Configurar webhook](/api-reference/merchant/update-merchant) > > Referência de `PUT /v1/merchantOnboarding`. # Integre com a Onbeef Source: https://docs.onbeef.app/index Conecte PDV, ERP ou sistema de logística à Onbeef: preços no catálogo, pedidos no seu sistema e entregas atualizadas. # Integre com a Onbeef Conecte PDV, ERP ou sistema de logística à Onbeef: preços no catálogo, pedidos no seu sistema e entregas atualizadas. ## Por onde começar Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente Sou lojista O que a integração faz na minha loja, quanto custa e como ativar. Sem termos técnicos. Começar por aqui → [Open](/lojistas/overview) Sou desenvolvedor Integrar um PDV, um ERP ou um sistema de entregas pela API, no padrão Open Delivery. Ver a documentação técnica → [Open](/desenvolvedores) ## O que é a integração A integração, chamada Onbeef Connect, liga à Onbeef o sistema que a loja já usa: o do caixa, o de gestão ou o da empresa de entregas. A loja gera uma chave no painel da Onbeef, liga os produtos aos códigos do sistema e entrega a chave ao fornecedor. Com ela, o sistema envia preços e lê os pedidos daquela loja.A Onbeef não cobra pela integração. A loja precisa do plano Expert. ## Como um pedido anda **1. O cliente compra no catálogo online** Ele vê o preço que o sistema da loja enviou. **2. A loja aceita e prepara no painel da Onbeef** É no painel que a loja pesa a carne e ajusta o pedido. **3. O pedido sai para entrega ou fica pronto para retirada** Se a loja usa uma empresa de entregas integrada, ela marca a saída e a entrega. **4. O sistema da loja importa o pedido** Para emitir o cupom. O peso e o valor são os finais quando a loja marca o pedido como entregue. ## O que dá para integrar Uma, duas ou as três partes. Cada sistema usa a sua própria chave. > [card] [Catálogo e preços](/lojistas/catalogo) > > O sistema envia preço e disponibilidade dos produtos ligados a ele. > [card] [Pedidos](/lojistas/pedidos) > > O pedido feito na Onbeef vai para o sistema, para emitir o cupom. > [card] [Entregas](/lojistas/entregas) > > A empresa de entregas recebe o pedido e marca a saída e a entrega. ## O que a integração não faz Não cria pedido na OnbeefO pedido nasce na Onbeef. O sistema recebe, não envia. Não altera itens, peso nem valor pelo sistemaO ajuste é no painel da Onbeef. O sistema pode avançar a etapa do pedido e cancelar. Não leva estoqueAcabou o produto: o sistema envia como indisponível. Não cria promoçãoO sistema envia o preço. A promoção é feita no painel. Não traz clientes nem vendas do balcãoA venda feita fora da Onbeef fica no sistema da loja. Não devolve o que muda no painelO que a loja edita no painel não volta para o sistema. # Ative a integração da sua loja Source: https://docs.onbeef.app/lojistas/ativar Gere a chave no painel da Onbeef, vincule os produtos, entregue a chave ao fornecedor do seu sistema e confira se a integração funcionou. Você gera uma chave no painel da Onbeef, vincula os produtos e entrega a chave ao fornecedor do seu sistema. ## Antes de começar * **Plano Expert.** Sem ele, a tela **Integrações** mostra **Exclusivo do plano Expert**: clique em **Quero ter acesso** para falar com a Onbeef pelo WhatsApp. Com o plano, a chave já vale, sem liberação da Onbeef. * **Permissão.** Se **Integrações** não aparece no menu, peça a permissão ao dono da loja. * **Fornecedor.** Confirme se o sistema integra com a Onbeef, o que ele integra (produtos, pedidos ou os dois) e se cobra. Se não integra, encaminhe a [documentação para desenvolvedores](/desenvolvedores). ## Passo a passo **1. Abra a tela de integrações** Vá em **Configurações** > **Canais e Integrações** > **Integrações**. Se o seu sistema aparece em **Explorar integrações**, clique em **Conectar** e siga a janela no lugar dos passos 2 e 3. **2. Gere a chave** Clique no cartão **Nova chave API**. Em **Nome**, escreva o nome do sistema. Clique em **Adicionar Chave**. **3. Copie o ID e a Chave** A janela **Credenciais Geradas com Sucesso!** mostra o **ID** e a **Chave** uma única vez. Copie os dois e clique em **Continuar**. Não envie ainda. **4. Vincule produtos e categorias** Sem os códigos, o primeiro envio cria produtos repetidos. Veja [Vincule produtos e categorias](/lojistas/vincular-produtos). **5. Entregue a chave ao fornecedor** Mande o **ID** e a **Chave** em conversa particular, nunca em grupo. Diga: "Já preenchi os códigos. Pode fazer o primeiro envio." Se ele precisar da chave antes, avise: "Não envie produtos antes de eu terminar os códigos." **6. Confira** **Produtos:** depois do primeiro envio, a tela **Integrações** mostra o cartão **Status da Integração PDV** como **Ativo**. **Pedidos:** crie um pedido em **Painel de Vendas** > **Novo pedido** e veja com o fornecedor se ele chegou. Avise antes: "Vou criar um pedido de teste. Não emita cupom dele." Depois, cancele o pedido. > [!WARNING] > > A chave dá acesso aos produtos e aos pedidos da loja. Envie só a quem você confia. ### Regras * **O ID certo.** O fornecedor precisa do **ID** da janela do passo 3. O **ID do Merchant**, do botão **Dados de Integrações**, é outro dado. * **Uma chave por sistema e por loja.** Caixa e empresa de entregas usam chaves separadas. ## Desligar ou trocar a chave | Na tela Integrações | O que acontece | | - | - | | Interruptor em **Inativa** | O sistema perde o acesso à loja. Em **Ativa**, a mesma chave volta a valer. | | Ícone de lixeira, **Apagar Chave API** > **Apagar** | O acesso do sistema acaba de vez. Os produtos e os códigos continuam na loja. Confira o **Nome** antes de apagar. | | Perdeu a chave | Gere outra, envie ao fornecedor e apague a antiga. | Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Vincule os produtos](/lojistas/vincular-produtos) > > O passo 4, com as telas. > [card] [Perguntas frequentes](/lojistas/faq) > > O sistema parou, produto duplicou, preço não mudou. # Catálogo integrado Source: https://docs.onbeef.app/lojistas/catalogo Veja o que o seu sistema atualiza nos produtos da Onbeef, o que continua com você no painel e como conferir se o envio deu certo. O seu sistema envia para a Onbeef o preço e a disponibilidade dos produtos. O resto do produto continua com você, no painel. ## Como funciona **1. Você liga os produtos ao seu sistema** Cada produto e cada categoria recebe o código que tem no seu sistema. Veja [Vincule produtos e categorias](/lojistas/vincular-produtos). **2. O seu sistema envia** O preço, a disponibilidade e os produtos novos. De quanto em quanto tempo, pergunte ao fornecedor. **3. A Onbeef grava** Ela acha cada produto pelo código e atualiza o catálogo online em seguida. **4. Você confere** Em **Configurações** > **Canais e Integrações** > **Integrações**, veja o cartão **Status da Integração PDV**. Ele aparece depois do primeiro envio. Atualize a página para ver o resultado mais recente. | No cartão | O que significa | | - | - | | **Ativo** | O último envio deu certo. Não é a situação da chave, que é **Ativa** ou **Inativa**. | | **Pendente** | O envio está em andamento. | | **Erro** | O envio falhou, inteiro ou em parte. Mostre o texto do cartão ao fornecedor. | ## O que acontece com cada informação | Informação | Quem decide | | - | - | | Preço | O seu sistema. O preço que você mudar no painel é trocado no próximo envio. | | Disponível ou indisponível | O seu sistema, quando ele envia essa informação. | | Produto e categoria novos | O seu sistema cria. O produto chega sem os cortes da sua loja: complete no painel. | | Nome e descrição | Você, enquanto o sistema envia só preço e disponibilidade. Se ele enviar o cadastro do produto, o nome do painel é trocado pelo nome do sistema. | | Fotos | As fotos que você pôs no painel ficam. | | Cortes, temperos, complementos, kits, promoções, horários e ordem | Você, no painel. O sistema não mexe e não cria kit. | | Estoque | Não passa pela integração. Acabou o produto: o sistema marca como indisponível. | ### O que pedir ao fornecedor * **Para manter os nomes do painel.** "Envie só preço e disponibilidade. Não reenvie o cadastro dos produtos que já existem." * **Para não encher o catálogo.** "Envie só os produtos que eu vendo online." Produto novo já aparece para o cliente. * **Antes de um envio do catálogo inteiro.** "Me mande antes a lista do que vai nesse envio." * **Se a loja fechada abrir sozinha.** "Envie a situação real da loja, aberta ou fechada, e não sempre aberta." > [!WARNING] > > No envio do **catálogo inteiro**, o produto e a categoria com código que não vierem são excluídos da Onbeef, com as fotos e os cortes. O produto que você criou no painel, sem código, fica. Sumiu um produto? Peça ao fornecedor: "Inclua o produto no envio." Ele volta como novo: cadastre de novo as fotos e os cortes. Produto duplicado e preço que não mudou estão em [Perguntas frequentes](/lojistas/faq). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Vincule os produtos](/lojistas/vincular-produtos) > > Ligue cada produto ao código do seu sistema. > [card] [Para o fornecedor do sistema](/guides/catalog-sync) > > O guia técnico do envio de produtos e preços. # Entregas integradas Source: https://docs.onbeef.app/lojistas/entregas Veja como a empresa de entregas recebe os pedidos da loja com uma chave e marca a saída e a entrega no painel da Onbeef. A empresa de entregas recebe os pedidos da sua loja com uma chave que você gera no painel. Quando o entregador sai e quando ele entrega, o pedido muda sozinho na Onbeef. ## Como funciona **1. O cliente faz um pedido de entrega** A empresa de entregas recebe o pedido com endereço, cliente e valor a cobrar. **2. Você aceita e prepara no painel** Aceitar, pesar em **Ajustar o pedido** e marcar **Pronto** continua com a loja. **3. O entregador sai** A empresa de entregas marca a saída no sistema dela. O pedido muda para **Em rota**. **4. O entregador entrega** O pedido muda para **Entregue**. ### Regras * **Uma chave só para ela.** Não reaproveite a chave do caixa: gere outra, com o nome da empresa de entregas. * **A chave dá acesso a tudo.** Não existe chave só de pedidos: ela consegue ler e alterar produtos e pedidos da loja, como a chave do caixa. Entregue só a quem você confia. * **Ela recebe todos os pedidos.** Também os de retirada, com os dados do cliente. Ela trata só os de entrega. * **Você não vê o entregador.** Nome, localização e previsão ficam no sistema dela. O painel mostra só **Em rota** e **Entregue**. * **O painel continua valendo.** Você também pode marcar **Em rota** e **Entregue** no painel. A empresa de entregas fica sabendo, e do cancelamento também. ## Como ativar 1. Pergunte à empresa de entregas se ela já integra com a Onbeef. Se não, encaminhe a ela a [documentação para empresas de entrega](/desenvolvedores/logistica). 2. Abra **Configurações** > **Canais e Integrações** > **Integrações**. 3. Se ela aparece em **Explorar integrações**, clique em **Conectar** e siga a janela. 4. Se não aparece, gere uma chave em **Nova chave API** e envie o **ID** e a **Chave** a ela em conversa particular. As telas estão em [Ative a integração](/lojistas/ativar). Não há códigos de produto a preencher. ## Perguntas comuns > [accordion] Posso ter o sistema do caixa e a empresa de entregas juntos? > > Sim. Gere uma chave para cada um. > [accordion] O entregador saiu e o pedido não ficou Em rota > > Em pedido pago online com produto por peso, ajuste o peso em **Ajustar o pedido** antes de o entregador sair. Sem isso, a saída marcada pela empresa de entregas pode não ser registrada. Se ele já saiu, ajuste o peso e mova o pedido para **Em rota** no **Painel de Vendas**. > [accordion] E se a empresa de entregas não puder fazer a entrega? > > O pedido não muda sozinho na Onbeef. Combine com ela como você será avisado. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Ative a integração](/lojistas/ativar) > > As telas para gerar a chave. > [card] [Para a empresa de entregas](/desenvolvedores/logistica) > > A documentação técnica para ela integrar. # Perguntas frequentes Source: https://docs.onbeef.app/lojistas/faq Respostas diretas para as dúvidas de lojistas: custo, produto duplicado, preço que não mudou, peso diferente no sistema e chave que parou. ## Custo e chave > [accordion] Tem custo? > > Não. A Onbeef não cobra pela integração, mas a loja precisa do plano **Expert**. O fornecedor pode cobrar pela parte dele. > [accordion] O sistema parou de funcionar > > Em **Configurações** > **Canais e Integrações** > **Integrações**, confira: > > 1. **A chave está Inativa.** Mude para **Ativa**: a mesma chave volta a valer. > 2. **A chave sumiu da tela.** Alguém apagou: gere outra. > 3. **A tela mostra Exclusivo do plano Expert.** A loja saiu do plano, e as chaves ficaram inativas sozinhas. Clique em **Quero ter acesso** e, com o plano de volta, deixe a chave em **Ativa**. > [accordion] Apaguei a chave. Perco os produtos? > > Não. Só o acesso do sistema acaba: os produtos e os códigos continuam na loja. Para voltar, gere outra chave. ## Produtos e preços > [accordion] Meu produto ou minha categoria duplicou > > O original estava sem o código do seu sistema. Veja como resolver em [Vincule produtos e categorias](/lojistas/vincular-produtos#como-resolver). > [accordion] Mudei o preço no sistema e não mudou na Onbeef > > Confira: > > 1. O produto tem o **Código de integração com PDV** igual ao do sistema. > 2. Pergunte ao fornecedor: "O último envio desse produto deu certo?" > 3. O cartão **Status da Integração PDV** não está em **Erro**. Se estiver, mostre o texto do cartão ao fornecedor. > > O catálogo online muda logo depois que o envio dá certo. Se o painel mostra o preço novo e o catálogo online não, fale com o suporte da Onbeef. > [accordion] Desativei um produto na Onbeef e ele voltou > > O seu sistema enviou o produto como disponível. Peça ao fornecedor: "Envie só o preço desse produto, sem a disponibilidade." Não desative o produto no seu sistema: isso pode bloquear a venda no balcão. Produto desativado no painel sai do catálogo online e continua no pedido criado pela loja. ## Pedidos e fidelidade > [accordion] O pedido chegou no sistema com peso diferente > > O sistema importou antes de você pesar. Veja as regras em [Pedidos integrados](/lojistas/pedidos#regras). > [accordion] Dei um desconto e o sistema recebeu o valor cheio > > Você usou **Ajustar valor**, que muda só o total na Onbeef. Use **Desconto personalizado**: ele chega ao sistema, mas só existe em pedido pago na entrega. Em pedido já pago pelo site não há desconto que chegue ao sistema. > [accordion] Uso os pontos do meu sistema ou a fidelidade da Onbeef? > > A da Onbeef. Ela calcula os pontos sobre o pedido feito nela, com as regras do programa da sua loja. A integração não leva pontos de um lado para o outro. ## A quem recorrer * **Suporte do seu sistema.** Dúvida sobre o sistema e sobre o que ele envia e importa. * **Suporte da Onbeef.** Dúvida sobre o painel, o plano e o catálogo online: clique em **Precisa de Ajuda?**, no menu lateral do painel. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Vincule os produtos](/lojistas/vincular-produtos) > > Produto duplicado e categoria vazia. > [card] [Glossário](/lojistas/glossario) > > Os termos da integração. # Glossário Source: https://docs.onbeef.app/lojistas/glossario Os termos que aparecem na integração e nas telas do painel, explicados em linguagem do balcão. Os termos desta documentação e os nomes que você vê nas telas do painel. ## Quem é quem | Termo | O que significa | | - | - | | **Seu sistema** | O programa que a loja usa para vender e emitir cupom: caixa, PDV ou ERP. | | **PDV** e **ERP** | PDV é o sistema do caixa. ERP é o sistema de gestão da loja. PDV aparece no nome de alguns campos do painel. | | **Fornecedor do sistema** | A empresa que fornece o seu sistema. É quem configura a integração e passa os códigos. | | **Painel de Vendas** | A tela do painel com os pedidos da loja. | | **Catálogo online** | A loja virtual onde o cliente faz o pedido. | ## Chave | Termo | O que significa | | - | - | | **Chave** | A senha que libera um sistema para acessar a sua loja. Tem duas partes, **ID** e **Chave**, e é gerada no cartão **Nova chave API**. | | **API** | Palavra que aparece em alguns botões do painel. Leia como "integração". | | **ID do Merchant** | O código da loja na Onbeef, mostrado no botão **Dados de Integrações**. Não é o **ID** da chave. | | **Ativa** e **Inativa** | A situação da chave. **Inativa**, o sistema perde o acesso. **Ativa**, a mesma chave volta a valer. | | **Plano Expert** | O plano da Onbeef que libera a tela **Integrações**. | ## Produtos | Termo | O que significa | | - | - | | **Código de integração com PDV** | O código do produto ou da categoria no seu sistema. É por ele que a Onbeef reconhece o produto. | | **Código da balança** | O código do produto na balança. Não é o código do seu sistema. | | **Códigos & Balança** | O botão do menu **Catálogo** que abre a lista de produtos para preencher os códigos. | | **Vincular** | Preencher o **Código de integração com PDV** em um produto ou em uma categoria. | | **Envio do catálogo inteiro** | O envio com todos os produtos de uma vez. O que tem código e não vem nele é excluído da Onbeef, com fotos e cortes. | | **Status da Integração PDV** | O cartão da tela **Integrações** que mostra o resultado do último envio: **Ativo**, **Pendente** ou **Erro**. Não é a situação da chave. | ## Pedidos | Termo | O que significa | | - | - | | **Importar o pedido** | Quando o seu sistema copia o pedido da Onbeef para emitir o cupom. | | **Ajustar o pedido** | O botão do pedido que corrige peso e itens. O sistema recebe a correção. | | **Desconto personalizado** | O campo do pedido para dar desconto. O sistema recebe esse desconto. | | **Ajustar valor** | O botão do pedido que muda só o total. O sistema não recebe essa mudança. | | **Pendente**, **Em preparo**, **Pronto**, **Em rota**, **Entregue**, **Cancelado** | As etapas do pedido. O seu sistema é avisado de cada mudança. | > [card] [O que a integração faz](/lojistas/overview) > > O que ela faz e o que não faz. > [card] [Perguntas frequentes](/lojistas/faq) > > As dúvidas mais comuns. # O que a integração faz Source: https://docs.onbeef.app/lojistas/overview Entenda o que a integração entre o seu sistema e a Onbeef faz, o que ela não faz, quanto custa e onde você faz cada coisa. A integração liga à Onbeef o sistema que você já usa na loja para vender e emitir cupom, como o do caixa. Ela mantém em dia o preço e a disponibilidade dos produtos e leva o pedido para o seu sistema emitir o cupom. **Quanto custa.** A Onbeef não cobra pela integração. A loja precisa estar no plano **Expert**. O fornecedor do seu sistema pode cobrar pela parte dele: pergunte a ele. ## Como funciona 1. Você gera uma chave no painel da Onbeef. 2. Você liga os produtos e as categorias da Onbeef aos códigos do seu sistema. 3. Você entrega a chave ao fornecedor do seu sistema. Só depois do passo 2: sem os códigos, o primeiro envio cria produtos repetidos. 4. O seu sistema passa a enviar o preço e a disponibilidade desses produtos. 5. O pedido chega pela Onbeef e você cuida dele no painel, como hoje. 6. O seu sistema importa o pedido para emitir o cupom. As telas estão em [Ative a integração](/lojistas/ativar). ## O que ela faz e o que não faz | Faz | Não faz | | - | - | | Atualiza o preço dos produtos ligados ao seu sistema | Não cria promoção: promoção você faz no painel | | Marca o produto como disponível ou indisponível, quando o sistema envia essa informação | Não leva estoque de um lado para o outro | | Cria os produtos e as categorias novos que o sistema enviar | Não manda para o sistema o que você muda no painel | | Leva o pedido da Onbeef para o seu sistema | Não cria pedido na Onbeef | | Deixa a empresa de entregas marcar a saída e a entrega | Não traz clientes nem vendas do balcão | | | Não leva pontos de fidelidade de um lado para o outro | * **Fidelidade.** Use o programa de fidelidade da Onbeef, e não um programa de pontos do seu sistema. A Onbeef calcula os pontos sobre o pedido feito nela, com as regras do programa da sua loja. * **Produto novo.** O que o sistema envia já aparece no catálogo online. Combine com o fornecedor quais produtos ele envia: por exemplo, só os do açougue, sem carvão e bebida. ## Onde você faz cada coisa | Tarefa | Onde | | - | - | | Aceitar, pesar, ajustar e entregar o pedido | Painel da Onbeef | | Emitir o cupom | Seu sistema | | Mudar o preço e marcar produto em falta | Seu sistema | | Cortes, temperos, promoções e horários | Painel da Onbeef | Dúvida sobre o seu sistema vai para o fornecedor dele. Dúvida sobre o painel vai para a Onbeef. Veja [A quem recorrer](/lojistas/faq#a-quem-recorrer). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente ## Próximos passos > [card] [Ative a integração](/lojistas/ativar) > > As telas, passo a passo. > [card] [Vincule os produtos](/lojistas/vincular-produtos) > > O passo que mais falha. > [card] [Catálogo integrado](/lojistas/catalogo) > > O que o sistema atualiza. > [card] [Pedidos integrados](/lojistas/pedidos) > > Quando ajustar o pedido. # Pedidos integrados Source: https://docs.onbeef.app/lojistas/pedidos Veja como o pedido da Onbeef chega ao seu sistema, onde você faz cada etapa, quando ajustar o peso e como dar desconto. O pedido feito na Onbeef vai para o seu sistema com itens, cliente, endereço e pagamento. Você cuida dele no painel, e o seu sistema emite o cupom. ## Como funciona **1. O pedido chega no painel** Pedido pago por PIX no catálogo online só segue para o seu sistema depois que o cliente paga. **2. Você aceita e prepara no painel** Como hoje. **3. Você pesa e ajusta o pedido** Abra o pedido e clique em **Ajustar o pedido**, ou bipe a etiqueta da balança. A Onbeef recalcula o valor. **4. Você avança o pedido até Entregue** Marque **Entregue** em todo pedido, também nos de retirada: só aí o pedido para de mudar. **5. O seu sistema importa o pedido** Pergunte ao fornecedor: "O sistema importa o pedido quando ele chega, quando fica **Pronto** ou quando fica **Entregue**?" ### Regras * **Ajuste antes de marcar Pronto.** Pedido pago na entrega aceita ajuste até **Entregue**. Pedido pago online aceita um ajuste só, antes de sair para entrega ou, na retirada, antes de **Pronto**. * **O ajuste não avisa o sistema.** Se ele importou antes de você pesar, fica com o peso antigo. Peça ao fornecedor: "Consulte o pedido de novo depois que eu marcar **Entregue**, antes de emitir o cupom." * **Desconto.** Só em pedido pago na entrega: clique em **adicionar desconto**, preencha **Desconto personalizado** e clique em **Aplicar**. Em pedido pago online não há desconto que chegue ao seu sistema. * **Mudou no sistema, não muda na Onbeef.** Vale para item, peso e valor. > [!WARNING] > > Não use **Ajustar valor** em loja integrada. Esse botão muda só o total na Onbeef: o seu sistema recebe a soma dos itens, com o valor antigo. Use **Ajustar o pedido** para peso e quantidade e **Desconto personalizado** para desconto. ## O que o seu sistema recebe | Você faz no painel | O que chega ao sistema | | - | - | | Aceita, marca **Pronto**, **Em rota** ou **Entregue**, ou cancela | Aviso da mudança. | | Usa **Ajustar o pedido** ou **Desconto personalizado** | Nenhum aviso. O sistema vê a mudança quando consulta o pedido. | Cupom, desconto de fidelidade e taxa de entrega também chegam, separados. ## Perguntas comuns > [accordion] Quais pedidos vão para o sistema? > > Os do catálogo online e os que a loja cria em **Painel de Vendas** > **Novo pedido**. Venda registrada no tablet de fidelidade não vai. O painel continua mostrando todos. > [accordion] O meu sistema pode aceitar ou cancelar o pedido? > > Depende do sistema: a integração permite avançar a etapa e cancelar. Se ele cancelar, o pagamento online é devolvido ao cliente. > [accordion] O item chegou ao sistema sem o código do produto > > O produto não está ligado ao seu sistema. Veja [Vincule produtos e categorias](/lojistas/vincular-produtos). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Entregas integradas](/lojistas/entregas) > > Quem marca a saída e a entrega. > [card] [Para o fornecedor do sistema](/guides/order-import) > > Quando importar o pedido. # Vincule produtos e categorias ao seu sistema Source: https://docs.onbeef.app/lojistas/vincular-produtos Ligue os produtos e as categorias que a loja já tem aos códigos do seu sistema. Evite produto duplicado e categoria vazia. Vincular é dizer à Onbeef qual produto dela é qual produto do seu sistema. Exemplo: a picanha é o produto 1001 no seu sistema, então você escreve 1001 na picanha da Onbeef. Faça depois de gerar a chave (a coluna do código só aparece aí) e antes de entregá-la ao fornecedor. Nome igual não conta: a Onbeef só reconhece o produto pelo código. ## O que acontece sem o código | Situação | Resultado | | - | - | | Produto ou categoria sem código | O sistema cria outro igual, sem as suas fotos e cortes. | | Preço enviado para produto sem código | O preço não muda. O cartão **Status da Integração PDV** mostra **Erro** com "Itens não encontrados". | ## Passo a passo **1. Peça os códigos ao fornecedor** Diga: "Me mande o código de cada produto e de cada categoria que o sistema vai enviar para a Onbeef." Lá, a categoria pode se chamar grupo ou seção. **2. Preencha os produtos** No menu **Catálogo**, clique em **Códigos & Balança**. Digite os códigos na coluna **Código de integração com PDV** e clique em **Salvar Identificadores**: um clique salva todos. **3. Preencha as categorias** Em **Catálogo** > **Produtos & Categorias**, abra a edição de cada categoria. Marque **Vincular esta categoria ao seu sistema de PDV** e preencha o **Código de integração com PDV**. **4. Entregue a chave e libere o envio** Confira com a lista se ficou algo sem código. Depois, diga: "Pode fazer o primeiro envio." ### Regras * **Aproveite o que já existe.** Vincule em vez de recriar: se você excluir as categorias para o sistema enviar tudo de novo, perde as fotos e os cortes. * **É digitado na tela.** O fornecedor não preenche pela integração, e a importação de arquivo preenche só o **Código da balança**, outro campo. * **Um código, um lugar.** Se a tela perguntar **Salvar com códigos duplicados?**, clique em **Revisar**. * **Igual ao do sistema.** Com os zeros à esquerda. > [!WARNING] > > Excluir uma categoria exclui junto os produtos que estão só nela. Confira antes se é a que o sistema criou, e não a sua. ## Como resolver > [accordion] Meu produto duplicou > > Exclua o que o sistema criou. Depois, preencha o código no original. Nessa ordem: o código não pode estar nos dois. > [accordion] Duplicou a loja inteira > > Peça ao fornecedor: "Pare os envios até eu avisar." Exclua as categorias que o sistema criou: os produtos repetidos saem junto. Preencha os códigos e libere. > [accordion] Apareceu uma categoria vazia ou repetida > > Abra a categoria que o sistema criou e anote o código dela. Exclua essa categoria e preencha o código anotado na sua. O aviso "Já existe outra categoria com o código de integração com PDV informado" quer dizer que a outra ainda não foi excluída. Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [Catálogo integrado](/lojistas/catalogo) > > O que o sistema atualiza. > [card] [Para o fornecedor do sistema](/guides/catalog-linking) > > O guia técnico. # Faça a primeira chamada Source: https://docs.onbeef.app/quickstart Gere a chave na loja de teste, peça o token e consulte a loja pela API, com curl em formulário e em JSON. Com o login do painel de teste em mãos, em 10 minutos você gera uma chave, troca a chave por um token e consulta a loja pela API. Tudo acontece no ambiente de teste (sandbox), sem tocar em loja real. Implemente a autenticação da Onbeef Connect API no meu sistema e faça a primeira chamada, seguindo [https://docs.onbeef.app/quickstart.md](https://docs.onbeef.app/quickstart.md) e [https://docs.onbeef.app/agent-ready.md](https://docs.onbeef.app/agent-ready.md) ## Passo a passo **1. Peça a loja de teste** Escreva para [rafael@onbeefapp.com.br](mailto:rafael@onbeefapp.com.br) dizendo qual é o seu sistema. A Onbeef cria uma loja de teste e envia o login do [painel de teste](https://lojista.dev.onbeefapp.com.br/). **2. Gere a chave** A chave é o par de credenciais que identifica o seu sistema em uma loja. No painel de teste: 1. Abra **Configurações** > **Canais e Integrações** > **Integrações**. 2. Clique no cartão **Nova chave API**. 3. Preencha o campo **Nome** com o nome do seu sistema e clique em **Adicionar Chave**. 4. Na janela **Credenciais Geradas com Sucesso!**, copie os dois valores e clique em **Continuar**. | No painel | Na API | | - | - | | **ID** | `client_id` | | **Chave** | `client_secret` | Os dois valores aparecem uma única vez. Perdeu a **Chave**: apague a chave e gere outra. **3. Peça o token** Envie as credenciais para `POST /oauth/token`. O endpoint aceita formulário (o formato do padrão Open Delivery) e JSON. ```bash Ambiente de teste (formulário) theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=" \ -d "client_secret=" ``` ```bash Ambiente de teste (JSON) theme={null} curl -X POST https://api.dev.connect.onbeefapp.com.br/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "", "client_secret": "" }' ``` A resposta traz o token e a validade em segundos. O token vale 12 horas: guarde e reaproveite. ```json Resposta theme={null} { "token_type": "Bearer", "expires_in": 43200, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." } ``` **4. Consulte a loja** Envie o token no header `Authorization`: ```bash Ambiente de teste theme={null} curl https://api.dev.connect.onbeefapp.com.br/v1/merchant \ -H "Authorization: Bearer " ``` Um `200` com os dados da loja confirma que a autenticação funcionou. As listas trazem as categorias e os produtos da loja de teste. ```json Resposta (resumida) theme={null} { "lastUpdate": "2026-11-12T14:03:11.000000Z", "TTL": 600, "id": "0b8f6c1e-2d4a-4c57-9a55-6f1f0e2f7a10", "status": "AVAILABLE", "categories": [], "products": [] } ``` ## Deu erro? | Resposta | Motivo mais comum | O que fazer | | - | - | - | | `401` `The client credentials were incorrect.` | **ID** ou **Chave** errados, ou chave de produção na URL de teste. | Confira os dois valores e o ambiente. | | `401` `Token not provided` | O header não foi enviado ou não começa com `Bearer `. | Envie `Authorization: Bearer `. | | `403` `Integration is not active` | A chave está **Inativa** no painel. | Ative a chave na tela **Integrações**. | O **ID do Merchant**, que aparece em **Dados de Integrações**, não é o `client_id`. A lista completa de erros está em [Autenticação](/authentication/overview#erros). ## Teste Com a primeira chamada funcionando, crie um pedido de teste e acompanhe os eventos. Veja [Ambiente de teste](/environments/sandbox#crie-pedidos-de-teste). Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente > [card] [PDV ou ERP](/desenvolvedores/pdv) > > O roteiro para catálogo e pedidos. > [card] [Empresa de entregas](/desenvolvedores/logistica) > > O roteiro para receber pedidos e informar a entrega. > [card] [Autenticação](/authentication/overview) > > As regras da chave e do token. > [card] [Ambiente de teste](/environments/sandbox) > > Pedidos de teste e o que testar.