> ## 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.

# Vincule uma loja que já tem produtos

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

**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 <access_token>'
```

```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](https://docs.onbeef.app/guides/catalog-sync.md#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](https://docs.onbeef.app/guides/catalog-sync.md), 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](https://docs.onbeef.app/guides/catalog-sync.md#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](https://docs.onbeef.app/concepts/merchant.md#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](https://docs.onbeef.app/guides/catalog-sync.md)
>
> O que enviar em cada situação.

> [card] [Para o lojista: vincular produtos](https://docs.onbeef.app/lojistas/vincular-produtos.md)
>
> O passo a passo das telas.


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