# Guia da Loja

Gerencie a página pública da sua loja, identidade visual e avaliações.

> **🚧 BETA**: esta API ainda está em revisão. Os endpoints listados aqui funcionam, mas **schemas, nomes de campos e comportamentos podem mudar** antes da versão estável. Recomendamos integrar com flexibilidade: trate respostas como dicionários, não dependa rigidamente de campos opcionais.

---

## Página da Loja

A página pública é o que o comprador vê ao acessar a sua loja no marketplace. Tem três pedaços que você gerencia por API: **textos descritivos**, **logo** e **imagem de fundo**.

> **⚠️ Por enquanto, só pelo portal.** Os endpoints de Página da Loja exigem escopos que hoje ainda não são atribuíveis a tokens de integração — chamadas com token `sk_live_*` retornam **403**. Essa parte da API, por ora, só funciona pelo portal do seller (as rotas de [Avaliações](#avaliações) funcionam normalmente com token de integração). Esse é parte do motivo de a API da Loja seguir em BETA.

### Consultar

<a class="api-route" href="/reference/loja#tag/página-da-loja/GET/api/stores/page"><span class="api-method api-method-get">GET</span><span class="api-path">/api/stores/page</span></a>

Retorna tudo: dados da loja, da `company`, textos descritivos e URLs públicas do logo/background.

### Textos descritivos

<a class="api-route" href="/reference/loja#tag/página-da-loja/PUT/api/stores/page"><span class="api-method api-method-put">PUT</span><span class="api-path">/api/stores/page</span></a>

Quatro campos opcionais. Envie só os que quer atualizar; os omitidos não mudam. Pra **limpar** um campo, mande `null` — mas repare na leitura de volta: os campos de texto (`short_description`, `description`, `full_description`) voltam como string vazia (`""`); só `foundation_date` retorna `null` de verdade.

| Campo | Limite | Para que serve |
|-------|--------|----------------|
| `short_description` | 255 chars | Subtítulo curto, exibido logo abaixo do nome da loja. |
| `description` | 500 chars | Resumo na seção "Sobre" da página. |
| `full_description` | sem limite | Texto longo da aba "Sobre" expandida. Suporta múltiplos parágrafos. |
| `foundation_date` | data ISO | Data de fundação, vira "Loja desde 2015" no cabeçalho. |

Exemplo:

```json
{
  "short_description": "Tecnologia no atacado",
  "description": "Loja referência em atacado de tecnologia desde 2015.",
  "foundation_date": "2015-05-20"
}
```

### Logo e imagem de fundo

Ambos são enviados via `multipart/form-data` no campo `image` direto nos endpoints da própria loja. Aqui você não usa o fluxo de Mídia (`/api/media/upload`), e é de propósito: logo e fundo são peças únicas da loja — não uma galeria — então não faz sentido subir, guardar um `id` e vincular depois. Você manda o arquivo direto no endpoint e ele já substitui o anterior. Especificação:

| Item | Valor |
|------|-------|
| Campo do upload | `image` |
| Tipos aceitos | `jpeg`, `png`, `jpg`, `gif`, `webp` |
| Tamanho máximo | 5 MB |
| Comportamento | Substitui o arquivo anterior (sem versionamento). A URL pública é a mesma. |

Após o upload, a URL final aparece no `GET /api/stores/page`. Pode levar alguns segundos pra CDN propagar.

#### Logo

<a class="api-route" href="/reference/loja#tag/página-da-loja/POST/api/stores/page/logo"><span class="api-method api-method-post">POST</span><span class="api-path">/api/stores/page/logo</span></a>

<a class="api-route" href="/reference/loja#tag/página-da-loja/DELETE/api/stores/page/logo"><span class="api-method api-method-delete">DELETE</span><span class="api-path">/api/stores/page/logo</span></a>

Exibido no cabeçalho da página da loja e nos cards de listagem do marketplace. Recomendado: imagem quadrada (1:1), fundo transparente (PNG/WebP), mínimo 256×256.

#### Background

<a class="api-route" href="/reference/loja#tag/página-da-loja/POST/api/stores/page/background"><span class="api-method api-method-post">POST</span><span class="api-path">/api/stores/page/background</span></a>

<a class="api-route" href="/reference/loja#tag/página-da-loja/DELETE/api/stores/page/background"><span class="api-method api-method-delete">DELETE</span><span class="api-path">/api/stores/page/background</span></a>

Banner horizontal no topo da página da loja. Recomendado: largura mínima 1920px, proporção ~3:1 (ex.: 1920×640). Sem texto importante na imagem, porque partes podem ser cortadas em telas estreitas.

---

## Avaliações

Nota da loja calculada automaticamente a partir das avaliações dos pedidos entregues.

### Resumo

<a class="api-route" href="/reference/loja#tag/avaliação/GET/api/stores/rating"><span class="api-method api-method-get">GET</span><span class="api-path">/api/stores/rating</span></a>

### Histórico

<a class="api-route" href="/reference/loja#tag/avaliação/GET/api/stores/rating/history"><span class="api-method api-method-get">GET</span><span class="api-path">/api/stores/rating/history</span></a>