VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Identidade e configurações da loja

Como o seller define a aparência da sua loja, edita o próprio cadastro e envia imagens, e o que cada rota devolve.

Numa loja marketplace vários sellers (lojistas) vendem sob o mesmo domínio. Cada seller tem uma identidade própria: logo, banner, cores, redes sociais, uma vitrine própria (o microsite) e um cadastro com dados fiscais, endereço e conta para repasse. Esta seção reúne as rotas do painel do seller que leem e gravam essa identidade, mais o upload de imagens e um relatório de personalização.

Pontos-chave
  • Há duas noções de "configuração": as cores do painel (valem para a loja inteira, o seller só lê) e a vitrine do seller (storefront-config, o seller escreve).
  • PUT /vendor/storefront-config substitui o documento inteiro: campo omitido volta ao vazio e is_published volta a false. Envie sempre tudo.
  • GET/PUT /vendor/settings é o mesmo cadastro do seller (igual a /vendor/profile). Comissão, status, modelo de pagamento e aprovação de produtos não mudam por aqui: o servidor ignora esses campos.
  • Para trocar logo ou banner, envie a imagem em POST /vendor/media, pegue a url da resposta e grave essa URL no campo logo_url/banner_url.
  • Ler a configuração exige só o papel de seller. Gravar exige um privilégio de configuração quando o usuário é de uma equipe (vendor_settings e afins).

Como funciona

  1. Envie a imagem
    POST /api/v1/vendor/media com o arquivo, owner_type=vendor e o id do seu seller. A resposta traz a url pública.
  2. Monte a vitrine
    PUT /api/v1/vendor/storefront-config com logo, banner, cores, descrição, SEO, redes sociais e is_published.
  3. Ajuste o cadastro
    PUT /api/v1/vendor/settings com os dados da empresa, endereço, contato, conta de repasse e preferências de e-mail.
  4. Defina o prazo
    PUT /api/v1/vendor/settings/handling-time informa em quantos dias o seller despacha.

Conceitos-chave

Seller, administrador e equipe

O seller é a empresa que vende. O administrador da loja é quem opera o marketplace. Uma equipe é o conjunto de usuários que o seller convida; cada um tem privilégios próprios. O seller dono (e quem não tem grupo de restrição) pode tudo.

Cores do painel

GET /vendor/branding devolve duas cores em hexadecimal (#0044ff) definidas pelo administrador da loja: a do painel de administração e a do painel do seller. O seller não as altera.

Dinheiro, datas e ids

Ids são UUIDs em texto. Datas são RFC 3339. Valores em dinheiro, onde existirem, são inteiros em centavos.

Imagens e URLs

Os campos de imagem (logo_url, banner_url) guardam a URL e não o arquivo. O servidor não valida se a URL abre nem se é imagem.

Endpoints

MétodoCaminhoPara que servePágina
GET/api/v1/vendor/brandingCores do painelCores do painel
GET/api/v1/vendor/storefront-configLer a vitrine do sellerVitrine do seller
PUT/api/v1/vendor/storefront-configGravar a vitrine do sellerVitrine do seller
GET/api/v1/vendor/settingsLer o cadastro do sellerCadastro e configurações
PUT/api/v1/vendor/settingsAlterar o cadastro do sellerCadastro e configurações
PUT/api/v1/vendor/settings/handling-timePrazo de postagem em diasCadastro e configurações
POST/api/v1/vendor/mediaEnviar uma imagem, PDF ou vídeoUpload de mídia
GET/api/v1/vendor/personalization/reportAderência do catálogo à demandaRelatório de personalização

Erros comuns

  • Mandar só o campo que mudou no PUT /storefront-config. Os demais viram vazio e a vitrine é despublicada. Leia, altere e devolva o objeto inteiro.
  • Esperar que PUT /settings mude comissão ou status. Esses campos são descartados em silêncio; só o administrador os altera.
  • Gravar um slug em uso. Responde 409 slug_taken. O slug de um seller excluído também não é reaproveitado.
  • Enviar o arquivo sem owner_id. O upload exige owner_type e owner_id; sem eles responde 400.
  • Usar um token de administrador. Todas as rotas são do seller e respondem 403 insufficient permissions para outros papéis.

Próximos passos

Upload de mídia
Envie logo, banner e fotos.
Vitrine do seller
Microsite próprio do seller.
Cadastro e configurações
Dados da empresa e prazo de postagem.
Relatório de personalização
Demanda dos compradores x seu catálogo.
Anterior
Traduções em inglês
Próxima
Cores do painel
Nesta página
  • Como funciona
  • Conceitos-chave
  • Seller, administrador e equipe
  • Cores do painel
  • Dinheiro, datas e ids
  • Imagens e URLs
  • Endpoints
  • Erros comuns
  • Próximos passos