Skip to main content
PUT
Sincronize o catálogo
Envie o catálogo completo ou atualize itens e ofertas específicos. Escolha o formato de updatedObjects pelo campo entityType. A API responde de forma assíncrona. Depois do envio, consulte GET /v1/merchantStatus para verificar o resultado.
A configuração do webhook de pedidos é opcional para sincronizar o catálogo. Para receber notificações de pedidos, configure PUT /v1/merchantOnboarding e consulte o guia Webhook de pedidos.

​
Corpo da requisição

Envie um corpo application/json.

​
Campos comuns

​
string
required
Define o formato de updatedObjects. Valores aceitos:
  • MERCHANT: sincroniza a loja, as categorias, os itens e as ofertas em uma estrutura aninhada.
  • ITEM: atualiza produtos existentes em uma lista plana.
  • ITEM_OFFER: atualiza preço e disponibilidade de produtos existentes em uma lista plana.
​
string
Obrigatório quando entityType é MERCHANT. Valores aceitos: AVAILABLE e UNAVAILABLE.AVAILABLE liga a chave geral de recebimento de pedidos. UNAVAILABLE desliga essa chave e bloqueia novos pedidos no checkout.O campo não representa o horário de funcionamento. Uma loja pode estar AVAILABLE e não receber pedidos fora do horário cadastrado.Com ITEM ou ITEM_OFFER, o campo é aceito e ignorado.
​
boolean
default:"false"
Tem efeito apenas quando entityType é MERCHANT.
  • true: adiciona ou atualiza os dados enviados sem desassociar produtos nem remover registros do catálogo.
  • false: substitui as associações entre categorias e produtos pelo conteúdo enviado. Também permite remover do catálogo categorias e produtos vinculados ao PDV que não aparecem no payload.
Com ITEM ou ITEM_OFFER, o campo é ignorado.

​
O que cada entityType atualiza

Os três formatos têm alcances diferentes. Use a tabela para escolher: Recomendação de uso:
  • MERCHANT: carga inicial e mudanças estruturais (novas categorias, novos produtos, remoções).
  • ITEM: dados cadastrais de produtos existentes.
  • ITEM_OFFER: o dia a dia de preço e disponibilidade.
Estoque não é atualizado por nenhum formato. O campo stock de GET /v1/merchant é apenas leitura.

​
Formato de updatedObjects

O conteúdo de updatedObjects muda conforme entityType. Não misture os formatos.
Use MERCHANT para enviar a estrutura aninhada da loja, com categorias, itens e ofertas.
​
array
required
Lista de objetos de loja. O primeiro objeto precisa conter id.
​
string
required
Identificador da loja no seu PDV. A Onbeef armazena esse valor como pdv_external_id.Se o primeiro objeto não tiver id, nada será processado e a sincronização terminará com FAIL.
​
array
Categorias do catálogo.
  • id (string, obrigatório): identificador estável da categoria no seu PDV.
  • name (string, obrigatório): nome de exibição da categoria.
  • index (integer): posição da categoria. Esse valor é usado apenas na criação.
  • status (string): AVAILABLE ou UNAVAILABLE.
  • itemOfferId (array of strings): IDs das ofertas associadas à categoria.
Apesar do nome no singular, itemOfferId recebe uma lista de IDs.Uma categoria sem id ou name é descartada e reportada como malformada.
​
array
Ofertas que relacionam itens às categorias e definem preço e disponibilidade.
  • id (string, obrigatório): identificador da oferta. Deve corresponder a um valor presente em category.itemOfferId.
  • itemId (string, obrigatório): identificador do item associado. Deve corresponder a item.id.
  • price.value (number, obrigatório): preço aplicado ao produto.
  • status (string): AVAILABLE ou UNAVAILABLE. Este campo define a disponibilidade do produto neste formato.
Uma oferta sem id não pode ser alcançada pelas categorias. Os produtos relacionados a ela são descartados e reportados como malformados.
​
array
Dados dos produtos referenciados pelas ofertas.
  • id (string, obrigatório): identificador estável do item no seu PDV. A Onbeef armazena esse valor como pdv_external_id do produto.
  • name (string, obrigatório): nome de exibição do produto. Usado apenas na criação: em produtos existentes, o nome cadastrado pelo lojista é preservado.
  • description (string): descrição do produto. Usada apenas na criação, como o name.
  • externalCode (string): código de balança do produto, usado pelos recursos de balança do painel. Não é usado para localizar produtos na integração.
  • ean (string): código de barras EAN. Apenas informativo.
  • unit (string): KG ou UN. Define o tipo do produto apenas na criação. Depois de definido, o tipo não pode ser alterado e novos valores são ignorados.
  • serving (integer): número de pessoas que a porção serve. Envie um número; texto é convertido para 0.
  • nutritionalInfo (object): informações nutricionais.
  • image (object): imagem no formato { "url": "https://..." }.
O item não carrega preço nem disponibilidade neste formato. Use itemOffer.price.value e itemOffer.status.
O encadeamento segue esta ordem: category.itemOfferId referencia itemOffer.id, e itemOffer.itemId referencia item.id. Um conjunto sem item correspondente, sem item.name ou sem itemOffer.price.value é descartado e reportado em moreInfo.
Quando onlyAddProducts é false, categorias e produtos vinculados ao PDV que não aparecem no payload podem ser removidos do catálogo. A remoção afeta apenas registros com pdv_external_id. Conteúdos criados manualmente pelo lojista no painel não são removidos.Imagens, cortes e vínculos de categoria associados aos registros removidos também são excluídos.Se qualquer objeto do payload estiver malformado, nenhuma remoção será executada nessa sincronização. O mesmo ocorre quando o payload não contém nenhuma categoria válida. Consulte moreInfo para identificar o problema.

​
Exemplo de payload

Para ocultar temporariamente um produto sem removê-lo, defina o status da oferta como UNAVAILABLE. Em MERCHANT, use itemOffers[].status. Em ITEM_OFFER, use updatedObjects[].status.

​
Processamento e resultado

O processamento ocorre de forma assíncrona. Depois de receber o payload, a API enfileira a sincronização e responde com 204 No Content.
O status HTTP 204 confirma apenas que a requisição foi aceita e enfileirada. Ele não confirma que os dados foram aplicados.
Consulte GET /v1/merchantStatus até status deixar de ser PROCESSING. moreInfo informa quantos objetos foram processados e descreve dados descartados ou problemas encontrados.
FAIL também pode representar sucesso parcial. Por exemplo, se 99 de 100 itens forem atualizados, o resultado será FAIL, mas as 99 alterações já terão sido aplicadas.Não reenvie o mesmo payload automaticamente em loop. Leia moreInfo, identifique o que foi aplicado ou descartado e corrija a próxima sincronização.

​
Campos da resposta

​
204: Sem conteúdo

A requisição foi recebida e enfileirada. A resposta não contém corpo. Consulte GET /v1/merchantStatus para saber se o processamento terminou com SUCCESS ou FAIL.

​
400: Requisição inválida

Um campo obrigatório está ausente ou com valor não aceito (por exemplo, entityType fora do enum, ou merchantStatus ausente com entityType: MERCHANT). O corpo informa o campo: { "title": "The merchant status field is required when entity type is MERCHANT.", "status": 400 }.

​
401: Não autorizado

Token ausente ou inválido. Reautentique-se e tente novamente. Veja Erros.