Entenda a gestão da loja e do catálogo

O merchant representa sua loja na Onbeef. Ele reúne disponibilidade, categorias e produtos.

Estrutura principal

Campo	O que representa
`id`	Identificador único da loja.
`status`	Chave geral de recebimento de pedidos.
`lastUpdate`	Data da última atualização.
`TTL`	Tempo de cache dos dados, em segundos.
`categories`	Categorias exibidas no catálogo.
`products`	Produtos disponíveis na loja.

Consulte a estrutura completa em GET /v1/merchant.

Disponibilidade

AVAILABLE

A chave geral de recebimento está ligada. A loja pode receber novos pedidos.

UNAVAILABLE

A chave geral de recebimento está desligada. O checkout bloqueia novos pedidos.

O horário de funcionamento é independente desse status. Uma loja AVAILABLE ainda pode recusar pedidos fora do horário cadastrado, salvo quando estiver configurada para recebê-los. Categorias organizam a vitrine e controlam a ordem de exibição. Produtos armazenam nome, preço, unidade, imagens e disponibilidade. As categorias referenciam os produtos por ID. O mesmo produto pode aparecer em mais de uma categoria.

Identificadores

Produtos e categorias carregam mais de um código. Cada um tem um papel diferente:

Campo	Quem define	Para que serve
`id`	Onbeef (UUID)	Identificador interno. Não é aceito como identificador no `merchantUpdate`.
`pdv_external_id`	Seu PDV, ou o lojista no painel	O código que a sincronização usa para localizar produtos e categorias. É a ele que `itemId` e os ids do `merchantUpdate` devem corresponder.
`externalCode`	Lojista ou sincronização	Código de balança do produto, usado pelos recursos de balança do painel. Não localiza produtos na integração.
`ean`	Sincronização	Código de barras. Apenas informativo.
`sku`	—	Apenas leitura; sem caminho de escrita via API.

Um produto sem pdv_external_id é invisível para a sincronização: ITEM e ITEM_OFFER retornam FAIL com “Itens não encontrados”, e MERCHANT cria um produto novo em vez de atualizar o existente.

Fluxo de atualização

Vincule o catálogo existente

Produtos e categorias já cadastrados precisam do código de integração com PDV (pdv_external_id) preenchido no painel para serem reconhecidos pela sincronização. Veja o passo a passo em Sincronizar catálogo.

Envie o catálogo

Use PUT /v1/merchantUpdate para sincronizar categorias, produtos e ofertas.

Consulte o processamento

Use GET /v1/merchantStatus para verificar o resultado da sincronização.

Sincronizar o catálogo

Siga o fluxo completo de publicação e atualização.

​Estrutura principal

​Disponibilidade

AVAILABLE

UNAVAILABLE

​Identificadores

​Fluxo de atualização

Sincronizar o catálogo

Estrutura principal

Disponibilidade

Identificadores

Fluxo de atualização