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

Produtos mestres e ofertas

Entende o produto mestre do catálogo e lista as ofertas dos sellers para ele, com preço, estoque e avaliação, para a aba "outros vendedores".

Um produto mestre é uma ficha de catálogo (nome, descrição, imagens, características) que o administrador mantém uma vez. Cada seller (lojista) liga a sua própria versão do produto a essa ficha e define o próprio preço e estoque: essa versão é uma oferta. A vitrine vende as ofertas, nunca a ficha.

Por isso, das três rotas desta página só uma devolve dados: a das ofertas. Use-a na página de um produto que pertence a um mestre, para mostrar "outros vendedores" com a comparação de preço.

Módulo e configuração

As três rotas exigem o módulo master-products ligado (senão 403 {"error":"module_disabled","module":"master-products"}) e passam pelo portão de navegação da loja (401 shopping_requires_login para visitante quando a loja só permite navegar logado). A rota de ofertas ainda exige a opção "produtos mestres" ligada nas configurações da loja; desligada, responde 404.

GET/api/v1/storefront/master-productsPública

Lista de produtos mestres (sempre vazia)

A ficha mestre não é uma superfície de compra, então esta rota sempre devolve uma lista vazia, mesmo com o módulo ligado. Os produtos vendáveis aparecem nas listagens normais de produtos. Os parâmetros page e per_page são apenas devolvidos na resposta.

Parâmetros de consulta

pageintegerpadrão: 1
Devolvido como veio, sem validação.
per_pageintegerpadrão: 20
Devolvido como veio, sem validação.

Exemplo de requisição (lista)

bash
curl "$BASE_URL/api/v1/storefront/master-products"

Resposta (lista)

200Lista vazia
json
{ "products": [], "total": 0, "page": 1, "per_page": 20, "total_pages": 0 }
GET/api/v1/storefront/master-products/{id}Pública

Detalhe de produto mestre (sempre 404)

Pelo mesmo motivo, o detalhe de uma ficha mestre sempre responde 404, para qualquer id. Não construa uma página de detalhe de mestre na vitrine: leve o cliente à página da oferta (use product_slug das ofertas).

Parâmetros de caminho

iduuidobrigatório
Id do produto mestre.

Resposta (detalhe)

404Sempre
json
{ "error": "master product not found" }
GET/api/v1/storefront/master-products/{id}/offersPública

Ofertas dos sellers para um produto mestre

Devolve uma oferta por seller: a melhor oferta ativa de cada um. Entram só ofertas de produtos ativos, de sellers ativos e em estoque (ou sem controle de estoque). Ficam de fora sellers invisíveis para o cliente e, conforme a configuração da loja, sellers que não entregam na região do comprador. A região vem da query, depois dos cabeçalhos X-Buyer-* e, por último, do endereço padrão do cliente logado.

Cabeçalhos

X-Buyer-Statestring
UF do comprador. Só é lido quando nenhum parâmetro de região vem na query.
X-Buyer-Citystring
Cidade do comprador.
X-Buyer-Districtstring
Bairro do comprador.
X-Buyer-CEPstring
CEP do comprador. Só o CEP basta: a plataforma descobre cidade e bairro.

Parâmetros de caminho

iduuidobrigatório
Id do produto mestre.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora do intervalo volta a 20.
sortstring
Aceito e ignorado. As ofertas vêm sempre do menor preço para o maior e, no empate, da melhor avaliação.
deliver_to_statestring
UF do comprador para o filtro de entrega regional. Alias: buyer_state.
deliver_to_citystring
Cidade do comprador. Alias: buyer_city.
deliver_to_districtstring
Bairro do comprador. Alias: buyer_district.
deliver_to_cepstring
CEP do comprador. Aliases: buyer_cep, cep.

Exemplo de requisição (ofertas)

bash
curl "$BASE_URL/api/v1/storefront/master-products/6b5806fe-4370-4f12-bc95-a7dbba04918b/offers" \
  -H "X-Buyer-CEP: 01310-100"

Resposta (ofertas)

200Ofertas retornadas
json
{
  "offers": [
    {
      "product_id": "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
      "product_slug": "cafeteira-premium-branca-01426-1426",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Exemplo",
      "vendor_slug": "loja-exemplo",
      "vendor_logo_url": "/uploads/exemplo/logo.png",
      "price": 80990,
      "quantity": 2,
      "track_inventory": true,
      "status": "A",
      "rating_avg": 3.8,
      "rating_count": 0,
      "free_shipping": true,
      "sku": "SD-001426",
      "image_url": "/uploads/exemplo/cafeteira.png",
      "created_at": "2026-05-25T12:05:41Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

offersarray
Uma oferta por seller.
offers[].product_iduuid
Id do produto do seller (a oferta). É ele que vai ao carrinho.
offers[].product_slugstring
Slug do produto da oferta, para montar o link da página dele.
offers[].vendor_iduuid
Id do seller.
offers[].vendor_namestring
Nome do seller.
offers[].vendor_slugstring
Slug da página do seller.
offers[].vendor_logo_urlstring
Logo do seller, pode ser vazio.
offers[].priceinteger
Preço em centavos. 0 com price_redacted: true para visitante em loja que esconde preço.
offers[].list_priceinteger
Preço "de", em centavos, quando existe. Ausente caso contrário.
offers[].price_redactedboolean
true quando price e list_price foram zerados para o visitante. Ausente caso contrário.
offers[].quantityinteger
Estoque do seller.
offers[].track_inventoryboolean
Se o seller controla estoque. Mostre "em estoque" quando !track_inventory || quantity > 0.
offers[].statusstring
Status do produto (A, ativo).
offers[].rating_avgnumber
Média de avaliações do seller.
offers[].rating_countinteger
Quantidade de avaliações.
offers[].free_shippingboolean
Se o produto tem frete grátis.
offers[].skustring
SKU do seller. Ausente quando não há.
offers[].image_urlstring
Primeira imagem do produto, ou vazio.
offers[].created_atstring
Criação da oferta (RFC 3339).
totalinteger
Total de sellers com oferta.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401A loja exige login para navegar e a chamada é anônima.{"error":"shopping_requires_login","message":"this storefront requires login to browse"}
403Módulo master-products desligado.{"error":"module_disabled","module":"master-products"}
404Opção de produtos mestres desligada nas configurações da loja.{"error":"feature not enabled","detail":"enable master_products via admin settings"}
404Produto mestre inexistente, inativo ou com id que não é UUID.{"error":"master product not found"}
500Falha interna.{"error":"failed to get offers","detail":"..."}
Resposta que depende da região

Quando a loja filtra por região e o comprador é identificado (query, cabeçalhos X-Buyer-* ou endereço padrão do cliente logado), a resposta passa a ser Cache-Control: private, no-store, com Vary nesses cabeçalhos. Não compartilhe essa resposta entre compradores.

Veja também

  • Kits
  • Modo catálogo
  • Kits e conjuntos: visão geral
Anterior
Kits
Próxima
Modo catálogo
Nesta página
  • Exemplo de requisição (lista)
  • Resposta (lista)
  • Resposta (detalhe)
  • Exemplo de requisição (ofertas)
  • Resposta (ofertas)
  • Erros
  • Veja também