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 funcionam normalmente com token de integração). Esse é parte do motivo de a API da Loja seguir em BETA.
Consultar
Retorna tudo: dados da loja, da company, textos descritivos e URLs públicas do logo/background.
Textos descritivos
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:
{
"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
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
POST/api/stores/page/background
DELETE/api/stores/page/background
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.