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

# Consulte o merchant

> Consulte a loja e seu catálogo.

Este endpoint retorna o status, as categorias e os produtos da loja. O campo `TTL` informa o tempo de cache dos dados.

## Campos da resposta

### 200: Sucesso

<ResponseField name="lastUpdate" type="string">
  Timestamp ISO 8601 da última atualização dos dados do merchant na plataforma Onbeef (por exemplo, `"2025-08-22T16:13:37.000000Z"`).
</ResponseField>

<ResponseField name="TTL" type="integer">
  Time-to-live do cache em segundos. Após esse tempo, a resposta em cache é invalidada e uma nova leitura será feita.
</ResponseField>

<ResponseField name="id" type="string">
  UUID único do merchant na plataforma Onbeef (por exemplo, `"e9e7e242-fbee-4e43-9c3f-251c1e6588fb"`).
</ResponseField>

<ResponseField name="status" type="string">
  Disponibilidade atual do merchant. Um dos valores `"AVAILABLE"` ou `"UNAVAILABLE"`.
</ResponseField>

<ResponseField name="categories" type="array">
  Lista de objetos de categoria associados a este merchant.

  <Expandable title="Campos do objeto category">
    <ResponseField name="id" type="string">
      UUID único da categoria.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome de exibição da categoria (por exemplo, `"Bovinos"`, `"Aves"`, `"Kits"`).
    </ResponseField>

    <ResponseField name="index" type="integer">
      Ordem de exibição da categoria no catálogo, começando em `0`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Disponibilidade da categoria: `"AVAILABLE"` ou `"UNAVAILABLE"`.
    </ResponseField>

    <ResponseField name="externalCode" type="string">
      Identificador externo desta categoria no seu PDV (por exemplo, `"72BD8D"`).
    </ResponseField>

    <ResponseField name="productsId" type="array of strings">
      Array de UUIDs de produtos pertencentes a esta categoria.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="products" type="array">
  Lista de objetos de produto no catálogo deste merchant.

  <Expandable title="Campos do objeto product">
    <ResponseField name="id" type="string">
      UUID único do produto.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome de exibição do produto.
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição longa do produto exibida aos clientes.
    </ResponseField>

    <ResponseField name="price" type="number">
      Preço unitário do produto.
    </ResponseField>

    <ResponseField name="unit" type="string">
      Unidade de medida: `"KG"` (venda por peso) ou `"UN"` (venda por unidade).
    </ResponseField>

    <ResponseField name="status" type="string">
      Disponibilidade do produto: `"AVAILABLE"` ou `"UNAVAILABLE"`.
    </ResponseField>

    <ResponseField name="stock" type="number">
      Quantidade atual em estoque deste produto.
    </ResponseField>

    <ResponseField name="externalCode" type="string">
      Identificador externo deste produto no seu PDV.
    </ResponseField>

    <ResponseField name="ean" type="string">
      Código de barras EAN do produto, se aplicável.
    </ResponseField>

    <ResponseField name="sku" type="string">
      SKU do produto, se aplicável.
    </ResponseField>

    <ResponseField name="media" type="array of strings">
      Array de URLs de imagens deste produto.
    </ResponseField>

    <ResponseField name="cuts" type="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 corte
      * `name` (string): Nome do corte (por exemplo, `"Sem osso"`)
      * `spice` (object | null): Tempero do corte, como `{ "id": "...", "name": "Natural" }`, ou `null` quando não há tempero
    </ResponseField>
  </Expandable>
</ResponseField>

### 401: Não autorizado

Token ausente ou inválido. Reautentique-se e tente novamente. Veja [Erros](/api-reference/errors).

### 503: Serviço indisponível

Serviço temporariamente indisponível ou token inválido. Veja [Erros](/api-reference/errors).

## Exemplo

### Requisição

```bash theme={null}
curl https://api.dev.connect.onbeefapp.com.br/v1/merchant \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

### Resposta (truncada)

```json theme={null}
{
  "lastUpdate": "2025-08-22T16:13:37.000000Z",
  "TTL": 600,
  "id": "e9e7e242-fbee-4e43-9c3f-251c1e6588fb",
  "status": "AVAILABLE",
  "categories": [
    {
      "id": "bdfbb2f3-af2a-4ad7-8714-f3c75531e78f",
      "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",
      "name": "Churrasco",
      "index": 1,
      "status": "AVAILABLE",
      "externalCode": "4C951B",
      "productsId": [ "..." ]
    }
  ],
  "products": [
    {
      "id": "1db3abc1-d295-4873-be31-ef64050a31f7",
      "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 }
      ]
    }
  ]
}
```

<Tip>
  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.
</Tip>