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

Catálogo mestre

Lista e lê os produtos mestre ativos que o seller pode clonar.

Listar mestres

Lista os produtos mestre ativos, do mais novo para o mais antigo, com filtros por categoria e texto.

GET/api/v1/vendor/master-catalogSeller

Listar mestres ativos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de consulta

category_iduuid
Só mestres desta categoria principal.
searchstring
Texto procurado no nome, SKU ou marca (sem diferença de maiúsculas).
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página. Padrão 20, máximo 100 (valor maior é reduzido a 100).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/master-catalog?search=cafeteira&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mestres
json
{
  "products": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "sku": "sd-001426",
      "name": "Cafeteira Moderno Branco 01426",
      "description": "Cafeteira com acabamento premium.",
      "short_description": "Cafeteira Moderno Branco, envio rápido.",
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "brand": "Marca Exemplo",
      "base_price": 80990,
      "main_image_url": "https://cdn.example.com/master/cafeteira.jpg",
      "features": {
        "Modelo": "220v"
      },
      "specifications": {},
      "status": "A",
      "offer_count": 1,
      "barcode": "7891234567895",
      "quantity": 0,
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 0,
      "images": [],
      "created_at": "2026-07-23T14:30:14.156287Z",
      "updated_at": "2026-10-11T21:09:09.826034Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

productsarray
Mestres da página (campos abaixo).
totalinteger
Mestres que atendem ao filtro.
pageinteger
Página.
per_pageinteger
Itens por página aplicado.
total_pagesinteger
Total de páginas.
iduuid
Id do produto mestre.
skustring
Código do mestre. Ausente se não houver.
namestring
Nome.
descriptionstring
Descrição completa.
short_descriptionstring
Descrição curta.
category_iduuid
Categoria principal. Ausente se não houver.
category_namestring
Nome da categoria. Só na leitura de um mestre; ausente na lista.
brandstring
Marca (texto livre).
base_priceinteger
Preço de venda sugerido, em centavos.
main_image_urlstring
Imagem principal.
featuresobject
Características livres (nome para valor).
specificationsobject
Especificações livres (nome para valor).
statusstring
Situação do mestre: A ativo. O seller só enxerga mestres ativos.
offer_countinteger
Quantos produtos ativos (de qualquer seller) já vendem este mestre.
barcodestring
EAN/GTIN. Ausente se não houver.
quantityinteger
Estoque do próprio mestre.
min_quantityinteger
Quantidade mínima por pedido (0 sem regra).
max_quantityinteger
Quantidade máxima por pedido (0 sem regra).
quantity_stepinteger
Múltiplo de compra (0 sem regra).
imagesarray
Galeria: id, master_product_id, image_url, alt_text, position, is_primary. Na lista pode vir vazia.
additional_category_idsarray
Outras categorias (uuids). Ausente se não houver.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
404O recurso de produtos mestre está desligado nesta loja.{"error":"feature not enabled","detail":"enable master_products via admin settings"}
500category_id que não é UUID, ou falha ao consultar.{"error":"failed to list master catalog","detail":"..."}

Veja também

  • Clonar mestres

Ler um mestre

Devolve um produto mestre pelo id, com galeria e traduções. Mestres excluídos respondem 404.

GET/api/v1/vendor/master-catalog/{id}Seller

Ler um mestre

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do mestre.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/master-catalog/$MASTER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mestre
json
{
  "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
  "sku": "sd-001426",
  "name": "Cafeteira Moderno Branco 01426",
  "description": "Cafeteira com acabamento premium.",
  "short_description": "Cafeteira Moderno Branco, envio rápido.",
  "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
  "brand": "Marca Exemplo",
  "base_price": 80990,
  "main_image_url": "https://cdn.example.com/master/cafeteira.jpg",
  "features": {
    "Modelo": "220v"
  },
  "specifications": {},
  "status": "A",
  "offer_count": 1,
  "barcode": "7891234567895",
  "quantity": 0,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 0,
  "images": [
    {
      "id": "1f6b2e0a-9c64-4b0e-a1b4-5d6e7f8a9b10",
      "master_product_id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "image_url": "https://cdn.example.com/master/cafeteira.jpg",
      "alt_text": "",
      "position": 1,
      "is_primary": true
    }
  ],
  "created_at": "2026-07-23T14:30:14.156287Z",
  "updated_at": "2026-10-11T21:09:09.826034Z",
  "category_name": "Cafeteiras"
}

Campos da resposta

iduuid
Id do produto mestre.
skustring
Código do mestre. Ausente se não houver.
namestring
Nome.
descriptionstring
Descrição completa.
short_descriptionstring
Descrição curta.
category_iduuid
Categoria principal. Ausente se não houver.
category_namestring
Nome da categoria. Só na leitura de um mestre; ausente na lista.
brandstring
Marca (texto livre).
base_priceinteger
Preço de venda sugerido, em centavos.
main_image_urlstring
Imagem principal.
featuresobject
Características livres (nome para valor).
specificationsobject
Especificações livres (nome para valor).
statusstring
Situação do mestre: A ativo. O seller só enxerga mestres ativos.
offer_countinteger
Quantos produtos ativos (de qualquer seller) já vendem este mestre.
barcodestring
EAN/GTIN. Ausente se não houver.
quantityinteger
Estoque do próprio mestre.
min_quantityinteger
Quantidade mínima por pedido (0 sem regra).
max_quantityinteger
Quantidade máxima por pedido (0 sem regra).
quantity_stepinteger
Múltiplo de compra (0 sem regra).
imagesarray
Galeria: id, master_product_id, image_url, alt_text, position, is_primary. Na lista pode vir vazia.
additional_category_idsarray
Outras categorias (uuids). Ausente se não houver.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.
descriptionsarray
Traduções: lang_code, name, description, short_description. Ausente se não houver.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
404O recurso de produtos mestre está desligado nesta loja.{"error":"feature not enabled","detail":"enable master_products via admin settings"}
404Mestre inexistente ou excluído.{"error":"master product not found"}
500id que não é UUID, ou falha ao consultar.{"error":"failed to get master product","detail":"..."}
Mestre oculto ou pendente

A leitura individual só recusa mestres excluídos. Um mestre oculto ou pendente pode ser lido pelo id mesmo sem aparecer na lista.

Anterior
Catálogo mestre e visibilidade
Próxima
Clonar mestres
Nesta página
  • Listar mestres
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
  • Ler um mestre
  • Exemplo de requisição
  • Resposta
  • Erros