Skip to main content
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, é o que ele segue quando você cola o prompt. Se você é um agente de código, vá direto para ela.

Deixe o agente implementar

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, pedidos, webhook e entregas.

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

Peça para o agente ler a documentação antes de escrever código e diga o que o seu sistema faz:
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.

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 <access_token> em toda chamada de /v1. Teste com GET /v1/merchant.
Detalhes: 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-flow.md e 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). 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. Leia antes https://docs.onbeef.app/guides/catalog-sync.md e 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
  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": <eventId>, "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
  • 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