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:
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:- O sistema é PDV ou ERP, empresa de entregas ou só lê (CRM, atendimento)?
- PDV ou ERP: catálogo, pedidos ou os dois?
- Pedidos: o PDV precisa do pedido só para faturar, ou antes, para separação?
- Catálogo: a loja já tem produtos na Onbeef?
- Onde fica o código e qual é a stack?
- 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(painelhttps://lojista.dev.onbeefapp.com.br). - Produção:
https://api.connect.onbeefapp.com.br(painelhttps://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_ide a Chave é oclient_secret. Aparecem uma única vez. - Uma chave por loja. A chave de um ambiente não funciona no outro: causa mais comum de
401,404e500no 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)
POST /oauth/tokencomgrant_type=client_credentials,client_ideclient_secret, emapplication/x-www-form-urlencodedou JSON.- Reaproveite o
access_tokenaté perto deexpires_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. - Envie
Authorization: Bearer <access_token>em toda chamada de/v1. Teste comGET /v1/merchant.
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ê.- Escolha o gatilho pela pergunta 3:
- Só fatura: importe no
DELIVERED. Filtre comeventType=DELIVERED&eventType=CANCELLEDe confirme oCANCELLEDsem faturar. - Precisa antes: aceite
READY_FOR_PICKUP,DISPATCHEDouDELIVERED, o que chegar primeiro. Filtre comeventType=READY_FOR_PICKUP&eventType=DISPATCHED&eventType=DELIVERED&eventType=CANCELLEDe consulte o pedido de novo noDELIVERED, antes de faturar.
- Só fatura: importe no
- 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. - Opcional, para tempo real: webhook (https://docs.onbeef.app/guides/orders-webhook.md). Cadastre a URL base com
PUT /v1/merchantOnboarding: a Onbeef chamaPOST {URL base}/v1/orderUpdate. Com várias lojas na mesma URL, escolha a Chave pelo headerX-App-MerchantId, oiddevolvido porGET /v1/merchant. - Para cada evento do gatilho, consulte
GET /v1/orders/{orderId}, grave o pedido e só então confirme comPOST /v1/events/acknowledgment, vários eventos em uma chamada. - Ofereça um botão “atualizar pedido da Onbeef”, que consulta o pedido de novo.
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 e https://docs.onbeef.app/guides/catalog-linking.md- 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.
- Envie
PUT /v1/merchantUpdateconforme a situação (payload de cada caso no guia):- Preço:
ITEM_OFFERcomitemIdeprice.value. Semstatus, só o preço muda. - Produto acabou, voltou ou saiu de linha: o mesmo
ITEM_OFFER, comstatusUNAVAILABLEouAVAILABLE. - Nome, descrição, foto ou código de balança:
ITEMcomidename. - Produto ou categoria nova:
MERCHANTcomonlyAddProducts: true.
- Preço:
- O envio completo (
MERCHANTsemonlyAddProducts: 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. EnvieitemOfferIdem toda categoria: sem a chave, nada é removido e o envio termina emFAIL. Só quando o PDV é a única fonte do catálogo, e avise o usuário antes. - Todo
MERCHANTleva emupdatedObjects[0].ido código da loja no PDV, como"LOJA-01"(pergunte ao usuário). Ele volta emmerchant.idde cada pedido. Sem ele, o envio termina emFAIL. - Todo
MERCHANTexigemerchantStatus, aplicado na hora:AVAILABLEfixo reabre a loja que o lojista fechou. LeiastatusemGET /v1/merchante reenvie o mesmo valor. A leitura pode estar até 10 minutos atrasada: eviteMERCHANTlogo depois de a loja abrir ou fechar. - Uma sincronização por vez, com vários produtos em
updatedObjects. ConsulteGET /v1/merchantStatusaté sair dePROCESSING: sóSUCCESSé bom (o catálogo online muda em seguida), e emFAILmostre omoreInfo. Passou de 5 minutos emPROCESSING: envie de novo.
6. Empresa de entregas
Leia antes https://docs.onbeef.app/guides/delivery-flow.md- Autenticação, polling com
start_ate confirmação como na seção 4. Semstart_at, um pedido antigo parado em Pronto aciona um entregador. - Chegam os eventos de todos os pedidos da loja: trate só
type: DELIVERYe confirme os de retirada sem processar. - Chame o entregador no
CONFIRMEDou noREADY_FOR_PICKUP. Pedido agendado: use a janela emschedule. - 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.
- Chame
dispatchna saída, só depois doREADY_FOR_PICKUPou no mínimo doCONFIRMED, edeliveredna entrega. Não chameconfirmnemreadyForPickup. - No
CANCELLED, dispense o entregador. Entrega que não pôde ser feita: avise a loja e não chamerequestCancellation, que estorna o cliente. - 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 pelostatus. 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 deRetry-After. 202e204só confirmam o recebimento. No catálogo, o resultado está emGET /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_atem 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 ostart_at7 dias e ignore o pedido já entregue antes (em entrega,delivery.deliveryDateTimeanterior à 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_REQUESTEDeCANCELLATION_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 resposta202não avisa da recusa. ConfiralastEventantes. eventIdidentifica o tipo do evento. Deduplique pelo parorderId+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
discountse entra emtotal.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ó semethodforCASH,PIX,CREDIT,DEBIT,FOOD_VOUCHERouMEAL_VOUCHERe 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 emschedule; em retirada,takeout.takeoutDateTime. iddo item é o código do PDV, no catálogo e no pedido.externalCodeé o código de balança.idem UUID no pedido: produto não vinculado.unitaceita só"KG"ou"UN", em maiúsculas. ComKG, 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 oclient_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
SUCCESSem 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
- Índice: https://docs.onbeef.app/llms.txt
- Tudo em um arquivo: https://docs.onbeef.app/llms-full.txt
- Erros e limites: https://docs.onbeef.app/api-reference/errors.md
