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

Sellers e microsites

Visão geral do diretório público de sellers, da página de cada um e do microsite.

Em uma loja marketplace, vários sellers (lojistas) vendem na mesma vitrine. Cada seller tem uma página pública: nome, logotipo, cidade, quantos produtos vende, reputação e, se quiser, um microsite próprio com banners, páginas e blog. Esta seção documenta as rotas públicas que o front-end usa para listar sellers, abrir a página de um deles e mostrar selos como "de férias" ou "vendedor bem avaliado".

Pontos-chave
  • Todas as rotas são públicas: sem token. Em lojas que exigem login para navegar, as de diretório respondem 401 shopping_requires_login a quem não está logado.
  • O seller pode ser identificado pelo UUID ou pelo slug (o nome na URL, como moda-carioca) na maioria das rotas. As exceções estão marcadas.
  • Só aparecem sellers ativos. Seller oculto, suspenso, apagado, restrito a outro grupo de clientes ou que não entrega para o cliente responde como se não existisse (404).
  • Dinheiro em centavos inteiros (min_order_amount: 15000 = R$ 150,00). Datas em RFC 3339.
  • A rota delivers-to hoje sempre responde available: true (veja Situação do seller).

Como funciona

  1. Listar os sellers

    Listar sellers devolve uma página do diretório, com busca por nome e filtro por cidade e estado.

  2. Abrir a página de um seller

    Consultar seller traz o cabeçalho da página. Categorias do seller alimenta o menu lateral.

  3. Mostrar selos

    Situação do seller dá a reputação e o aviso de férias.

  4. Microsite próprio

    Seller com "Minha Loja" publicada tem um microsite, que também pode ser servido num domínio próprio.

Conceitos-chave

Seller, lojista e loja

Seller (lojista) é quem vende dentro da loja marketplace. A loja é a plataforma que hospeda todos. Numa loja com um único vendedor, o diretório tem poucos ou nenhum seller.

Slug

O slug é o nome do seller para URLs, em minúsculas e com hifens. É único na loja. Use o slug nas páginas públicas e o UUID quando precisar de uma chave que não muda.

Microsite e "Minha Loja"

No painel, o seller edita "Minha Loja": logotipo, banner, descrição, cores, redes sociais, CSS e SEO. Isso se mescla à ficha do seller na página dele. Enquanto o seller despublica a Minha Loja, a página dele (/vendors/{id}) e o microsite respondem 404, mas o seller continua aparecendo na listagem.

Reputação

A reputação é uma nota de 0 a 100 calculada sobre os últimos 60 dias (cancelamentos, atrasos no envio, devoluções, avaliações e tempo de resposta). Com menos de 10 pedidos no período o seller fica "neutro" (sem termômetro).

Endpoints

MétodoRotaO que fazPágina
GET/api/v1/storefront/vendorsLista os sellersListar sellers
GET/api/v1/storefront/vendors/{id}Consulta um seller por UUID ou slugConsultar seller
GET/api/v1/storefront/vendors/by-slug/{slug}Consulta um seller só por slugConsultar seller
GET/api/v1/storefront/vendors/{id}/categoriesCategorias com produtos do sellerCategorias do seller
GET/api/v1/storefront/vendors/{id}/delivers-toO seller entrega neste destino?Situação do seller
GET/api/v1/storefront/vendors/{id}/reputationReputaçãoSituação do seller
GET/api/v1/storefront/vendors/{vendorId}/vacationAviso de fériasSituação do seller
GET/api/v1/storefront/vendors/{slug}/micrositeMicrosite do sellerMicrosite
GET/api/v1/storefront/vendor-microsite/domain/{domain}Microsite por domínio próprioMicrosite
GET/api/v1/storefront/vendor-terms/activeTermos de adesão vigentesTermos de adesão

Erros comuns

  1. Usar o slug em vacation. Essa rota só aceita UUID; com slug responde 500.
  2. Abrir na lista e falhar no detalhe. Um seller com a Minha Loja despublicada está na lista, mas o detalhe dele é 404. Trate o 404 ao navegar.
  3. Confiar em delivers-to. A resposta é sempre true, seja qual for o destino. Para saber se há frete, use o cálculo de frete.
  4. Mostrar a nota de reputação de um seller novo. Com cold_start: true ou band: neutral não exiba número nem termômetro.
  5. Pedir per_page acima de 100. O valor volta ao padrão de 20, não é limitado a 100.
  6. Exibir content dos termos sem sanitizar. O texto vem em HTML.

Próximos passos

Listar sellers
O diretório com busca e filtros.
Consultar seller
A ficha pública de um seller.
Microsite
A loja própria do seller.
Anterior
Personalização
Próxima
Listar sellers
Nesta página
  • Como funciona
  • Conceitos-chave
  • Seller, lojista e loja
  • Slug
  • Microsite e "Minha Loja"
  • Reputação
  • Endpoints
  • Erros comuns
  • Próximos passos