Consulte o merchant
curl --request GET \
--url https://api.dev.connect.onbeefapp.com.br/v1/merchant \
--header 'Authorization: Bearer <token>'{
"lastUpdate": "<string>",
"TTL": 123,
"id": "<string>",
"status": "<string>",
"categories": [
{
"id": "<string>",
"pdv_external_id": {},
"name": "<string>",
"index": 123,
"status": "<string>",
"externalCode": "<string>",
"productsId": {}
}
],
"products": [
{
"id": "<string>",
"pdv_external_id": {},
"name": "<string>",
"description": "<string>",
"price": 123,
"unit": "<string>",
"status": "<string>",
"stock": 123,
"externalCode": "<string>",
"ean": "<string>",
"sku": "<string>",
"media": {},
"cuts": [
{}
]
}
]
}Merchant
Consulte o merchant
Consulte a loja e seu catálogo. O pdv_external_id devolvido por produto e categoria é o código que a sincronização usa para localizá-los.
GET
/
v1
/
merchant
Consulte o merchant
curl --request GET \
--url https://api.dev.connect.onbeefapp.com.br/v1/merchant \
--header 'Authorization: Bearer <token>'{
"lastUpdate": "<string>",
"TTL": 123,
"id": "<string>",
"status": "<string>",
"categories": [
{
"id": "<string>",
"pdv_external_id": {},
"name": "<string>",
"index": 123,
"status": "<string>",
"externalCode": "<string>",
"productsId": {}
}
],
"products": [
{
"id": "<string>",
"pdv_external_id": {},
"name": "<string>",
"description": "<string>",
"price": 123,
"unit": "<string>",
"status": "<string>",
"stock": 123,
"externalCode": "<string>",
"ean": "<string>",
"sku": "<string>",
"media": {},
"cuts": [
{}
]
}
]
}Este endpoint retorna o status, as categorias e os produtos da loja. O campo
TTL informa o tempo de cache dos dados.
O
id de produtos e categorias é o UUID interno da Onbeef e não é aceito como identificador no PUT /v1/merchantUpdate. O identificador da integração é o pdv_external_id: é ele que deve corresponder ao itemId (ITEM_OFFER), ao id do item (ITEM) e aos ids de categoria e item no MERCHANT.Campos da resposta
200: Sucesso
string
Timestamp ISO 8601 da última atualização dos dados do merchant na plataforma Onbeef (por exemplo,
"2025-08-22T16:13:37.000000Z").integer
Time-to-live do cache em segundos. Após esse tempo, a resposta em cache é invalidada e uma nova leitura será feita.
string
UUID único do merchant na plataforma Onbeef (por exemplo,
"e9e7e242-fbee-4e43-9c3f-251c1e6588fb").string
Disponibilidade atual do merchant. Um dos valores
"AVAILABLE" ou "UNAVAILABLE".array
Lista de objetos de categoria associados a este merchant.
Show Campos do objeto category
Show Campos do objeto category
string
UUID único da categoria na Onbeef.
string | null
Código de integração com PDV da categoria. É o identificador que a sincronização usa para reconhecer a categoria (corresponde a
categories[].id no merchantUpdate). null quando a categoria foi criada manualmente no painel e ainda não foi vinculada.string
Nome de exibição da categoria (por exemplo,
"Bovinos", "Aves", "Kits").integer
Ordem de exibição da categoria no catálogo, começando em
0.string
Disponibilidade da categoria:
"AVAILABLE" ou "UNAVAILABLE".string
Código interno gerado pela Onbeef na criação da categoria (por exemplo,
"72BD8D"). Apenas informativo: não é um identificador do PDV e não é usado pela sincronização.array of strings
Array de UUIDs de produtos pertencentes a esta categoria.
array
Lista de objetos de produto no catálogo deste merchant.
Show Campos do objeto product
Show Campos do objeto product
string
UUID único do produto na Onbeef.
string | null
Código de integração com PDV do produto. É este valor que o
itemId (ITEM_OFFER) e o id do item (ITEM e MERCHANT) devem referenciar no merchantUpdate. null quando o produto foi criado manualmente no painel e ainda não foi vinculado a um código do PDV.string
Nome de exibição do produto.
string
Descrição longa do produto exibida aos clientes.
number
Preço unitário do produto.
string
Unidade de medida:
"KG" (venda por peso) ou "UN" (venda por unidade).string
Disponibilidade do produto:
"AVAILABLE" ou "UNAVAILABLE".number
Quantidade atual em estoque deste produto.
string
Código de balança do produto, definido pelo lojista no painel ou pelo campo
externalCode da sincronização. Usado pelos recursos de balança do painel, como a atualização de preço por arquivo. Não é usado para localizar produtos na integração: para isso, use o pdv_external_id.string
Código de barras EAN do produto, se aplicável. Gravado pela sincronização e devolvido apenas para consulta.
string
SKU do produto, se aplicável. Apenas para consulta: não há caminho de escrita via API.
array of strings
Array de URLs de imagens deste produto.
array
Array de opções de corte disponíveis para produtos de açougue. Presente apenas quando o produto tem cortes cadastrados (omitido quando não há). Cada objeto de corte contém:
id(string): UUID do cortename(string): Nome do corte (por exemplo,"Sem osso")spice(object | null): Tempero do corte, como{ "id": "...", "name": "Natural" }, ounullquando não há tempero
401: Não autorizado
Token ausente ou inválido. Reautentique-se e tente novamente. Veja Erros.503: Serviço indisponível
Serviço temporariamente indisponível ou token inválido. Veja Erros.Exemplo
Requisição
curl https://api.dev.connect.onbeefapp.com.br/v1/merchant \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
Resposta (truncada)
{
"lastUpdate": "2025-08-22T16:13:37.000000Z",
"TTL": 600,
"id": "e9e7e242-fbee-4e43-9c3f-251c1e6588fb",
"status": "AVAILABLE",
"categories": [
{
"id": "bdfbb2f3-af2a-4ad7-8714-f3c75531e78f",
"pdv_external_id": "15",
"name": "Kits",
"index": 0,
"status": "AVAILABLE",
"externalCode": "72BD8D",
"productsId": [
"1db3abc1-d295-4873-be31-ef64050a31f7",
"e74dd75f-2a7c-416a-997d-02bab6adc10b"
]
},
{
"id": "82532a6d-c6d4-44c7-ab32-a8eca9bb29ca",
"pdv_external_id": null,
"name": "Churrasco",
"index": 1,
"status": "AVAILABLE",
"externalCode": "4C951B",
"productsId": [ "..." ]
}
],
"products": [
{
"id": "1db3abc1-d295-4873-be31-ef64050a31f7",
"pdv_external_id": "1001",
"name": "Picanha Angus Premium",
"description": "Picanha de raça Angus, maturada 21 dias.",
"price": 89.90,
"unit": "KG",
"status": "AVAILABLE",
"stock": 15.5,
"externalCode": "PIC001",
"ean": "7891234560001",
"sku": "PIC-ANG-001",
"media": [
"https://cdn.onbeefapp.com.br/products/picanha-angus.jpg"
],
"cuts": [
{ "id": "cut-001", "name": "Sem osso", "spice": { "id": "spice-001", "name": "Natural" } },
{ "id": "cut-002", "name": "Com gordura", "spice": null }
]
}
]
}
Use o valor de
TTL para decidir com que agressividade cachear esta resposta do seu lado. Se TTL for 600, o cache da Onbeef pode servir dados obsoletos por até 10 minutos: leve isso em conta ao esperar que mudanças rápidas de catálogo sejam refletidas.