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

# Agentes de código

> 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](https://docs.onbeef.app/guides/catalog-sync.md), [pedidos](https://docs.onbeef.app/guides/order-flow.md), [webhook](https://docs.onbeef.app/guides/orders-webhook.md) e [entregas](https://docs.onbeef.app/guides/delivery-flow.md).

## 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 <access_token>` 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": <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](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)


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